From 55e4c7c5ee858648dc21b355fd78b16e545572ba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Jare=C5=A1?= Date: Sat, 29 Aug 2026 09:31:34 +0200 Subject: [PATCH] Give returning v5 users the assertion rename map The tutorial says Should-Be and Should -Be both work, which is true, and then uses Should-HaveType, Should-BeCollection, Should-BeNull and Should-BeLessThan without saying which v5 operator each one replaces. The names are not a mechanical translation, so guessing fails with a plain CommandNotFoundException and no suggestion. Add a table of the ones the tutorial uses plus the few that catch people out. Say why TestDrive asserts with Test-Path piped into Should-BeTrue. There is no Should-Exist in the new family, so it is a replacement rather than a preference. Say where Assert-MockCalled went, on the page that teaches Should-Invoke. Mark the mock fall-through change as the one most likely to turn an existing green v5 suite red, it was framed only as a nice property of a new suite. The migration guide documents the Assert-MockCalled symptom as "The term 'Assert-MockCalled' is not recognized", which is not what you get. The command is still in the manifest, so PowerShell tries to auto-load Pester and reports the load failure instead, and somebody searching for what they saw does not find the section. Fix #463 --- docs/migrations/v5-to-v6.mdx | 7 +++++-- tutorial/2-testing-a-module/2-first-test.mdx | 16 ++++++++++++++++ tutorial/4-mocking/3-verifying-calls.mdx | 6 ++++++ tutorial/5-working-with-files/2-testdrive.mdx | 4 +++- 4 files changed, 30 insertions(+), 3 deletions(-) diff --git a/docs/migrations/v5-to-v6.mdx b/docs/migrations/v5-to-v6.mdx index 3f56523..c4f76b4 100644 --- a/docs/migrations/v5-to-v6.mdx +++ b/docs/migrations/v5-to-v6.mdx @@ -173,12 +173,15 @@ It 'adds up to `<($a + $b)`>' -ForEach @(@{ a = 1; b = 2 }) { } Both were deprecated back in v5 and are now fully removed. -**Symptom.** +**Symptom.** The command is gone, but the message does not say so. Because `Assert-MockCalled` is still listed in the module manifest, PowerShell tries to auto-load `Pester` to find it and reports the load failure instead: ``` -The term 'Assert-MockCalled' is not recognized as a name of a cmdlet, function, script file, or operable program. +The 'Assert-MockCalled' command was found in the module 'Pester', but the module could not be +loaded due to the following error: [Should operator 'Be' is not registered] ``` +`Assert-VerifiableMock` fails the same way. Searching for the removed command name is what usually brings people here, so it is worth knowing that the error names neither the removal nor the fix. + **Fix.** Use the `Should` mock assertions, see [Mocking](../usage/mocking): ```powershell diff --git a/tutorial/2-testing-a-module/2-first-test.mdx b/tutorial/2-testing-a-module/2-first-test.mdx index f52cf2a..a0666c9 100644 --- a/tutorial/2-testing-a-module/2-first-test.mdx +++ b/tutorial/2-testing-a-module/2-first-test.mdx @@ -137,6 +137,22 @@ You may have noticed the generated test used `Should -Be` and we switched to `Sh `Should-Be` is a command in its own right, added in Pester v6, and is [the recommended way to assert in v6](../../docs/assertions/should-command). `Should -Be` is the older operator style — `Should` with a `-Be` parameter — and it is what nearly all existing Pester code, blog posts and Stack Overflow answers use, including the file `New-Fixture` generates. They coexist in v6 and you can mix them freely, even in one file. This tutorial uses the newer `Should-Be` style throughout. + +The names are not a mechanical translation of the old parameters, so if you are coming from v5 these are the ones this tutorial uses, plus the few that catch people out: + +| v5 operator | v6 command | +| --- | --- | +| `Should -Be` | `Should-Be` | +| `Should -BeOfType` | `Should-HaveType` | +| `Should -Contain` | `Should-ContainCollection` | +| `Should -HaveCount` | `Should-BeCollection -Count` | +| `Should -Match` | `Should-MatchString` | +| `Should -BeLike` | `Should-BeLikeString` | +| `Should -BeExactly` | `Should-BeString -CaseSensitive` | +| `Should -BeGreaterOrEqual` | `Should-BeGreaterThanOrEqual` | +| `Should -Exist` | no equivalent, use `Test-Path` with `Should-BeTrue` | + +Guessing the name usually fails with a plain `CommandNotFoundException` and no suggestion, so the [Should assertions overview](../../docs/assertions/should-command) is worth a look before you start renaming a suite. The old operators are not deprecated, leaving them alone is a valid choice. ::: ## Reading a failure diff --git a/tutorial/4-mocking/3-verifying-calls.mdx b/tutorial/4-mocking/3-verifying-calls.mdx index 80b1294..06967c9 100644 --- a/tutorial/4-mocking/3-verifying-calls.mdx +++ b/tutorial/4-mocking/3-verifying-calls.mdx @@ -125,6 +125,10 @@ Read the last line: it shows the filter that was evaluated *and* the arguments i This behavior is new in Pester v6. Previous versions called the original command when the filter failed. Tests could still pass based on the real data, and you would trust a mock that was never used. +:::note Upgrading a v5 suite +This is the change most likely to turn an existing green suite red. Every v5 test that relied, knowingly or not, on an unmatched call falling through to the real command now fails instead. That is the point, those tests were passing for a reason nobody chose, but it is worth expecting when you upgrade rather than meeting it one test at a time. [v5 to v6](../../docs/migrations/v5-to-v6) covers the fix. +::: + ### Giving a mock a fallback Sometimes you genuinely want "handle this specific case, and everything else generically". Say so explicitly by adding a second mock with no `-ParameterFilter` — an unfiltered mock matches any call, so it becomes the fallback. @@ -156,6 +160,8 @@ Twenty tests: the original fifteen, plus five that no longer care what is in `pl There is also `Should-NotInvoke`, the mirror image, for asserting a command was *not* called — "it did not delete anything", "it did not retry". It takes the same `-ModuleName` and `-ParameterFilter` parameters. +If you are coming from v5, `Should-Invoke` is where `Assert-MockCalled` went. It was deprecated in v5 and removed in v6, and the error you get for it does not mention either fact. +