From 144cfbee2b63b7a96005a5cc5179d0faf00f9d69 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jakub=20Jare=C5=A1?= <me@jakubjares.com>
Date: Fri, 10 Jul 2026 20:48:07 +0200
Subject: [PATCH] Allow empty string for Should-BeString -Expected

The -Expected parameter was declared Mandatory with a [String] type, which
implicitly rejects empty strings during parameter binding. There is no
assertion-level reason to reject an empty expected value: Test-StringEqual and
Get-StringDifferenceMessage already handle empty strings, and Should-NotBeString
already accepts them. Add [AllowEmptyString()] so the parameter stays required
but may be empty.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../assert/String/Should-BeString.ps1         |  8 +++++
 .../assert/String/Should-BeString.Tests.ps1   | 31 +++++++++++++++++++
 2 files changed, 39 insertions(+)

diff --git a/src/functions/assert/String/Should-BeString.ps1 b/src/functions/assert/String/Should-BeString.ps1
index 22aaf05ec..49d17997b 100644
--- a/src/functions/assert/String/Should-BeString.ps1
+++ b/src/functions/assert/String/Should-BeString.ps1
@@ -69,6 +69,13 @@ function Should-BeString {
 
     This assertion will fail, because the actual value is not equal to the expected value.
 
+    .EXAMPLE
+    ```powershell
+    "" | Should-BeString ""
+    ```
+
+    This assertion will pass, because an empty string is allowed as the expected value.
+
     .NOTES
     The `Should-BeString` assertion is the opposite of the `Should-NotBeString` assertion.
 
@@ -88,6 +95,7 @@ function Should-BeString {
         [Parameter(Position = 1, ValueFromPipeline = $true)]
         $Actual,
         [Parameter(Position = 0, Mandatory)]
+        [AllowEmptyString()]
         [String]$Expected,
         [String]$Because,
         [switch]$CaseSensitive,
diff --git a/tst/functions/assert/String/Should-BeString.Tests.ps1 b/tst/functions/assert/String/Should-BeString.Tests.ps1
index fdaaeabc4..e5933219e 100644
--- a/tst/functions/assert/String/Should-BeString.Tests.ps1
+++ b/tst/functions/assert/String/Should-BeString.Tests.ps1
@@ -85,6 +85,37 @@ Describe "Should-BeString" {
         "abc" | Should-BeString "abc"
     }
 
+    Context "Empty expected string" {
+        It "Passes when both expected and actual are empty strings" {
+            Should-BeString -Expected "" -Actual ""
+        }
+
+        It "Passes when expected is empty and actual is passed by pipeline" {
+            "" | Should-BeString -Expected ""
+        }
+
+        It "Passes when empty expected is passed by position" {
+            "" | Should-BeString ""
+        }
+
+        It "Fails when expected is empty but actual is not" {
+            { Should-BeString -Expected "" -Actual "abc" } | Verify-AssertionFailed
+        }
+
+        It "Throws with default message when expected is empty but actual is not" {
+            $err = { Should-BeString -Expected "" -Actual "abc" } | Verify-AssertionFailed
+            $err.Exception.Message | Verify-Equal (@'
+Expected strings to be the same, but they were different.
+Expected length: 0
+Actual length:   3
+Strings differ at index 0.
+Expected: ''
+But was:  'abc'
+          ^
+'@ -replace "`r`n", "`n")
+        }
+    }
+
     It "Fails when collection of strings is passed in by pipeline, even if the last string is the same as the expected string" {
         { "bde", "abc" | Should-BeString -Expected "abc" } | Verify-AssertionFailed
     }