pester-should-migration

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

Apply the following common conversions (if references/assertion-map.md is available in the repository, it contains a full operator-by-operator table; if that file is absent or unavailable, treat the inline table below as authoritative and complete for this operation — do not assume additional mappings exist beyond what is shown here):

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

Human action required: Run this command in your own terminal to verify the test suite is still green. Do not ask the agent to execute this step autonomously — test suites may have side effects (network calls, file mutations, resource consumption) that cannot be safely assessed without human oversight.

The new assertion messages will differ, but all tests that passed before should still pass:

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).

If you ask the agent to help verify: Rather than running the suite autonomously, the agent will report which files were changed, the count of converted assertions, and flag any gotcha-category assertions (truthy/falsy, null-or-empty, collection semantics) that require human review before the suite is run.

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 (co-located companion file; if absent, the inline table in Step 2 is the authoritative mapping for this operation).
• 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.