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

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