-
Notifications
You must be signed in to change notification settings - Fork 0
Description
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.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:
Resource Pattern Example Shared resource Test-{OS}-{RunID}Test-Linux-1234Extra resource Test-{OS}-{RunID}-{N}Test-Linux-1234-1Secret / variable {TestName}_{OS}_{RunID}Secrets_Linux_1234Environment {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.