Powershell-Pester-6

# PowerShell Pester v6 Testing Guidelines

This guide provides PowerShell-specific instructions for creating automated tests with the PowerShell Pester v6 module. Pester v6 runs on Windows PowerShell 5.1 and PowerShell 7.4+. Follow the general PowerShell scripting guidance in [powershell.instructions.md](./powershell.instructions.md).

Pester v6 is largely compatible with v5, but it makes several previously deprecated behaviours fail fast. Keep each test file self-contained and run the suite with the same PowerShell and Pester versions used by CI.

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 }
    }
}

Discovery and Run

- Pester v6 discovers and runs one file at a time. Do not rely on discovery-time side effects from another test file (for example, a global variable, current directory, or imported module).

- Use `BeforeDiscovery` for data needed to construct tests and `BeforeAll` to import modules or initialise runtime state for the file.

- Keep every test file independently runnable; place shared setup in a Pester configuration (`Run.BeforeContainer`) or a repository `Pester.BeforeContainer.ps1` when it truly applies to all files.

BeforeDiscovery {
    $cases = Get-Content "$PSScriptRoot/cases.json" | ConvertFrom-Json
}

BeforeAll {
    Import-Module "$PSScriptRoot/MyModule.psm1"
}

Describe 'MyModule' {
    It 'handles <Name>' -ForEach $cases { Invoke-Thing $Name | Should -Be 'ok' }
}

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`**: Classic assertion command (`Should -Be`, `Should -Throw`, etc.); existing v5 syntax remains supported

- **`Should-*`**: New v6 assertion commands (`Should-Be`, `Should-Throw`, etc.); adopt them deliberately, not as a required rename

- **`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 are available to child blocks (read-only); `BeforeEach`, `It`, and `AfterEach` share their block scope

- **One hook of each type**: A block may contain only one `BeforeAll`, `BeforeEach`, `AfterAll`, or `AfterEach`; combine setup when necessary

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 ca