Pester Should -* → Should-* Migration

Convert classic Pester v5 assertions (Should -Be, space then parameter) to the new Pester v6 Should-* assertions (Should-Be, hyphen, no space).

Status: experimental / preview. Verified against Pester 6.0.0-rc2. The classic Should -Be style still works in v6, so migrate incrementally and keep the suite green.

Companion skill. This skill covers the optional move to the new Should-* operators. To upgrade a suite across major Pester versions (v3→v4→v5→v6 — the runtime, mocks, and config), use the separate pester-migration skill. In v6 the classic Should -Be keeps working, so adopting Should-* is independent of any version bump.

When to Use

• Modernizing a Pester suite to the v6 Should-* assertions.
• A user asks to migrate / convert / rewrite Should -... calls.
• You want clearer, type-aware failure messages from the new assertions.

Know This First

• Both syntaxes work side by side in Pester v6. Migration is optional and can be done one test (or one file) at a time. Nothing breaks if you leave some classic.
• Requires Pester v6+. The Should-* commands do not exist in v5.
• Negation is a separate command, not a -Not switch: Should -Not -Be → Should-NotBe. There is no -Not parameter on the new assertions.
• The actual value still comes from the pipeline ($x | Should-Be 1) or from -Actual (Should-Be -Actual $x -Expected 1). -Because carries over unchanged.
• Most renames are mechanical, but several have behavior changes you must check by hand — see Gotchas.

Procedure

Step 1 — Find the classic assertions

Search the target for the classic space-separated syntax (the tell is Should -, or Should followed by -Not):

Should -          # any classic operator
Should -Not -     # negated classic operator
Assert-MockCalled # also removed in v6 -> Should-Invoke

Limit the scope to PowerShell test files (*.Tests.ps1, *.ps1).

Step 2 — Apply the mapping

Most-used conversions (full list in references/assertion-map.md):

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.

…