Powershell Pester 5

PowerShell Pester v5 Testing Guidelines

This guide provides PowerShell-specific instructions for creating automated tests using PowerShell Pester v5 module. Follow PowerShell cmdlet development guidelines in powershell.instructions.md for general PowerShell scripting best practices.

File Naming and Structure

• File Convention: Use *.Tests.ps1 naming pattern
• Placement: Place test files next to tested code or in dedicated test directories
• Import Pattern: Use BeforeAll { . $PSScriptRoot/FunctionName.ps1 } to import tested functions
• No Direct Code: Put ALL code inside Pester blocks (BeforeAll, Describe, Context, It, etc.)

Test Structure Hierarchy

BeforeAll { # Import tested functions }
Describe 'FunctionName' {
    Context 'When condition' {
        BeforeAll { # Setup for context }
        It 'Should behavior' { # Individual test }
        AfterAll { # Cleanup for context }
    }
}

Core Keywords

• Describe: Top-level grouping, typically named after function being tested
• Context: Sub-grouping within Describe for specific scenarios
• It: Individual test cases, use descriptive names
• Should: Assertion keyword for test validation
• BeforeAll/AfterAll: Setup/teardown once per block
• BeforeEach/AfterEach: Setup/teardown before/after each test

Setup and Teardown

• BeforeAll: Runs once at start of containing block, use for expensive operations
• BeforeEach: Runs before every It in block, use for test-specific setup
• AfterEach: Runs after every It, guaranteed even if test fails
• AfterAll: Runs once at end of block, use for cleanup
• Variable Scoping: BeforeAll variables available to child blocks (read-only), BeforeEach/It/AfterEach share same scope

Assertions (Should)

• Basic Comparisons: -Be, -BeExactly, -Not -Be
• Collections: -Contain, -BeIn, -HaveCount
• Numeric: -BeGreaterThan, -BeLessThan, -BeGreaterOrEqual
• Strings: -Match, -Like, -BeNullOrEmpty
• Types: -BeOfType, -BeTrue, -BeFalse
• Files: -Exist, -FileContentMatch
• Exceptions: -Throw, -Not -Throw

Mocking

• Mock CommandName { ScriptBlock }: Replace command behavior
• -ParameterFilter: Mock only when parameters match condition
• -Verifiable: Mark mock as requiring verification
• Should -Invoke: Verify mock was called specific number of times
• Should -InvokeVerifiable: Verify all verifiable mocks were called
• Scope: Mocks default to containing block scope

Mock Get-Service { @{ Status = 'Running' } } -ParameterFilter { $Name -eq 'TestService' }
Should -Invoke Get-Service -Exactly 1 -ParameterFilter { $Name -eq 'TestService' }

Test Cases (Data-Driven Tests)

Use -TestCases or -ForEach for parameterized tests:

It 'Should return <Expected> for <Input>' -TestCases @(
    @{ Input = 'value1'; Expected = 'result1' }
    @{ Input = 'value2'; Expected = 'result2' }
) {
    Get-Function $Input | Should -Be $Expected
}

Data-Driven Tests

• -ForEach: Available on Describe, Context, and It for generating multiple tests from data
• -TestCases: Alias for -ForEach on It blocks (backwards compatibility)
• Hashtable Data: Each item defines variables available in test (e.g., @{ Name = 'value'; Expected = 'result' })
• Array Data: Uses $_ variable for current item
• Templates: Use <variablename> in test names for dynamic expansion

# Hashtable approach
It 'Returns <Expected> for <Name>' -ForEach @(
    @{ Name = 'test1'; Expected = 'result1' }
    @{ Name = 'test2'; Expected = 'result2' }
) { Get-Function $Name | Should -Be $Expected }

# Array approach
It 'Contains <_>' -ForEach 'item1', 'item2' { Get-Collection | Should -Contain $_ }

Tags

• Available on: Describe, Context, and It blocks
• Filtering: Use -TagFilter and -ExcludeTagFilter with Invoke-Pester
• Wildcards: Tags support -like wildcards for flexible filtering

Describe 'Function' -Tag 'Unit' {
    It 'Should work' -Tag 'Fast', 'Stable' { }
    It 'Should be slow' -Tag 'Slow', 'Integration' { }
}

# Run only fast unit tests
Invoke-Pester -TagFilter 'Unit' -ExcludeTagFilter 'Slow'

Skip

• -Skip: Available on Describe, Context, and It to skip tests
• Conditional: Use -Skip:$condition for dynamic skipping
• Runtime Skip: Use Set-ItResult -Skipped during test execution (setup/teardown still run)

It 'Should work on Windows' -Skip:(-not $IsWindows) { }
Context 'Integration tests' -Skip { }

Error Handling

• Continue on Failure: Use Should.ErrorAction = 'Continue' to collect multiple failures
• Stop on Critical: Use -ErrorAction Stop for pre-conditions
• Test Exceptions: Use { Code } | Should -Throw for exception testing

Best Practices

• Descriptive Names: Use clear test descriptions that explain behavior
• AAA Pattern: Arrange (setup), Act (execute), Assert (verify)
• Isolated Tests: Each test should be independent
• Avoid Aliases: Use full cmdlet names (Where-Object not ?)
• Single Responsibility: One assertion per test when possible
• Test File Organization: Group related tests in Context blocks. Context blocks can be nested.

Example Test Pattern

BeforeAll {
    . $PSScriptRoot/Get-UserInfo.ps1
}

Describe 'Get-UserInfo' {
    Context 'When user exists' {
        BeforeAll {
            Mock Get-ADUser { @{ Name = 'TestUser'; Enabled = $true } }
        }

        It 'Should return user object' {
            $result = Get-UserInfo -Username 'TestUser'
            $result | Should -Not -BeNullOrEmpty
            $result.Name | Should -Be 'TestUser'
        }

        It 'Should call Get-ADUser once' {
            Get-UserInfo -Username 'TestUser'
            Should -Invoke Get-ADUser -Exactly 1
        }
    }

    Context 'When user does not exist' {
        BeforeAll {
            Mock Get-ADUser { throw "User not found" }
        }

        It 'Should throw exception' {
            { Get-UserInfo -Username 'NonExistent' } | Should -Throw "*not found*"
        }
    }
}

Configuration

Configuration is defined outside test files when calling Invoke-Pester to control execution behavior.

# Create configuration (Pester 5.2+)
$config = New-PesterConfiguration
$config.Run.Path = './Tests'
$config.Output.Verbosity = 'Detailed'
$config.TestResult.Enabled = $true
$config.TestResult.OutputFormat = 'NUnitXml'
$config.Should.ErrorAction = 'Continue'
Invoke-Pester -Configuration $config

Key Sections: Run (Path, Exit), Filter (Tag, ExcludeTag), Output (Verbosity), TestResult (Enabled, OutputFormat), CodeCoverage (Enabled, Path), Should (ErrorAction), Debug