---
name: powershell-pester-testing
description: "Use when: creating, reviewing, or migrating Pester tests for PowerShell modules, including Pester 5 or 6 discovery, BeforeAll, Describe, It, Should assertions, Mock, parameter filters, and test configuration."
argument-hint: "Command or test file to cover"
---

# PowerShell Pester Testing

Create reviewable tests without executing test or workspace code through the MCP server.

## Version Gate

1. Detect the intended Pester major version from dependency files, CI, build scripts, or an explicit repository requirement.
2. If the repository targets Pester 4 or earlier, do not write tests in that version. State that Pester 4 is unsupported by this skill, propose an explicit upgrade to Pester 5 as a separate step, and write new tests in Pester 5/6-compatible syntax only after the user confirms.
3. If the version is ambiguous, write syntax compatible with both Pester 5 and 6 and state that assumption.
4. For dual-compatible tests, use classic assertions such as `Should -Be`. Use v6 `Should-Be` and related `Should-*` commands only when Pester 6 is explicit.

## Workflow

1. Derive tests from observable behavior and public contracts, not implementation line coverage.
2. Name files `*.Tests.ps1` and keep each test file self-contained.
3. Import or dot-source code under test in `BeforeAll`, never at discovery scope. Put discovery-time data preparation in `BeforeDiscovery` when required.
4. Organize one public command per top-level `Describe`; use `Context` for parameter sets, states, or failure modes.
5. Keep each `It` focused on one behavior. Include success, validation, pipeline, error, and `WhatIf` behavior where relevant.
6. Mock only external boundaries such as network, filesystem, time, or another module. Do not mock the function being tested.
7. Give parameter-filtered mocks a default mock when unmatched calls must not reach the real command. Prefer `Should -Invoke` and `Should -InvokeVerifiable`; Pester 6 removes `Assert-MockCalled` and `Assert-VerifiableMock`.
8. Use `New-PesterConfiguration` for scripted CI configuration. Do not introduce legacy Pester 4 `Invoke-Pester` parameters.
9. When `psmcp-builtin` is available, read the test text and use `parse_script` to validate syntax. PSScriptAnalyzer can review style when separately run, but neither check proves tests pass.
10. Provide the exact `Invoke-Pester` command for a human or separately authorized execution environment to run. Never report tests as passing unless that command was actually executed and its result observed.

## Pester 6 Checks

- PowerShell 7.4 or later
- At most one setup/teardown block of each type per containing block
- Null or empty `-ForEach` data is either fixed or explicitly allowed
- Each file owns its discovery data and setup
- Mocks do not rely on unmatched calls falling through to real commands
- `Assert-MockCalled`, `Assert-VerifiableMock`, and `Set-ItResult -Pending` are absent

## Boundaries

- Pester tests can execute arbitrary accessible commands. `psmcp-builtin` does not run them.
- Do not fabricate coverage percentages or passing results.
- Do not silently migrate a repository between Pester major versions.

## Sources

- [Pester 6 quick start](https://pester.dev/docs/quick-start)
- [Pester 5 quick start](https://pester.dev/docs/v5/quick-start)
- [Pester 5 to 6 migration](https://pester.dev/docs/migrations/v5-to-v6)