Skip to content

📖 [Docs]: Add best practices for shared test infrastructure #286

@MariusStorhaug

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:

  1. 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.

  2. Stale resource cleanup — start BeforeAll.ps1 by removing any resources matching the naming prefix from previous failed runs before creating new ones.

  3. 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.

  4. 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
  5. 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.

Metadata

Metadata

Labels

documentationImprovements or additions to documentation

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions