Generate Pester 5.x Tests

When to Use

• User asks to generate, write, or create tests for PowerShell code
• User asks to add test coverage to existing modules or scripts
• User mentions Pester, mocking, code coverage, or unit/integration testing
• User says "test this function", "add tests", "write tests for X"

Prerequisites

• PowerShell 7+ or Windows PowerShell 5.1+
• Pester 5.5.0+ installed: Install-Module Pester -MinimumVersion 5.5.0 -Force
• Source code in ./src/ (or specify path)
• Tests output to ./tests/ (parallel directory structure)

Phase 1: Discovery — Scan the Codebase

Use AST to find all functions, their parameters, dependencies, and complexity:

# Discover all PowerShell source files
$sourceFiles = Get-ChildItem -Path ./src -Include '*.ps1','*.psm1' -Recurse

foreach ($file in $sourceFiles) {
    $ast = [System.Management.Automation.Language.Parser]::ParseFile(
        $file.FullName, [ref]$null, [ref]$null
    )

    # Find all function definitions
    $functions = $ast.FindAll({
        $args[0] -is [System.Management.Automation.Language.FunctionDefinitionAst]
    }, $true)

    # Find all command calls (dependencies to mock)
    $commands = $ast.FindAll({
        $args[0] -is [System.Management.Automation.Language.CommandAst]
    }, $true)

    Write-Host "$($file.Name): $($functions.Count) functions, $($commands.Count) commands"
}

Output: Test Creation Report — file count, function count, testability scores (0-100%), anti-patterns flagged.

Phase 2: Dependency Mapping — Build Mock Graph

For each function, identify what needs mocking:

Output: Dependency & Requirement Mapping Report — per-function parameters, return types, mock graph.

Phase 3: Test Points — Identify What to Test

For each function, define the test matrix:

Output: Test Points Identification Report — per-function test matrix with categories.

Phase 4: Test Generation — Write the Tests

Generate Pester 5.x test files following this exact structure:

#Requires -Modules Pester

BeforeAll {
    . $PSScriptRoot/../src/Get-PolicyCompliance.ps1
}

Describe 'Get-PolicyCompliance' -Tag 'Unit' {
    BeforeAll {
        # Always mock authentication
        Mock Connect-AzAccount { }
        Mock Get-AzContext {
            @{ Subscription = @{ Id = '00000000-0000-0000-0000-000000000000' } }
        }
    }

    Context 'When policy is compliant' {
        BeforeAll {
            Mock Get-AzPolicyState {
                [PSCustomObject]@{ ComplianceState = 'Compliant' }
            }
        }

        It 'Returns compliant status' {
            $result = Get-PolicyCompliance -PolicyName 'test-policy'
            $result.State | Should -Be 'Compliant'
        }

        It 'Calls Get-AzPolicyState exactly once' {
            Should -Invoke Get-AzPolicyState -Times 1 -Exactly
        }
    }

    Context 'Parameter validation' {
        It 'Throws when PolicyName is missing' {
            { Get-PolicyCompliance } | Should -Throw '*PolicyName*'
        }
    }
}

Non-Negotiable Rules

• BeforeAll for dot-sourcing (never script-scope)
• Should -BeTrue not Should -Be $true
• Should -BeNullOrEmpty not Should -Be $null
• Should -Invoke not Assert-MockCalled (deprecated)
• -Tag 'Unit' or -Tag 'Integration' on every Describe
• -TestCases or -ForEach for data-driven (no copy-paste It blocks)
• One test file per source file: Get-Policy.ps1 → Get-Policy.Tests.ps1

Phase 5: Run and Validate

$config = New-PesterConfiguration
$config.Run.Path = './tests'
$config.Run.PassThru = $true
$config.CodeCoverage.Enabled = $true
$config.CodeCoverage.Path = './src'
$config.CodeCoverage.OutputFormat = 'JaCoCo'
$config.CodeCoverage.OutputPath = './reports/coverage.xml'
$config.CodeCoverage.CoveragePercentTarget = 90
$config.TestResult.Enabled = $true
$config.TestResult.OutputFormat = 'NUnitXml'
$config.TestResult.OutputPath = './reports/test-results.xml'
$config.Output.Verbosity = 'Detailed'
$result = Invoke-Pester -Configuration $config

Output: Code Coverage Report — line/branch/function % vs targets, uncovered lines.

Phase 6: Fix Gaps (if coverage < 90%)

If tests fail or coverage is below target:

1. Analyze $result.CodeCoverage.CommandsMissed — which lines uncovered
2. If uncovered line is in if/else → add Context with Mock that triggers the branch
3. If uncovered line is in catch → add It with Mock that throws
4. If uncovered line is in switch → add -TestCases for each case value
5. Invoke tuner subagent for complex gap analysis

Output: Final Validation Report — test count, pass rate, coverage achieved, recommendations.

Context Management (Critical for Large Codebases)

• More than 3 source files → process ONE module at a time via subagents
• Each subagent gets a fresh context window (prevents crashes)
• Summarize results between modules to preserve context budget
• Chain: builder (generate) → reviewer (validate) → tuner (fix gaps)

Non-Negotiable Rules (From Production Testing)

1. -Scope Context on ALL Should -Invoke: When the function under test is called in BeforeAll, Should -Invoke defaults to It scope and reports 0 calls. Always add -Scope Context.

1. AST extraction for scripts with top-level code: If a .ps1 file has ANY code outside of functions (Write-Host, Read-Host, exit, variable assignments), do NOT dot-source it. Use AST ParseFile to extract only function definitions, then Invoke-Expression each one.

1. Replace exit with throw: exit is a PowerShell keyword that cannot be mocked. When extracting functions that contain exit N, replace with throw "Exit code: N" or return $N.

1. Wrap Group-Object in @(): ($data | Group-Object X).Count returns item count when there's a single group. Always use @($data | Group-Object X).Count to get group count.