Pester Unit Testing for PowerShell

Pester is PowerShell's ubiquitous test and mock framework. Pester 5+ uses a two-phase execution model (Discovery → Run) that requires specific patterns for reliable tests.

TDD Cycle

Red – Write a failing test describing expected behavior
Green – Implement minimal code to pass
Refactor – Clean up while keeping tests green

Test File Structure

Test files use *.Tests.ps1 naming convention. Place alongside source files:

src/
├── Get-Widget.ps1
└── Get-Widget.Tests.ps1

Basic Template

BeforeAll {
    . $PSCommandPath.Replace('.Tests.ps1', '.ps1')
}

Describe 'Get-Widget' {
    Context 'when called with valid ID' {
        It 'returns widget object' {
            $result = Get-Widget -Id 42
            $result.Id | Should -Be 42
        }
    }

    Context 'when widget does not exist' {
        It 'throws not found error' {
            { Get-Widget -Id 9999 } | Should -Throw -ErrorId 'WidgetNotFound'
        }
    }
}

Block Hierarchy

| Block | Purpose | Scope | |-------|---------|-------| | Describe | Top-level grouping (1 per function/feature) | Container | | Context | Scenario grouping ("when X", "with Y") | Sub-container | | It | Single test case with assertions | Test | | BeforeAll | Run once before all tests in block | Setup | | BeforeEach | Run before each It | Per-test setup | | AfterEach | Run after each It (guaranteed) | Per-test cleanup | | AfterAll | Run once after all tests (guaranteed) | Final cleanup |

Discovery vs Run Phase (Critical)

Pester 5 executes in two phases:

Discovery – Scans to find all tests (does NOT run It blocks)
Run – Executes tests with setup/teardown

Rule: Put ALL code inside It, BeforeAll, BeforeEach, AfterEach, AfterAll, or BeforeDiscovery.

# ❌ WRONG - runs during Discovery, $data is null in Run phase
$data = Get-ExpensiveData
Describe 'Tests' {
    It 'works' { $data | Should -Not -BeNull }  # FAILS!
}

# ✅ CORRECT - use BeforeAll
Describe 'Tests' {
    BeforeAll { $script:data = Get-ExpensiveData }
    It 'works' { $script:data | Should -Not -BeNull }
}

For dynamic test generation, use BeforeDiscovery:

BeforeDiscovery {
    $testCases = @('file1.ps1', 'file2.ps1')
}

Describe 'Validate <_>' -ForEach $testCases {
    BeforeAll { $file = $_ }
    It 'has valid syntax' { ... }
}

Mocking

Mock any PowerShell command within test scope:

Describe 'Send-Report' {
    BeforeAll {
        Mock Send-MailMessage {}
        Mock Get-Date { return [DateTime]'2024-01-15' }
    }

    It 'sends email with correct subject' {
        Send-Report -Title 'Summary'
        Should -Invoke Send-MailMessage -Times 1 -ParameterFilter {
            $Subject -like '*Summary*'
        }
    }
}

Parameter Filters

Create conditional mocks for different inputs:

Mock Get-Service { @{ Status = 'Running' } } -ParameterFilter { $Name -eq 'BITS' }
Mock Get-Service { @{ Status = 'Stopped' } } -ParameterFilter { $Name -eq 'Spooler' }
Mock Get-Service { @{ Status = 'Unknown' } }  # Default fallback

Mocking Native Commands (bash, git, curl)

Native commands work via $args:

Describe 'Git Operations' {
    BeforeAll { Mock git { 'mocked-output' } }

    It 'calls git with correct args' {
        Invoke-GitPush -Branch 'main'
        Should -Invoke git -ParameterFilter {
            $args[0] -eq 'push' -and $args[1] -eq 'origin'
        }
    }
}

Module Internals

Use -ModuleName for functions inside modules:

Mock Get-InternalData { 'mocked' } -ModuleName MyModule

Use InModuleScope for private/non-exported functions:

InModuleScope MyModule {
    Mock Write-Log {}
    Invoke-PrivateFunction
    Should -Invoke Write-Log
}

Test Isolation

TestDrive (Filesystem)

Temporary PSDrive auto-cleaned per block:

