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

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions