From 5a4e2e9249dfa368bc82acf1e18444d968bb7a19 Mon Sep 17 00:00:00 2001 From: nohwnd Date: Mon, 29 Jun 2026 23:02:25 +0200 Subject: [PATCH] Document mock invocation history in 6.0.0 release notes - Add a "Mock invocation history" subsection with the example from the Pester docs, showing the call history printed when a Should -Invoke assertion fails and how matched/unmatched calls are marked. - Drop the "first release candidate" framing from the intro for final 6.0.0 wording. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/6.0.0.md | 49 ++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 44 insertions(+), 5 deletions(-) diff --git a/docs/6.0.0.md b/docs/6.0.0.md index 83f3f5167..5bbef2564 100644 --- a/docs/6.0.0.md +++ b/docs/6.0.0.md @@ -3,10 +3,9 @@ > 🙋 Want to share feedback or report a bug? Open an [issue](https://github.com/pester/Pester/issues/new/choose) > or start a [discussion](https://github.com/pester/Pester/discussions). -This is the first release candidate of Pester 6. It is **feature complete** for 6.0 and meant for -real-world testing before the final release. Pester 6 builds on the v5 runtime (Discovery & Run, the -configuration object, the rich result object) and focuses on a brand new assertion syntax, faster -code coverage, and an experimental parallel runner. +Pester 6.0.0 builds on the v5 runtime (Discovery & Run, the configuration object, the rich result +object) and focuses on a brand new assertion syntax, faster code coverage, and an experimental +parallel runner. Pester 6 runs on **Windows PowerShell 5.1** and **PowerShell 7.4+**. @@ -410,11 +409,51 @@ targets **Windows PowerShell 5.1** and **PowerShell 7.4+**. - `Assert-MockCalled` and `Assert-VerifiableMock` have been **removed**. Use `Should -Invoke` and `Should -InvokeVerifiable` (classic syntax) or the new `Should-Invoke` / `Should-NotInvoke`. -- **Mock history** can be printed to help you debug why a parameter filter did or didn't match. +- **Failed `Should -Invoke` assertions print the recorded mock invocation history**, marking which + calls matched your `-ParameterFilter` so you can see why a filter did or didn't match. - Dynamic parameters are handled more robustly: aliases are matched in `-ParameterFilter`, and mocking gracefully falls back when a command can't produce dynamic parameters. - The implicit "fall through to the real command" behavior was removed for more predictable mocks. +#### Mock invocation history + +When a `Should -Invoke` (or `Should-Invoke`) assertion fails, Pester now prints the recorded +invocation history for the mocked command — every recorded call, and whether each one matched +your `-ParameterFilter` — so you can see why a filter did or didn't match without adding your own +`Write-Host` debugging. For example, `Order.Tests.ps1`: + +```powershell +BeforeAll { + function Send-Email ($To, $Subject) { } +} + +Describe 'Order processing' { + It 'emails alice exactly twice' { + Mock Send-Email { } + + Send-Email -To 'alice@example.com' -Subject 'Welcome' + Send-Email -To 'bob@example.com' -Subject 'Receipt' + + Should -Invoke Send-Email -Times 2 -Exactly -ParameterFilter { $To -eq 'alice@example.com' } + } +} +``` + +The assertion fails because only one of the two calls matched the filter, and the failure lists +both recorded calls: + +``` +[-] emails alice exactly twice + Expected Send-Email to be called 2 times exactly, but was called 1 times + Performed invocations: + [*] Send-Email -To 'alice@example.com' -Subject 'Welcome' from Order.Tests.ps1:7 + [ ] Send-Email -To 'bob@example.com' -Subject 'Receipt' from Order.Tests.ps1:7 + at Should -Invoke Send-Email -Times 2 -Exactly -ParameterFilter { $To -eq 'alice@example.com' }, Order.Tests.ps1:12 +``` + +`[*]` marks a call that matched the parameter filter and `[ ]` marks one that didn't — here +`alice` matched and `bob` didn't, so the matched count is 1 instead of the expected 2. + ### Other improvements - `Run.SkipRemainingOnFailure` (`None`, `Run`, `Container`, `Block`) skips the rest of a scope once a