Describe the change
Add documentation to the Process-PSModule README covering best practices for shared test infrastructure when using BeforeAll.ps1 and AfterAll.ps1 setup/teardown scripts.
Problem Statement
Module authors using the BeforeAll.ps1 / AfterAll.ps1 setup and teardown feature lack guidance on how to structure shared test infrastructure for parallel cross-OS test runs. Without clear best practices, authors may:
- Use non-deterministic identifiers (
[guid]::NewGuid(), Get-Random) for shared resource names, making it impossible for test files on other runners to reference them
- Create expensive resources (e.g., repositories, databases) inside individual test files instead of sharing them
- Forget to clean up stale resources from previous failed runs
- Use inconsistent naming conventions that make cleanup difficult
Proposed documentation
The following best practices should be documented under the existing "Setup and Teardown Scripts" section:
-
Deterministic naming with $env:GITHUB_RUN_ID — use the stable run ID (shared across OS runners within a workflow run) to build resource names that can be referenced by all test files without passing state between jobs.
-
Stale resource cleanup — start BeforeAll.ps1 by removing any resources matching the naming prefix from previous failed runs before creating new ones.
-
Tests reference, don't create — test files should fetch shared resources by their deterministic name rather than provisioning their own. Only ephemeral test-specific resources (secrets, variables, temporary items) should be created within test files.
-
Naming conventions — provide a table of recommended patterns:
| Resource |
Pattern |
Example |
| Shared resource |
Test-{OS}-{RunID} |
Test-Linux-1234 |
| Extra resource |
Test-{OS}-{RunID}-{N} |
Test-Linux-1234-1 |
| Secret / variable |
{TestName}_{OS}_{RunID} |
Secrets_Linux_1234 |
| Environment |
{TestName}-{OS}-{RunID} |
Secrets-Linux-1234 |
-
Multi-context naming — when tests use multiple authentication contexts on the same runner, include a context identifier in the name to avoid collisions (e.g., Test-{OS}-{ContextID}-{RunID}).
Implementation
PR #285 implements this change.
Describe the change
Add documentation to the Process-PSModule README covering best practices for shared test infrastructure when using
BeforeAll.ps1andAfterAll.ps1setup/teardown scripts.Problem Statement
Module authors using the
BeforeAll.ps1/AfterAll.ps1setup and teardown feature lack guidance on how to structure shared test infrastructure for parallel cross-OS test runs. Without clear best practices, authors may:[guid]::NewGuid(),Get-Random) for shared resource names, making it impossible for test files on other runners to reference themProposed documentation
The following best practices should be documented under the existing "Setup and Teardown Scripts" section:
Deterministic naming with
$env:GITHUB_RUN_ID— use the stable run ID (shared across OS runners within a workflow run) to build resource names that can be referenced by all test files without passing state between jobs.Stale resource cleanup — start
BeforeAll.ps1by removing any resources matching the naming prefix from previous failed runs before creating new ones.Tests reference, don't create — test files should fetch shared resources by their deterministic name rather than provisioning their own. Only ephemeral test-specific resources (secrets, variables, temporary items) should be created within test files.
Naming conventions — provide a table of recommended patterns:
Test-{OS}-{RunID}Test-Linux-1234Test-{OS}-{RunID}-{N}Test-Linux-1234-1{TestName}_{OS}_{RunID}Secrets_Linux_1234{TestName}-{OS}-{RunID}Secrets-Linux-1234Multi-context naming — when tests use multiple authentication contexts on the same runner, include a context identifier in the name to avoid collisions (e.g.,
Test-{OS}-{ContextID}-{RunID}).Implementation
PR #285 implements this change.