Pester Should -* → Should-* full assertion map
Complete operator-by-operator mapping from classic Pester v5 assertions to the
Pester v6 Should-* assertions. Every signature here was taken from the Pester v6
command reference. For the authoritative, always-current parameters and examples,
open https://pester.dev/docs/commands/<Name> (e.g. .../Should-Be).
Conventions used below:
$x= the actual value (piped, or passed with-Actual).- A plain rename means: change
Should -OperatortoShould-Operatorand keep the pipeline/arguments. Anything else is called out.
Equality / comparison
| Classic v5 | Pester v6 | Notes |
|---|---|---|
$x | Should -Be 1 |
$x | Should-Be 1 |
Case-insensitive on strings in both (-eq semantics). |
$x | Should -Not -Be 1 |
$x | Should-NotBe 1 |
Negation is its own command. |
$x | Should -BeExactly 'A' |
$x | Should-BeString 'A' -CaseSensitive |
Should-Be is not case-sensitive; use Should-BeString -CaseSensitive. |
$x | Should -Not -BeExactly 'A' |
$x | Should-NotBeString 'A' -CaseSensitive |
|
$x | Should -BeGreaterThan 1 |
$x | Should-BeGreaterThan 1 |
Plain rename. |
$x | Should -BeGreaterOrEqual 1 |
$x | Should-BeGreaterThanOrEqual 1 |
Renamed (...ThanOrEqual). |
$x | Should -BeLessThan 1 |
$x | Should-BeLessThan 1 |
Plain rename. |
$x | Should -BeLessOrEqual 1 |
$x | Should-BeLessThanOrEqual 1 |
Renamed (...ThanOrEqual). |
There is no negated comparison command (e.g. no Should-NotBeGreaterThan). Invert
the logic with the opposite operator (Should-BeLessThanOrEqual) when needed.
Strings (pattern / regex / whitespace)
| Classic v5 | Pester v6 | Notes |
|---|---|---|
$x | Should -BeLike 'a*' |
$x | Should-BeLikeString 'a*' |
Wildcard match, case-insensitive default. |
$x | Should -BeLikeExactly 'a*' |
$x | Should-BeLikeString 'a*' -CaseSensitive |
|
$x | Should -Not -BeLike 'a*' |
$x | Should-NotBeLikeString 'a*' |
|
$x | Should -Match 're' |
$x | Should-MatchString 're' |
Regex match, case-insensitive default. |
$x | Should -MatchExactly 're' |
$x | Should-MatchString 're' -CaseSensitive |
|
$x | Should -Not -Match 're' |
$x | Should-NotMatchString 're' |
Should-BeString also offers -IgnoreWhitespace and -TrimWhitespace, plus the
dedicated Should-BeEmptyString, Should-NotBeEmptyString, and
Should-NotBeWhiteSpaceString for empty/whitespace checks (no v5 equivalents — they
replace BeNullOrEmpty-style checks on strings).
Boolean / truthiness
Classic BeTrue/BeFalse are truthy/falsy checks. The new same-named commands
are strict ($true/$false only). Choose deliberately:
| Classic v5 | Pester v6 (preserve behavior) | Pester v6 (strict bool) |
|---|---|---|
$x | Should -BeTrue |
$x | Should-BeTruthy |
$x | Should-BeTrue |
$x | Should -BeFalse |
$x | Should-BeFalsy |
$x | Should-BeFalse |
Should-BeFalsy passes for $false, 0, '', $null, @(). If the value under
test is genuinely a boolean, prefer the strict Should-BeTrue / Should-BeFalse.
Null / empty
Should -BeNullOrEmpty collapses several checks into one; v6 splits them. Pick by
what the value actually is:
| Intent | Classic v5 | Pester v6 |
|---|---|---|
value is $null |
$x | Should -BeNullOrEmpty |
$x | Should-BeNull |
| empty string | '' | Should -BeNullOrEmpty |
'' | Should-BeEmptyString |
| empty collection | @() | Should -BeNullOrEmpty |
@() | Should-BeCollection -Count 0 |
| any falsy value | $x | Should -BeNullOrEmpty |
$x | Should-BeFalsy |
| not null | $x | Should -Not -BeNullOrEmpty |
$x | Should-NotBeNull |
| not empty string | $x | Should -Not -BeNullOrEmpty |
$x | Should-NotBeEmptyString |
| not null/empty/whitespace | $x | Should -Not -BeNullOrEmpty |
$x | Should-NotBeWhiteSpaceString |
When in doubt and the type is mixed, Should-BeFalsy / Should-NotBeNull are the
closest broad equivalents — but a type-specific assertion gives a better message.
Type
| Classic v5 | Pester v6 | Notes |
|---|---|---|
$x | Should -BeOfType [int] |
$x | Should-HaveType ([int]) |
|
$x | Should -BeOfType 'System.Int32' |
$x | Should-HaveType ([System.Int32]) |
New form needs a type literal, not a string type name. |
$x | Should -Not -BeOfType [int] |
$x | Should-NotHaveType ([int]) |
For a typed collection, pipe-unwrapping turns [int[]] into [object[]]. Use
-Actual to keep the real type: Should-HaveType -Actual ([int[]](1,2)) -Expected ([int[]]).
Collections
| Classic v5 | Pester v6 | Notes |
|---|---|---|
$c | Should -Be @(1,2,3) |
$c | Should-BeCollection @(1,2,3) |
Should-Be errors on a collection -Expected; use Should-BeCollection for arrays. |
$c | Should -HaveCount 3 |
$c | Should-BeCollection -Count 3 |
|
$c | Should -Contain 2 |
$c | Should-ContainCollection 2 |
Membership. Pass one item, or a collection (@(1, 2)) to require several present, in order. |
$c | Should -Not -Contain 2 |
$c | Should-NotContainCollection 2 |
|
$v | Should -BeIn $c |
$c | Should-ContainCollection $v |
No Should-BeIn; operands swap (actual becomes the collection). |
Should-ContainCollection checks that the expected item(s) are present in the actual
collection, in the right order. Pass a single item ($c | Should-ContainCollection 2)
or a collection to require several at once (1, 2, 3 | Should-ContainCollection @(1, 2)).
For exact, whole-collection equality use Should-BeCollection.
New combinator assertions have no v5 equivalent but are handy in migrations:
$c | Should-All { $_ | Should-BeGreaterThan 0 } and $c | Should-Any { ... }.
Exceptions
| Classic v5 | Pester v6 | Notes |
|---|---|---|
{ ... } | Should -Throw |
{ ... } | Should-Throw |
Plain rename. |
{ ... } | Should -Throw 'msg' |
{ ... } | Should-Throw -ExceptionMessage 'msg' |
Param renamed from -ExpectedMessage. -like wildcards supported. |
{ ... } | Should -Throw -ErrorId 'X' |
{ ... } | Should-Throw -FullyQualifiedErrorId 'X' |
Param renamed. |
{ ... } | Should -Throw -ExceptionType ([T]) |
{ ... } | Should-Throw -ExceptionType ([T]) |
Same. |
{ ... } | Should -Not -Throw |
{ ... }; <no throw assertion needed> |
There is no Should-NotThrow; a script block that must not throw simply runs. Assert on its result instead, or keep the classic Should -Not -Throw. |
Should-Throw adds -AllowNonTerminatingError and returns the error record for
further assertions: $err = { throw 'boom' } | Should-Throw; $err.Exception.Message | Should-BeString '*boom*'.
Mocks
| Classic v5 | Pester v6 | Notes |
|---|---|---|
Should -Invoke Get-Thing |
Should-Invoke Get-Thing |
Plain rename. |
Should -Invoke Get-Thing -Times 2 -Exactly |
Should-Invoke Get-Thing -Times 2 -Exactly |
Same parameters. |
Should -Invoke Get-Thing -ParameterFilter { ... } |
Should-Invoke Get-Thing -ParameterFilter { ... } |
Same. |
Should -Not -Invoke Get-Thing |
Should-NotInvoke Get-Thing |
Separate command. |
Should -InvokeVerifiable |
Should-Invoke -Verifiable |
Folded into a -Verifiable parameter set. |
Assert-MockCalled / Assert-VerifiableMock were removed in v6 entirely — map them
to Should-Invoke / Should-Invoke -Verifiable as well.
Command metadata
| Classic v5 | Pester v6 | Notes |
|---|---|---|
Get-Command f | Should -HaveParameter X -Mandatory |
Get-Command f | Should-HaveParameter X -Mandatory |
Plain rename. |
... | Should -HaveParameter X -Type String |
... | Should-HaveParameter X -Type ([String]) |
Prefer a type literal. |
... | Should -HaveParameter X -DefaultValue 8 |
... | Should-HaveParameter X -DefaultValue 8 |
Same. |
... | Should -Not -HaveParameter X |
... | Should-NotHaveParameter X |
Separate command. |
No Should-* equivalent (keep classic or rewrite)
These v5 operators have no new assertion. Leave them as classic Should -...
(both syntaxes coexist), or rewrite with PowerShell + a new assertion:
| Classic v5 | Workaround in v6 |
|---|---|
$p | Should -Exist |
Test-Path $p | Should-BeTrue |
$p | Should -FileContentMatch 're' |
(Get-Content $p -Raw) | Should-MatchString 're' |
$p | Should -FileContentMatchExactly 're' |
(Get-Content $p -Raw) | Should-MatchString 're' -CaseSensitive |
$p | Should -FileContentMatchMultiline 're' |
(Get-Content $p -Raw) | Should-MatchString 're' |
$p | Should -FileContentMatchMultilineExactly 're' |
(Get-Content $p -Raw) | Should-MatchString 're' -CaseSensitive |
(With Get-Content -Raw, ^ and $ in the regex match the start/end of the whole
file, matching the multiline operators' behavior.)
New v6 assertions with no v5 counterpart
Worth reaching for when migrating; they often replace awkward classic combinations:
Should-BeSame/Should-NotBeSame— reference equality (same instance).Should-BeEquivalent— recursive, property-by-property object comparison.Should-BeHashtable— assert hashtable/ordered dict shape, keys, and count.Should-BeBefore/Should-BeAfter—[datetime]ordering.Should-BeFasterThan/Should-BeSlowerThan—[timespan]/[scriptblock]timing.Should-All/Should-Any— run a filter or nestedShould-*over every item.