Add -Count to Should-BeCollection

src/functions/assert/Collection/Should-BeCollection.ps1

@@ -9,6 +9,9 @@
     .PARAMETER Actual
     A collection of items.
 
+    .PARAMETER Count
+    Checks if the collection has the expected number of items.
+
     .PARAMETER Because
     The reason why the input should be the expected value.
 
@@ -41,26 +44,36 @@
     param (
         [Parameter(Position = 1, ValueFromPipeline = $true)]
         $Actual,
-        [Parameter(Position = 0, Mandatory)]
+        [Parameter(Position = 0, Mandatory, ParameterSetName = 'Expected')]
         $Expected,
-        [String]$Because
+        [String]$Because,
+        [Parameter(ParameterSetName = 'Count')]
+        [int] $Count
     )
 
     $collectedInput = Collect-Input -ParameterInput $Actual -PipelineInput $local:Input -IsPipelineInput $MyInvocation.ExpectingInput
     $Actual = $collectedInput.Actual
 
-    if (-not (Is-Collection -Value $Expected)) {
-        $Message = Get-AssertionMessage -Expected $Expected -Actual $Actual -Because $Because -DefaultMessage "Expected <expectedType> <expected> is not a collection."
+    if (-not (Is-Collection -Value $Actual)) {
+        $Message = Get-AssertionMessage -Expected $Expected -Actual $Actual -Because $Because -DefaultMessage "Actual <actualType> <actual> is not a collection."
         throw [Pester.Factory]::CreateShouldErrorRecord($Message, $MyInvocation.ScriptName, $MyInvocation.ScriptLineNumber, $MyInvocation.Line.TrimEnd([System.Environment]::NewLine), $true)
     }
 
-    if (-not (Is-Collection -Value $Actual)) {
-        $Message = Get-AssertionMessage -Expected $Expected -Actual $Actual -Because $Because -DefaultMessage "Actual <actualType> <actual> is not a collection."
+    if ($PSCmdlet.ParameterSetName -eq 'Count') {
+        if ($Count -ne $Actual.Count) {
+            $Message = Get-AssertionMessage -Expected $Count -Actual $Actual -Because $Because -Data @{ actualCount = $Actual.Count } -DefaultMessage "Expected <expected> items in <actualType> <actual>,<because> but it has <actualCount> items."
+            throw [Pester.Factory]::CreateShouldErrorRecord($Message, $MyInvocation.ScriptName, $MyInvocation.ScriptLineNumber, $MyInvocation.Line.TrimEnd([System.Environment]::NewLine), $true)
+        }
+        return
+    }
+
+    if (-not (Is-Collection -Value $Expected)) {
+        $Message = Get-AssertionMessage -Expected $Expected -Actual $Actual -Because $Because -DefaultMessage "Expected <expectedType> <expected> is not a collection."
         throw [Pester.Factory]::CreateShouldErrorRecord($Message, $MyInvocation.ScriptName, $MyInvocation.ScriptLineNumber, $MyInvocation.Line.TrimEnd([System.Environment]::NewLine), $true)
     }
 
     if (-not (Is-CollectionSize -Expected $Expected -Actual $Actual)) {
-        $Message = Get-AssertionMessage -Expected $Expected -Actual $Actual -Because $Because -DefaultMessage "Expected <expectedType> <expected> to be present in <actualType> <actual>, but they don't have the same number of items."
+        $Message = Get-AssertionMessage -Expected $Expected -Actual $Actual -Because $Because -DefaultMessage "Expected <expectedType> <expected> to be present in <actualType> <actual>,<because> but they don't have the same number of items."
         throw [Pester.Factory]::CreateShouldErrorRecord($Message, $MyInvocation.ScriptName, $MyInvocation.ScriptLineNumber, $MyInvocation.Line.TrimEnd([System.Environment]::NewLine), $true)
     }
 

tst/functions/assert/Collection/Should-BeCollection.Tests.ps1

@@ -24,4 +24,26 @@ Describe "Should-BeCollection" {
         $err = { $actual | Should-BeCollection $expected } | Verify-AssertionFailed
         $err.Exception.Message | Verify-Equal "Expected [Object[]] @(5, 6, 7, 8, 9) to be present in [Object[]] @(1, 2, 3, 4, 5) in any order, but some values were not.`nMissing in actual: '6 (index 1), 7 (index 2), 8 (index 3), 9 (index 4)'`nExtra in actual: '1 (index 0), 2 (index 1), 3 (index 2), 4 (index 3)'"
     }
+
+    Describe "-Count" {
+        It "Counts empty collection @() correctly" {
+            @() | Should-BeCollection -Count 0
+        }
+
+        It "Counts collection with one item correctly" -ForEach @(
+            @(1),
+            (, @()), # array in array
+            @($null),
+            @(""),
+            # we also cannot distinguish between a single item and a single item array
+            1
+        ) {
+            $_ | Should-BeCollection -Count 1
+        }
+
+        It "Fails when collection does not have the expected number of items" {
+            $err = { @(1, 2) | Should-BeCollection -Count 3 } | Verify-AssertionFailed
+            $err.Exception.Message | Verify-Equal "Expected 3 items in [Object[]] @(1, 2), but it has 2 items."
+        }
+    }
 }