Code Testing Extensions

PowerShell Extension

Language-specific guidance for PowerShell test generation using Pester v5.

Rule #0: Confirm the Test Target

If the prompt does not name a specific file (e.g. "test the repository", "cover one core module", "comprehensive suite"), do not assume the largest or top-level upstream code is the intended target. In real workflows the user usually wants to test code they have just added, and large upstream repos contain hundreds of scripts already covered by existing *.Tests.ps1 files.

Run these read-only discovery commands first — they are the deliberate exception to Rule #1's "before writing any test or running any command" rule, and their output is the ground truth Rule #1's reading is meant to interpret. Do not write or execute any tests until Rule #0 and Rule #1 are both complete.

Prefer targets that match all of:

1. Untracked or recently added (git status / git log --diff-filter=A).

2. Small and pure (a few hundred lines, no external state, no Invoke-WebRequest/registry/filesystem side effects).

3. Located under a conventional source root (tools/, src/, Public/, Private/, or the module root next to a .psd1).

4. Have no existing matching *.Tests.ps1 file.

If a .psd1 manifest's RootModule (or ModuleToProcess) points at a specific .psm1, that module is almost certainly the target — start there.

Test Placement Contract

Pester only discovers tests under the path passed to Invoke-Pester -Path (or the current directory when no path is given). Verification harnesses (CI, msbench, coverage tools) typically scope discovery to a single directory such as tools/ or tests/. Place every test file there, matching the existing convention in the repo:

A *.Tests.ps1 file placed outside the discovery root will be invisible to both Invoke-Pester and the harness.

First-Test Sanity Loop

After writing the first *.Tests.ps1 file — before writing any others:

1. Run Invoke-Pester -Path <dir> -PassThru and confirm the TotalCount is > 0. If it is 0, Pester is not discovering your file; fix the location, filename, or Describe/It structure before continuing.

2. Run the test (Invoke-Pester -Path <your.Tests.ps1> -Output Detailed); fix Import-Module / dot-source / BeforeAll errors before adding more tests.

3. Only then expand to cover the remaining functions.

This catches placement and discovery mistakes on turn 1 instead of after dozens of failed-test iterations.

Harness Discovery Check

Before reporting success, run the harness-equivalent discovery command from the repo root and confirm the test count went up by at least the number of tests you generated. CI/msbench/coverage harnesses do not know which directory you targeted with -Path; they invoke Pester from the repo root with default discovery, so a test that passes via Invoke-Pester -Path ./tools/Foo.Tests.ps1 is still worthless if Invoke-Pester from the repo root does not enumerate it.

# From repo root — mirrors what a generic harness sees
$result = Invoke-Pester -Configuration @{ Run = @{ PassThru = $true; SkipRun = $true } }
"$($result.TotalCount) tests discovered"

If the count did not increase, your *.Tests.ps1 file is outside the harness discovery root. Move it to the convention the repo's existing tests use (or, if there are no existing tests, prefer the repo root's tests/, Tests/, tst/, test/, or co-locate next to the source). Do not report success until the harness-equivalent command sees your new tests.

Rule #1: Investigate the Repo First

Before writing any test or running any command, read:

1. Existing tests — find *.Tests.ps1 files and copy their style (structure, assertions, mock approach, import method)

2. Module structure — look for .psd1 (manifest), .psm1 (root module), Public//Private/ organization

3. Build/test scripts — check for build.ps1, Invoke-Build (*.build.ps1), psake, or CI scripts

4. Shell target — check .psd1 for PowerShellVersion/CompatiblePSEditions, CI matrix for pwsh vs powershell.exe

Use the repo's existing test conventions. Only add Pester if the repo has no tests at all.

Build Commands

PowerShell is interpreted — no build step. If the repo has a build script, use it. Otherwise validate with:

• Module loads: Import-Module ./MyModule.psd1 -Force -ErrorAction Stop

• Script analyzer: Invoke-ScriptAnalyzer -Path ./src -Recurse (if PSScriptAnalyzer is available)

• Lint: Invoke-ScriptAnalyzer -Path path/to/file.ps1 -Fix

Test Commands

• Prefer the repo's build/test script over raw Invoke-Pester

• Use -Output Detailed during fix cycles, -Output Minimal for final validation

