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](#step-3--check-the-behavioral-gotchas-do-not-skip).

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](references/assertion-map.md)):

| Classic (v5) | New (v6) |

|---|---|

| $x \| Should -Be 1 | $x \| Should-Be 1 |

| $x \| Should -Not -Be 1 | $x \| Should-NotBe 1 |

| $x \| Should -BeExactly 'A' | $x \| Should-BeString 'A' -CaseSensitive |

| $x \| Should -BeGreaterOrEqual 2 | $x \| Should-BeGreaterThanOrEqual 2 |

| $x \| Should -BeLessOrEqual 2 | $x \| Should-BeLessThanOrEqual 2 |

| $x \| Should -BeLike 'a' | $x \| Should-BeLikeString 'a' |

| $x \| Should -Match 're' | $x \| Should-MatchString 're' |

| $x \| Should -BeOfType [int] | $x \| Should-HaveType ([int]) |

| $x \| Should -BeNullOrEmpty | depends — see gotchas (no single equivalent) |

| $c \| Should -HaveCount 3 | $c \| Should-BeCollection -Count 3 |

| $c \| Should -Contain 2 | $c \| Should-ContainCollection 2 |

| { ... } \| Should -Throw 'msg' | { ... } \| Should-Throw -ExceptionMessage 'msg' |

| Should -Invoke Get-Thing | Should-Invoke Get-Thing |

| Should -InvokeVerifiable | Should-Invoke -Verifiable |

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.

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

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

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

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

1. **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'.

1. 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](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.