pester — Claude Code rule for Pester tests
This rule guides Claude Code in writing PowerShell tests with Pester. Use it to keep test files, mocks, and cleanup consistent with the repository.
MIT ★ 1,627 updated 2026-10-25
.github/instructions/pester.instructions.mdWhat pester does
The rule applies to **/*.Tests.ps1 and covers Pester 5.x conventions: test names and locations, file-level BeforeAll, Describe, Context, and It blocks, plus mock setup and verification. For scripts, it calls for dot-sourcing; modules use Import-Module, while class modules use using module at the top of the file.
Tests follow the repository’s directory layout, with a tests/ folder inside self-contained packages. The guidance also covers temporary files and module cleanup. Run tests with the repository’s configured script in package.json, or call Invoke-Pester directly. Tests that change environment variables use the save-and-restore pattern from GitMocks.psm1.
What it helps with
- name PowerShell test files to match production files
- place tests in a matching directory structure
- load scripts, modules, and class modules appropriately
- isolate tests with mocks and temporary files
Example prompts for the agent
- Write Pester tests for this PowerShell script using the repository’s conventions.
- Check
SecurityHelpers.Tests.ps1against the Pester rule and fix its structure. - Add mock-based tests for this function and verify calls with
Should -Invoke.
How to install pester
Manually: put the files in place
.github/instructions/pester.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.claude/rules/pester.mdThe paths frontmatter field limits the files: move applyTo from the source into paths
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/pester.mdcFrontmatter: description, globs, alwaysApply. Move applyTo from the source into globs, or the rule will not attach on its own
Manually: put the files in place
.devin/rules/pester.mdManually: put the files in place
.clinerules/pester.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about pester
How do I install pester in Claude Code?
Save the rule as .claude/rules/pester.md in your project.
What does the pester rule do?
It guides PowerShell tests using Pester 5.x, including file layout, test structure, imports, mocks, isolation, and cleanup.
How should I run tests under this rule?
Use the test script configured in package.json, or run Invoke-Pester directly.
Source text
pester.instructions.md · MIT
---
description: "Instructions for Pester testing conventions"
applyTo: '**/*.Tests.ps1'
---
# Pester Testing Instructions
Pester 5.x is the testing framework for all PowerShell code. Run tests through the repository's test runner (check `package.json` for a test script, or invoke `Invoke-Pester` directly if no runner is configured). Follow the repository's conventions for test execution.
## Test File Naming
Test files use a `.Tests.ps1` suffix matching the production file name:
| Production file | Test file |
|------------------------------|------------------------------------|
| `Test-DependencyPinning.ps1` | `Test-DependencyPinning.Tests.ps1` |
| `SecurityHelpers.psm1` | `SecurityHelpers.Tests.ps1` |
| `SecurityClasses.psm1` | `SecurityClasses.Tests.ps1` |
## Test File Location
**Mirror directory pattern**: Place test files in a `tests/` directory that mirrors the production directory layout. Each production subdirectory has a corresponding test subdirectory. Discover the repository's test directory structure by examining existing test files.
**Co-located tests**: Self-contained packages (such as skills or plugins) place tests inside the package directory rather than the mirror tree:
```text
package-root/
├── scripts/
│ ├── action.ps1
│ └── helpers.psm1
└── tests/
├── action.Tests.ps1
└── helpers.Tests.ps1
```
## Test File Header
Test files place `#Requires -Modules Pester` before the copyright header. This ordering differs from production scripts:
```powershell
#Requires -Modules Pester
# Copyright (c) 2026 Microsoft Corporation. All rights reserved.
# SPDX-License-Identifier: MIT
```
## SUT Import Patterns
Import the system under test in a file-level `BeforeAll` block. Use the pattern matching the production file type:
**Dot-source for scripts** (`.ps1`):
```powershell
BeforeAll {
. (Join-Path $PSScriptRoot '../../security/Test-DependencyPinning.ps1')
}
```
**Import-Module for modules** (`.psm1`):
```powershell
BeforeAll {
Import-Module (Join-Path $PSScriptRoot '../../security/Modules/SecurityHelpers.psm1') -Force
}
```
**using module for class modules** (parse-time type resolution):
```powershell
using module ..\..\security\Modules\SecurityClasses.psm1
```
The `using module` statement appears at the top of the file outside any block because PowerShell processes it at parse time.
## BeforeAll Setup
File-level `BeforeAll` initializes the test environment. Common activities include SUT import, mock module import, fixture path resolution, and output suppression:
```powershell
BeforeAll {
. (Join-Path $PSScriptRoot '../../security/Test-DependencyPinning.ps1')
Import-Module (Join-Path $PSScriptRoot '../../security/Modules/SecurityHelpers.psm1') -Force
Import-Module (Join-Path $PSScriptRoot '../Mocks/GitMocks.psm1') -Force
$script:FixtureRoot = Join-Path $PSScriptRoot '../fixtures/Security'
Mock Write-Host {}
Mock Write-CIAnnotation {} -ModuleName SecurityHelpers
}
```
## Describe, Context, and It Blocks
All `Describe` blocks require `-Tag 'Unit'`. The pester configuration excludes `Integration` and `Slow` tags by default:
```powershell
Describe 'FunctionName' -Tag 'Unit' {
Context 'when input is valid' {
It 'Returns expected output' {
Get-Something -Path 'test' | Should -Be 'result'
}
}
}
```
`Context` groups related scenarios. Each `It` tests a single behavior with a descriptive sentence name.
## Data-Driven Tests
Use `-ForEach` on `It` blocks for parameterized testing:
```powershell
It 'Accepts valid type <Value>' -ForEach @(
@{ Value = 'Unpinned' }
@{ Value = 'Stale' }
@{ Value = 'VersionMismatch' }
) {
$v = [DependencyViolation]::new()
$v.ViolationType = $Value
$v.ViolationType | Should -Be $Value
}
```
## Mock Patterns
**Output suppression**: Empty scriptblock mocks prevent console noise:
```powershell
Mock Write-Host {}
```
**Module-scoped mocks**: `-ModuleName` injects mocks into modules under test:
```powershell
Mock Write-CIAnnotation {} -ModuleName SecurityHelpers
```
**Parameter-filtered mocks**: `-ParameterFilter` targets specific invocations:
```powershell
Mock git {
$global:LASTEXITCODE = 0
return 'abc123'
} -ModuleName LintingHelpers -ParameterFilter {
$args[0] -eq 'merge-base'
}
```
## Mock Verification
Use `Should -Invoke` to verify mock calls:
```powershell
Should -Invoke Write-CIAnnotation -ModuleName SecurityHelpers -Times 1 -Exactly
Should -Invoke Write-CIAnnotation -ModuleName SecurityHelpers -ParameterFilter {
$Level -eq 'Warning'
}
```
## Test Isolation
**`$TestDrive`**: Pester-managed temp directory, automatically cleaned per `Describe`:
```powershell
$testDir = Join-Path $TestDrive 'test-collection'
New-Item -ItemType Directory -Path $testDir -Force
```
**`New-TemporaryFile` with try/finally**: Manual temp file management when `$TestDrive` is insufficient:
```powershell
$tempFile = New-TemporaryFile
try {
# test using $tempFile
}
finally {
Remove-Item $tempFile -Force -ErrorAction SilentlyContinue
}
```
**`$script:` scope**: Shares state across `It` blocks within a `Describe` or `Context`:
```powershell
BeforeAll {
$script:result = Get-Something -Path 'test'
}
It 'Returns correct name' {
$script:result.Name | Should -Be 'expected'
}
```
## Environment Save and Restore
Tests modifying environment variables use the `GitMocks.psm1` save/restore pattern:
```powershell
BeforeAll {
Import-Module "$PSScriptRoot/../Mocks/GitMocks.psm1" -Force
}
BeforeEach {
Save-CIEnvironment
$script:MockFiles = Initialize-MockCIEnvironment
}
AfterEach {
Remove-MockCIFiles -MockFiles $script:MockFiles
Restore-CIEnvironment
}
```
## Cleanup
Remove imported modules in `AfterAll` to prevent state leakage between test files:
```powershell
AfterAll {
Remove-Module SecurityHelpers -Force -ErrorAction SilentlyContinue
Remove-Module GitMocks -Force -ErrorAction SilentlyContinue
}
```
## Assertion Reference
| Assertion | Usage |
|-------------------------------|-------------------------|
| `Should -Be` | Exact value equality |
| `Should -BeExactly` | Case-sensitive equality |
| `Should -BeTrue` / `-BeFalse` | Boolean checks |
| `Should -BeNullOrEmpty` | Null or empty string |
| `Should -Not -BeNullOrEmpty` | Non-null and non-empty |
| `Should -Match` | Regex matching |
| `Should -BeLike` | Wildcard matching |
| `Should -Contain` | Collection membership |
| `Should -BeOfType` | Type assertion |
| `Should -HaveCount` | Collection length |
| `Should -Throw` | Exception expected |
| `Should -Not -Throw` | No exception expected |
| `Should -BeGreaterThan` | Numeric comparison |
| `Should -BeLessThan` | Numeric comparison |
| `Should -Invoke` | Mock call verification |
## Running Tests
Check `package.json` for a test runner script (common name: `test:ps`). If a runner is configured, use it to execute tests:
```bash
# Example: run all tests via the repository's test runner
npm run test:ps
# Example: run tests for a specific directory or file
npm run test:ps -- -TestPath "path/to/tests/"
```
If no runner is configured, invoke Pester directly:
```powershell
Invoke-Pester -Path './tests/' -Output Detailed
```
After execution, check the repository's log or output directory for structured test results (such as summary and failure JSON files) when available.
## Complete Test Example
<!-- <template-complete-test> -->
```powershell
#Requires -Modules Pester
# Copyright (c) Microsoft Corporation.
# SPDX-License-Identifier: MIT
BeforeAll {
. (Join-Path $PSScriptRoot '../../linting/Invoke-Linter.ps1')
Import-Module (Join-Path $PSScriptRoot '../Mocks/GitMocks.psm1') -Force
$script:FixtureRoot = Join-Path $PSScriptRoot '../fixtures/Linting'
Mock Write-Host {}
}
Describe 'Invoke-Linter' -Tag 'Unit' {
Context 'when input file is valid' {
BeforeAll {
$script:result = Invoke-Linter -Path (Join-Path $script:FixtureRoot 'valid.md')
}
It 'Returns zero violations' {
$script:result.Violations | Should -HaveCount 0
}
It 'Sets status to pass' {
$script:result.Status | Should -Be 'Pass'
}
}
Context 'when input file has errors' {
BeforeAll {
$script:result = Invoke-Linter -Path (Join-Path $script:FixtureRoot 'invalid.md')
}
It 'Returns violations' {
$script:result.Violations | Should -Not -BeNullOrEmpty
}
It 'Includes file path in each violation' {
$script:result.Violations | ForEach-Object {
$_.File | Should -Not -BeNullOrEmpty
}
}
}
}
AfterAll {
Remove-Module GitMocks -Force -ErrorAction SilentlyContinue
}
```
<!-- </template-complete-test> -->
© microsoft · MIT · microsoft/hve-core