Project Layout and Imports

• All imports go in BeforeAll — never at script top level

• Use $PSScriptRoot or $PSCommandPath — never $MyInvocation.MyCommand.Path (returns empty in BeforeAll)

• Use -Force on Import-Module to pick up changes between runs

Test File Naming

• Files: *.Tests.ps1 — match existing convention (co-located vs Tests/ directory)

Pester v5 Discovery vs Run (Critical)

Pester v5 runs in two phases: Discovery (collects test metadata) then Run (executes tests). This is the #1 source of agent errors.

Rules:

• All setup code goes in BeforeAll or BeforeEach — never at script top level or loose inside Describe/Context

• Code directly inside Describe/Context (but outside It/Before*/After*) runs during Discovery — do not put setup, imports, or variable assignments there

• Data for -ForEach / -TestCases must be set in BeforeDiscovery, not BeforeAll (BeforeAll runs after discovery)

• -Skip:$condition evaluates at Discovery time — conditions from BeforeAll will be $null

• Use foreach loops for dynamic test generation only with BeforeDiscovery data

• Use TestDrive: for file-based tests instead of touching repo files — Pester cleans it up automatically

Parameterized Test Display Names

Apply Report-safe test names and result validation. Use an explicit safe Name/Case in -ForEach or -TestCases data and expand only that field in the It title. Do not expand arbitrary <Input> or <Expected> values into discovery/report metadata.

For a function whose contract reverses UTF-16 code units (not Unicode scalars), the reversed supplementary character is intentionally malformed UTF-16. Keep that expected value in the assertion, not the title:

Use Text for the data field, not Input: $Input is PowerShell's automatic pipeline-input variable and can hide the intended case value inside It.

BeforeDiscovery {
    $cases = @(
        @{
            Name = 'supplementary code-unit reversal'
            Text = [string]::Concat([char]0xD83D, [char]0xDE00)
            Expected = [string]::Concat([char]0xDE00, [char]0xD83D)
        }
        @{
            Name = 'isolated high surrogate'
            Text = [string][char]0xD800
            Expected = [string][char]0xD800
        }
    )
}

Describe 'Get-Reversed' {
    BeforeAll {
        Import-Module (Join-Path $PSScriptRoot '../tools/StringUtils.psm1') -Force
    }

    It 'reverses <Name>' -ForEach $cases {
        Get-Reversed -Value $Text | Should -BeExactly $Expected
    }
}

Reuse the repository's configured Pester TestResult export path and format when present and parse the resulting artifact before reporting success. A passing TotalCount/PassedCount does not prove JUnit export succeeded.

Common Errors

Mocking Rules

• Place mocks in BeforeAll (shared) or BeforeEach (reset per test)

• Mock where the command is called from — use -ModuleName to mock inside a module's scope

• Use -ParameterFilter for selective mocking (no param() block needed in v5)

• Verify calls with Should -Invoke — default scope inside It counts only that test's calls

• Use InModuleScope sparingly and as narrowly as possible — prefer Mock -ModuleName for testing via public API

• Inside mock bodies, use $PesterBoundParameters not $PSBoundParameters

• If a test needs more than 3 mocks, flag it as a design smell

Non-Obvious Assertions

Most Should operators are self-explanatory. These are the ones agents get wrong:

• Should -Throw requires a scriptblock: { risky-op } | Should -Throw — not a direct call

• Should -Contain is for collections — use Should -Be for scalar equality

• Should -HaveParameter validates cmdlet signatures: Get-Command X | Should -HaveParameter 'Name' -Mandatory

• Should -Invoke verifies mock calls: Should -Invoke Get-Item -Times 1 -Exactly

Cross-Platform

• Prefer pwsh (PowerShell 7+) unless the repo explicitly targets Windows PowerShell 5.1

• Use Join-Path for paths — never string concatenation with \

• Linux/macOS file systems are case-sensitive — match exact casing in imports and paths

• Windows ships Pester 3.4.0 — if v5 is needed: Install-Module Pester -Force -SkipPublisherCheck

• Check $PSVersionTable.PSEdition to detect Core vs Desktop

Skip Coverage Tools

Do not configure or run coverage tools (Pester CodeCoverage, JaCoCo export). Coverage is measured separately by the evaluation harness.