Describe 'File Processing' {
    BeforeAll {
        Set-Content 'TestDrive:\config.json' -Value '{"key":"value"}'
    }

    It 'reads config' {
        $cfg = Get-Content 'TestDrive:\config.json' | ConvertFrom-Json
        $cfg.key | Should -Be 'value'
    }
}

Use $TestDrive for .NET APIs requiring full paths:

$path = Join-Path $TestDrive 'file.txt'
[System.IO.File]::WriteAllText($path, 'content')

TestRegistry (Windows)

Temporary registry hive:

BeforeAll {
    New-Item -Path 'TestRegistry:\MyApp'
    New-ItemProperty -Path 'TestRegistry:\MyApp' -Name 'Setting' -Value 'Test'
}

Environment Variables

Save and restore manually:

BeforeEach {
    $script:oldEnv = $env:MY_VAR
    $env:MY_VAR = 'test-value'
}

AfterEach {
    $env:MY_VAR = $script:oldEnv
}

Output Capture

Stream Redirection

| Stream | Command | Capture | |--------|---------|---------| | 1 (Success) | Write-Output | Direct assignment | | 2 (Error) | Write-Error | 2>&1 or -ErrorVariable | | 3 (Warning) | Write-Warning | 3>&1 | | 4 (Verbose) | Write-Verbose | 4>&1 with -Verbose | | 6 (Information) | Write-Host | 6>&1 |

It 'captures Write-Host' {
    $result = MyFunction 6>&1
    $result | Should -Contain 'expected message'
}

ANSI Color Stripping

function Remove-AnsiCodes {
    param([string]$Text)
    $Text -replace '\x1b\[[0-9;]*[a-zA-Z]', ''
}

$clean = Remove-AnsiCodes $coloredOutput

Or configure Pester: $config.Output.RenderMode = 'Plaintext'

Parameterized Tests

Use -ForEach or -TestCases:

Describe 'Add-Numbers' {
    It 'adds <a> + <b> = <expected>' -TestCases @(
        @{ a = 2; b = 3; expected = 5 }
        @{ a = -1; b = 1; expected = 0 }
    ) {
        Add-Numbers $a $b | Should -Be $expected
    }
}

Running Specific Tests

Name Filters

Invoke-Pester -FullNameFilter '*Get-Widget*returns*'

Skip

It 'admin only' -Skip:(-not (Test-IsAdmin)) { ... }

Code Coverage

$config = New-PesterConfiguration
$config.CodeCoverage.Enabled = $true
$config.CodeCoverage.Path = './src'
$config.CodeCoverage.OutputFormat = 'JaCoCo'
$config.CodeCoverage.OutputPath = 'coverage.xml'
$config.CodeCoverage.CoveragePercentTarget = 80

Invoke-Pester -Configuration $config

CI Reports (JUnit/NUnit)

$config = New-PesterConfiguration
$config.TestResult.Enabled = $true
$config.TestResult.OutputFormat = 'JUnitXml'  # or NUnitXml
$config.TestResult.OutputPath = 'test-results.xml'
$config.Run.Exit = $true  # Exit code for CI

Invoke-Pester -Configuration $config

Additional Resources

references/anti-patterns.md - Common mistakes and pitfalls with solutions
references/mocking-patterns.md - Advanced mocking scenarios (APIs, databases, native commands)
references/ci-integration.md - GitHub Actions, Azure DevOps, GitLab CI, Jenkins examples

Common Anti-Patterns

See references/anti-patterns.md for detailed examples.

Quick checklist:

❌ Code outside Pester blocks
❌ Tests depending on each other
❌ Using foreach instead of -ForEach
❌ Mocking the function under test
❌ Over-specifying mock interactions
❌ Global variables in tests

Assertion Quick Reference

| Assertion | Description | |-----------|-------------| | Should -Be | Case-insensitive equality | | Should -BeExactly | Case-sensitive equality | | Should -BeTrue / -BeFalse | Boolean | | Should -BeNullOrEmpty | Null/empty check | | Should -BeOfType | Type checking | | Should -Contain | Collection contains | | Should -Match | Regex (case-insensitive) | | Should -BeLike | Wildcard match | | Should -Throw | Exception expected | | Should -Exist | Path exists | | Should -HaveCount | Collection count | | Should -Invoke | Mock was called |

Full assertion list: Get-ShouldOperator

pester