Collect-Input: empty pipeline unwraps to $null for value assertions

docs/assertion-types.md

@@ -43,13 +43,11 @@ Another special case is `@()`. A value assertion will handle it as `$null`, but
 1 | Should-Be -Expected 1
 @(1) | Should-Be -Expected 1
 $null | Should-Be -Expected $null
-@() | Should-Be -Expected $null #< --- TODO: this is not the case right now, we special case this as empty array, but is that correct? it does not play well with the value and collection assertion, and we special case it just because we can.
-# $null | will give $local:input -> $null , and @() | will give $local:input -> @(), is that distinction important when we know that we will only check against values?
+@() | Should-Be -Expected $null
 
 # This fails, because -Expected does not allow collections.
 @() | Should-Be -Expected @()
-
-
+```
 
 ```powershell
 # Should-BeCollection is a collection assertion:

src/functions/assert/Common/Collect-Input.ps1

@@ -22,15 +22,23 @@
     if ($IsPipelineInput) {
         # We are called like this: 1 | Assert-Equal -Expected 1, we will get $local:Input in $PipelineInput and $true in $IsPipelineInput (coming from $MyInvocation.ExpectingInput).
 
-        if ($PipelineInput.Count -eq 0) {
-            # When calling @() | Assert-Equal -Expected 1, the engine will special case it, and we will get empty array in $local:Input
-            $collectedInput = @()
-        }
-        else {
-            if ($UnrollInput) {
+        if ($UnrollInput) {
+            # Single-item assertions handle empty pipeline the same as $null,
+            # because there is no scalar that @() can unwrap to.
+            if ($PipelineInput.Count -eq 0) {
+                $collectedInput = $null
+            }
+            else {
                 # This is array of all the input, unwrap it.
                 $collectedInput = foreach ($item in $PipelineInput) { $item }
             }
+        }
+        else {
+            # Collection assertions keep the input as a collection. Empty pipeline stays @().
+            if ($PipelineInput.Count -eq 0) {
+                # When calling @() | Assert-Equal -Expected 1, the engine will special case it, and we will get empty array in $local:Input
+                $collectedInput = @()
+            }
             else {
                 # This is array of all the input.
                 $collectedInput = $PipelineInput

tst/functions/assert/Common/Collect-Input.Tests.ps1

@@ -46,6 +46,43 @@ InPesterModuleScope {
                 }
             }
 
+            It "Given @() through pipeline when unrolling it captures `$null" {
+                $collectedInput = @() | Assert-PassThru -UnrollInput
+
+                Verify-True $collectedInput.IsPipelineInput
+                if ($null -ne $collectedInput.Actual) {
+                    throw "Expected `$null, but got $(Format-Nicely2 $collectedInput.Actual)."
+                }
+            }
+
+            It "Given @(`$null) through pipeline when unrolling it captures `$null (PowerShell emits one `$null item)" {
+                $collectedInput = @($null) | Assert-PassThru -UnrollInput
+
+                Verify-True $collectedInput.IsPipelineInput
+                if ($null -ne $collectedInput.Actual) {
+                    throw "Expected `$null, but got $(Format-Nicely2 $collectedInput.Actual)."
+                }
+            }
+
+            It "Given ,`$null through pipeline when unrolling it captures `$null (PowerShell emits one `$null item)" {
+                $collectedInput = , $null | Assert-PassThru -UnrollInput
+
+                Verify-True $collectedInput.IsPipelineInput
+                if ($null -ne $collectedInput.Actual) {
+                    throw "Expected `$null, but got $(Format-Nicely2 $collectedInput.Actual)."
+                }
+            }
+
+            It "Given @(`$null, `$null) through pipeline when unrolling it captures the collection (two items stay as a collection)" {
+                $collectedInput = @($null, $null) | Assert-PassThru -UnrollInput
+
+                Verify-True $collectedInput.IsPipelineInput
+                Verify-Type -Actual $collectedInput.Actual -Expected ([Object[]])
+                if (2 -ne $collectedInput.Actual.Count -or $null -ne $collectedInput.Actual[0] -or $null -ne $collectedInput.Actual[1]) {
+                    throw "Expected @(`$null, `$null), but got $(Format-Nicely2 $collectedInput.Actual)."
+                }
+            }
+
             It "Given List[int] through pipeline it captures the items in Object[]" {
                 $collectedInput = [Collections.Generic.List[int]]@(1, 2) | Assert-PassThru
 

tst/functions/assert/General/Should-Be.Tests.ps1

@@ -77,4 +77,16 @@ Describe "Should-Be" {
         $err = { "dummy" | Should-Be @() } | Verify-Throw
         $err.Exception | Verify-Type ([ArgumentException])
     }
+
+    It "Given empty array through pipeline against `$null it passes (empty pipeline unwraps to `$null for value assertions)" {
+        @() | Should-Be -Expected $null
+    }
+
+    It "Given @(`$null) through pipeline against `$null it passes (single `$null item unwraps to `$null)" {
+        @($null) | Should-Be -Expected $null
+    }
+
+    It "Given ,`$null through pipeline against `$null it passes (single `$null item unwraps to `$null)" {
+        , $null | Should-Be -Expected $null
+    }
 }

tst/functions/assert/General/Should-BeNull.Tests.ps1

@@ -9,8 +9,32 @@ Describe "Should-BeNull" {
         { 1 | Should-BeNull } | Verify-AssertionFailed
     }
 
-    It "Given empty array it fails" {
-        { @() | Should-BeNull } | Verify-AssertionFailed
+    It "Given empty array through pipeline it passes (empty pipeline unwraps to `$null for value assertions)" {
+        @() | Should-BeNull
+    }
+
+    It "Given empty array through -Actual parameter it fails" {
+        { Should-BeNull -Actual @() } | Verify-AssertionFailed
+    }
+
+    It "Given @(`$null) through pipeline it passes (single `$null item unwraps to `$null)" {
+        @($null) | Should-BeNull
+    }
+
+    It "Given ,`$null through pipeline it passes (single `$null item unwraps to `$null)" {
+        , $null | Should-BeNull
+    }
+
+    It "Given @(@(`$null)) through pipeline it passes (PowerShell unwraps the outer @() so this is still a single `$null item)" {
+        @(@($null)) | Should-BeNull
+    }
+
+    It "Given @(`$null, `$null) through pipeline it fails (multi-item array is a collection, not `$null)" {
+        { @($null, $null) | Should-BeNull } | Verify-AssertionFailed
+    }
+
+    It "Given 1, `$null through pipeline it fails (multi-item array is a collection, not `$null)" {
+        { 1, $null | Should-BeNull } | Verify-AssertionFailed
     }
 
     It "Returns the given value" {

tst/functions/assert/General/Should-NotBeNull.Tests.ps1

@@ -10,6 +10,26 @@ InPesterModuleScope {
             { $null | Should-NotBeNull } | Verify-AssertionFailed
         }
 
+        It "Given empty array through pipeline it fails (empty pipeline unwraps to `$null for value assertions)" {
+            { @() | Should-NotBeNull } | Verify-AssertionFailed
+        }
+
+        It "Given empty array through -Actual parameter it passes" {
+            Should-NotBeNull -Actual @()
+        }
+
+        It "Given @(`$null) through pipeline it fails (single `$null item unwraps to `$null)" {
+            { @($null) | Should-NotBeNull } | Verify-AssertionFailed
+        }
+
+        It "Given ,`$null through pipeline it fails (single `$null item unwraps to `$null)" {
+            { , $null | Should-NotBeNull } | Verify-AssertionFailed
+        }
+
+        It "Given @(`$null, `$null) through pipeline it passes (multi-item array is a collection, not `$null)" {
+            @($null, $null) | Should-NotBeNull
+        }
+
         It "Can be called with positional parameters" {
             { Should-NotBeNull $null } | Verify-AssertionFailed
         }