Pester Should Migration

Pester Should migration

Convert classic space-separated Pester assertions such as Should -Be to the Pester v6 command form such as Should-Be, using behavior-aware mappings instead of blind text replacement.

When to invoke

• "Convert these Pester assertions to Should-* syntax."
• "Migrate Should -Be to Pester v6 style."
• "Rewrite Should -Not -Be calls in these .Tests.ps1 files."
• "Modernize Pester v5 assertions without changing test behavior."
• "Enable Should.DisableV5 after converting assertions."

Inputs

Use $ARGUMENTS as the file, folder, or suite scope to migrate. If $ARGUMENTS is empty, inspect the user's selected context or ask for a target before editing. Limit changes to PowerShell files, especially *.Tests.ps1 and relevant .ps1 helpers.

Prerequisites and context

• Requires Pester v6+ for the new Should-* commands.
• The classic Should -Be style still works in v6, so migration is optional and incremental.
• Verified guidance originated against Pester 6.0.0-rc2; confirm current command behavior when exact semantics matter.
• Use the companion pester-migration skill when the suite also needs runtime, mock, or config migration across v3→v4→v5→v6.

Progressive disclosure and bundled resources

• references/assertion-map.md: full operator-by-operator conversion table with before/after examples and workarounds.

Load it for any operator not listed in the quick mapping or when a behavioral gotcha applies.

Conversion map

Procedure

1. Search only the requested scope for Should -, Should -Not -, and Assert-MockCalled in *.Tests.ps1 and .ps1 files.
2. Apply mechanical mappings only where the operator has identical behavior.
3. Stop and choose by intent for case sensitivity, truthiness, null-or-empty, collections, pipeline unwrapping, Should -Exist, file-content assertions, and Should -BeIn.
4. Run Invoke-Pester -Path ./tests or the smallest equivalent suite command.
5. If the suite is fully migrated and the user wants enforcement, set:

$config = New-PesterConfiguration
$config.Should.DisableV5 = $true

Behavioral gotchas

Compatibility terminology

Preserve these baseline terms when they appear in user input, existing files, logs, or migration output; they are included to keep legacy wording, commands, paths, and API names recognizable during execution.

• ->
• and
• as
• $collection | Should-ContainCollection $value
• $false
• $null
• $true
• $value | Should -BeIn $collection
• $x | Should-Be 1
• (Get-Content $p -Raw) | Should-MatchString 're'
• ). The new
• *.ps1
• , and a typed collection (
• -Actual
• -BeFalse
• -Because
• -Not
• 1, 2, 3 | Should-ContainCollection @(1, 2)
• Should
• Should -*
• Should -Contain
• Should -Not -BeNullOrEmpty
• Should-Be -Actual $x -Expected 1
• Should-HaveType
• Should-NotBe
• Should-NotBeEmptyString
• Should-NotBeNull
• Should-NotBeWhiteSpaceString
• Test-Path $p | Should-BeTrue
• [object[]]
• actual/expected
• case-sensitive
• https://pester.dev/docs/assertions/should-command
• https://pester.dev/docs/commands/Should-Be
• https://pester.dev/docs/migrations/v5-to-v6
• re-check
• re-collected
• single-item
• step-3--check-the-behavioral-gotchas-do-not-skip
• type-aware
• whole-collection

Output template

## Pester Should migration result

**Status:** complete | needs human decision | blocked
**Scope:** `$ARGUMENTS`

### Assertion changes
| File | Converted | Left classic | Reason |
| --- | ---: | ---: | --- |
| `<file>.Tests.ps1` | <count> | <count> | <Should -Exist, BeNullOrEmpty decision, or none> |

### Validation
- `Invoke-Pester -Path ./tests`: <pass/fail/not run>

### Human decisions
- <truthy/falsy, null-or-empty, collection, or direction choice>

Quality gate

• $ARGUMENTS or selected scope was consumed and limited to PowerShell test targets.
• references/assertion-map.md was used for non-trivial operators.
• No behavioral gotcha was converted by blind rename.
• Should -Exist and Should -FileContentMatch* were kept or rewritten intentionally.
• Invoke-Pester or the suite's existing test command was run after changes.
• Any Should.DisableV5 enforcement happened only after remaining classic assertions were addressed.

References

• Should-Be command
• Should assertions concept
• Pester v5 to v6 migration