From b6e6d648be1163b0453003881decb548a9db64fa Mon Sep 17 00:00:00 2001
From: Jakub Jares <jajares@microsoft.com>
Date: Fri, 3 Apr 2026 11:42:50 +0200
Subject: [PATCH] Fix #2555: Should-BeNull treats empty pipeline input as null

When a function returns no output and the result is piped to Should-BeNull,
PowerShell sends an empty array through the pipeline. Should-BeNull now
recognizes this as no output and treats it as null.

- Pipeline empty array: passes (void function output)
- Explicit parameter empty array: still fails

Copilot-generated fix.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 src/functions/assert/General/Should-BeNull.ps1       |  9 +++++++++
 tst/functions/assert/General/Should-BeNull.Tests.ps1 | 11 +++++++++--
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/src/functions/assert/General/Should-BeNull.ps1 b/src/functions/assert/General/Should-BeNull.ps1
index fd7fd2b2f..b7751d3d5 100644
--- a/src/functions/assert/General/Should-BeNull.ps1
+++ b/src/functions/assert/General/Should-BeNull.ps1
@@ -32,6 +32,15 @@
 
     $collectedInput = Collect-Input -ParameterInput $Actual -PipelineInput $local:Input -IsPipelineInput $MyInvocation.ExpectingInput -UnrollInput
     $Actual = $collectedInput.Actual
+
+    # When a function returns no output and the result is piped to Should-BeNull,
+    # PowerShell sends an empty array @() through the pipeline. Treat empty pipeline
+    # input as $null since "no output" is effectively null.
+    # See https://github.com/pester/Pester/issues/2555
+    if ($collectedInput.IsPipelineInput -and $Actual -is [array] -and $Actual.Count -eq 0) {
+        $Actual = $null
+    }
+
     if ($null -ne $Actual) {
         $Message = Get-AssertionMessage -Expected $null -Actual $Actual -Because $Because -DefaultMessage "Expected `$null,<because> but got <actualType> '<actual>'."
         throw [Pester.Factory]::CreateShouldErrorRecord($Message, $MyInvocation.ScriptName, $MyInvocation.ScriptLineNumber, $MyInvocation.Line.TrimEnd([System.Environment]::NewLine), $true)
diff --git a/tst/functions/assert/General/Should-BeNull.Tests.ps1 b/tst/functions/assert/General/Should-BeNull.Tests.ps1
index 7398ae333..37f9a0574 100644
--- a/tst/functions/assert/General/Should-BeNull.Tests.ps1
+++ b/tst/functions/assert/General/Should-BeNull.Tests.ps1
@@ -9,8 +9,15 @@ Describe "Should-BeNull" {
         { 1 | Should-BeNull } | Verify-AssertionFailed
     }
 
-    It "Given empty array it fails" {
-        { @() | Should-BeNull } | Verify-AssertionFailed
+    It "Given empty array piped it passes (void function output is empty array)" {
+        # When a function returns no output, PowerShell sends @() through the pipeline.
+        # Should-BeNull treats this as $null since "no output" is effectively null.
+        # See https://github.com/pester/Pester/issues/2555
+        @() | Should-BeNull
+    }
+
+    It "Given empty array by parameter it fails" {
+        { Should-BeNull -Actual @() } | Verify-AssertionFailed
     }
 
     It "Returns the given value" {