Test Analysis Extensions

PowerShell Test Framework Reference (Pester v5)

Reference data for analyzing PowerShell test code. Used by the polyglot test analysis skills.

Capability tags

Test File Identification

Pester v5+ uses block-scoped variables — Describe/Context blocks run during discovery; BeforeAll is required to initialize variables used by It blocks.

Assertion APIs

Should -Invoke counts as a state/side-effect assertion — do not flag tests that only verify mock calls as assertion-free.

Sleep/Delay Patterns

Skip/Ignore Annotations

Exception Handling — Idiomatic Alternatives

# Preferred: Should -Throw with scriptblock
{ Get-Item -Path 'C:\nonexistent' -ErrorAction Stop } |
    Should -Throw -ErrorId 'PathNotFound,Microsoft.PowerShell.Commands.GetItemCommand'

# With pattern match on message:
{ Invoke-MyFunc -InvalidArg } | Should -Throw -ExpectedMessage '*invalid*'

# Not throwing:
{ Invoke-MyFunc -ValidArg } | Should -Not -Throw

Flag tests using try { ... } catch { Write-Error ... } patterns without subsequent Should assertion.

Mystery Guest — Common PowerShell Patterns

Integration Test Markers

• File suffix: *.Integration.Tests.ps1, *.E2E.Tests.ps1

• -Tag 'Integration' / -Tag 'E2E'

• Folder convention: tests/integration/, tests/e2e/

• Real Azure/AWS module calls (Connect-AzAccount, Get-S3Object) imply integration

Setup/Teardown

Pester v5 requires BeforeAll to initialize variables used in It blocks (discovery vs run separation). A common mistake: defining variables at Describe scope and using them inside It — they will be $null at run time.

Tag/Trait Attributes (for test-tagging)

Language-specific calibration notes

• Pester v5 vs v4 scoping differences: v4 tests using $script: variables shared between It blocks won't work in v5 the same way. Note as migration debt if both styles coexist.

• InModuleScope is the canonical way to test internal/non-exported module functions — not an implementation-coupling smell.

• Mock cmdlet intercepts ANY function in scope; tests that mock built-in cmdlets (Get-ChildItem, etc.) without ParameterFilter are over-broad — flag as smell.

• TestDrive: is an automatically-created temporary directory unique to each test — not a Mystery Guest.

• Pester Should -Invoke (v5) / Assert-MockCalled (v4) are state/side-effect assertions.

• Set-StrictMode -Version Latest in tests is a hygiene practice — acknowledge as positive.

• Set-ItResult -Inconclusive marks a test as inconclusive (not failure, not skip).

• -ForEach / -TestCases are parametrized — NOT duplicate tests.

• PSScriptAnalyzer integration: tests that lint themselves (Invoke-ScriptAnalyzer) are quality-gate tests, not analyzer code.

• Pester v6 (preview) changes some APIs; if the project targets v6, double-check assertion forms.