Pester Should Migration

Step 3 — Check the behavioral gotchas (do NOT skip)

These do not translate by a plain rename. Read each before converting:

1. Case sensitivity. Classic Should -Be is case-insensitive on strings; so is Should-Be. But classic Should -BeExactly (case-sensitive) has no plain equivalent — use Should-BeString -CaseSensitive. (Should-Be is never case-sensitive.) Same pattern for BeLikeExactly → Should-BeLikeString -CaseSensitive and MatchExactly → Should-MatchString -CaseSensitive.
2. Truthy vs. true. Classic Should -BeTrue / -BeFalse accept any truthy / falsy value (1, 'x', 0, '', $null, @()). The new Should-BeTrue / Should-BeFalse are strict (exactly $true / $false). To preserve the old loose behavior use Should-BeTruthy / Should-BeFalsy. Only use the strict ones when the value really is a boolean.
3. BeNullOrEmpty has no single equivalent. Pick by intent: $null → Should-BeNull; empty string → Should-BeEmptyString; empty collection → Should-BeCollection -Count 0; broad "falsy" → Should-BeFalsy. The negation Should -Not -BeNullOrEmpty similarly splits into Should-NotBeNull / Should-NotBeEmptyString / Should-NotBeWhiteSpaceString.
4. Collections. Classic Should -Be also compares arrays; the new Should-Be is a value assertion and errors if -Expected is a collection ("You provided a collection to the -Expected parameter"). Use Should-BeCollection to compare arrays. Should -Contain (single-item membership) → Should-ContainCollection. The new command also takes a collection of expected items and checks they are all present, in the right order (1, 2, 3 | Should-ContainCollection @(1, 2)). For exact, whole-collection equality use Should-BeCollection instead.
5. Pipeline unwrapping. The pipeline unwraps input: a value assertion sees @(1) as 1 and @() as $null, and a typed collection ([int[]]) is re-collected as [object[]]. When the exact value or concrete collection type matters (e.g. Should-HaveType), pass it with -Actual instead of piping.
6. No Should-* equivalent. Should -Exist and the Should -FileContentMatch* family have no new counterpart. Either keep the classic assertion, or rewrite with PowerShell: Test-Path $p | Should-BeTrue, (Get-Content $p -Raw) | Should-MatchString 're'.
7. Should -BeIn direction. No Should-BeIn. Reverse the operands: $value | Should -BeIn $collection → $collection | Should-ContainCollection $value (note the actual/expected swap), or keep the classic form.

Step 4 — Verify

Run the suite and confirm it's still green — the new messages differ, but passes must stay passes:

Invoke-Pester -Path ./tests

If a converted assertion newly fails, re-check the gotchas above (most often #2 truthy/falsy, #3 null-or-empty, or #4 collections).

Step 5 — (Optional) Enforce the new style

Once a suite is fully migrated, switch off the classic syntax so it can't creep back:

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

With this set, any remaining Should -Be throws and points at the Should-Be form.

Output

Summarize what changed: files touched, count of assertions converted, any classic assertions intentionally left (e.g. Should -Exist), and any conversions that need a human decision (truthy/falsy, null-or-empty, collection semantics).

Reference

• references/assertion-map.md — full operator-by-operator table with before/after examples and workarounds.
• Live command reference: https://pester.dev/docs/commands/Should-Be (swap in any Should-* name) for exact parameters and examples.
• Concepts: https://pester.dev/docs/assertions/should-command (value vs. collection assertions, pipeline vs. -Actual).
• v5→v6 upgrade guide: https://pester.dev/docs/migrations/v5-to-v6.