From 9798539263bb49a0ce0f26e42e559fd43dc7d6a1 Mon Sep 17 00:00:00 2001 From: nohwnd Date: Mon, 29 Jun 2026 23:04:26 +0200 Subject: [PATCH 1/2] Document the piped-collection assertion hint for v6 Add a "Piping vs. -Actual" subsection to the v5-to-v6 migration guide explaining that the new Should-* assertions take their actual value from the pipeline (which unwraps and re-collects collections as [object[]]) or from -Actual, and showing the failure-path hint that points users back to -Actual. Docs for pester/Pester#2806. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/migrations/v5-to-v6.mdx | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/migrations/v5-to-v6.mdx b/docs/migrations/v5-to-v6.mdx index f11931c..72d0659 100644 --- a/docs/migrations/v5-to-v6.mdx +++ b/docs/migrations/v5-to-v6.mdx @@ -233,6 +233,27 @@ Pester 6 adds a new family of `Should-*` assertions — `Should-Be`, `Should-Thr If you want to try them, see the [command reference](../commands/Should-Be). A dedicated guide for moving from `Should -Be` to `Should-Be` will come later. +### Piping vs. `-Actual` + +The new assertions take the actual value from the pipeline or from `-Actual`. The pipeline unwraps its input, so a **value** assertion sees `@(1)` as `1` and `@()` as `$null`, and a collection sent through the pipeline is re-collected as `[object[]]` — its original type (for example `[int[]]`) is lost. Use `-Actual` when you need the exact value or the concrete collection type: + +```powershell +@(1) | Should-Be 1 # pipeline unwraps @(1) to 1 +Should-HaveType -Actual ([int[]](1, 2)) -Expected ([int[]]) # -Actual keeps the [int[]] +``` + +If a value or type assertion fails because the pipeline unwrapped a collection this way, the failure message adds a hint that explains what happened and points you back to `-Actual`: + +```powershell +[int[]](1, 2) | Should-HaveType ([int[]]) +# Expected value to have type [int[]], but got [Object[]] @(1, 2). +# +# Hint: You piped a [int[]] into a type assertion, but the pipeline streams a multi-item +# collection and re-collects it as [Object[]], so the assertion saw [Object[]], not the +# [int[]] you piped. To assert the type of a collection, pass it as the -Actual argument +# instead of piping it, e.g. -Actual $value. +``` + :::warning Pester 6.0.0 is in preview Some details may still change before the final release. To keep up with the latest development, see the release notes for 6.0.0 pre-release builds at https://github.com/pester/Pester/releases ::: From 8de0fb2fd63a679a336bae77274405a752944755 Mon Sep 17 00:00:00 2001 From: nohwnd Date: Mon, 29 Jun 2026 23:26:40 +0200 Subject: [PATCH 2/2] Note that the piped-collection hint is best-effort The pipeline can't reliably distinguish a single-item collection from a scalar, and a collection's original type isn't visible on the right-hand side of the pipeline. Pester recovers the piped value through tricks that work for common cases but not every one, so the hint won't always appear; recommend -Actual when the exact value or collection type matters. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/migrations/v5-to-v6.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/migrations/v5-to-v6.mdx b/docs/migrations/v5-to-v6.mdx index 72d0659..11ec9c6 100644 --- a/docs/migrations/v5-to-v6.mdx +++ b/docs/migrations/v5-to-v6.mdx @@ -254,6 +254,8 @@ If a value or type assertion fails because the pipeline unwrapped a collection t # instead of piping it, e.g. -Actual $value. ``` +The hint is best-effort. PowerShell can't reliably tell a single-item collection from a scalar, and a collection's original type isn't visible on the right-hand side of the pipeline. Pester recovers the piped value through pipeline tricks that work for common cases but not every one, so the hint won't appear in every situation. When you need the exact value or the concrete collection type, pass it with `-Actual` rather than relying on the hint. + :::warning Pester 6.0.0 is in preview Some details may still change before the final release. To keep up with the latest development, see the release notes for 6.0.0 pre-release builds at https://github.com/pester/Pester/releases :::