Fix #2561: Escape control characters in assertion error messages

Format-String2 now escapes control characters as Unicode control pictures
so they are visible in error messages. Characters like ESC (used in ANSI
sequences) now display as their Unicode symbol instead of being invisible.

Copilot-generated fix.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: nohwnd

src/Format2.ps1

@@ -46,10 +46,25 @@ function Format-Object2 ($Value, $Property, [switch]$Pretty) {
 }
 
 function Format-String2 ($Value) {
-    if ('' -eq $Value) {
+    # Use .Length instead of '' -eq $Value because PowerShell's -eq operator
+    # considers some control characters (NUL, BEL, BS, ESC) equal to empty string.
+    if ($null -eq $Value -or $Value.Length -eq 0) {
         return '<empty>'
     }
 
+    # Escape control characters so they are visible in error messages.
+    # Without this, chars like ESC (0x1B used in ANSI sequences) are invisible
+    # and make error output confusing. See https://github.com/pester/Pester/issues/2561
+    $Value = $Value `
+        -replace "`0", '␀' `
+        -replace "`a", '␇' `
+        -replace "`b", '␈' `
+        -replace "`t", '␉' `
+        -replace "`f", '␌' `
+        -replace "`r", '␍' `
+        -replace "`n", '␊' `
+        -replace "`e", '␛'
+
     "'$Value'"
 }
 

tst/Format2.Tests.ps1

@@ -212,5 +212,65 @@ InPesterModuleScope {
         It "Formats string to be sorrounded by quotes" {
             Format-String2 -Value "abc" | Verify-Equal "'abc'"
         }
+
+        # Regression tests for https://github.com/pester/Pester/issues/2561
+        # Control characters must be escaped to Unicode control pictures so they are
+        # visible in error messages instead of being invisible or breaking output.
+        It "Escapes null character to control picture" {
+            Format-String2 -Value "`0" | Verify-Equal "'`u{2400}'"
+        }
+
+        It "Escapes bell character to control picture" {
+            Format-String2 -Value "`a" | Verify-Equal "'`u{2407}'"
+        }
+
+        It "Escapes backspace character to control picture" {
+            Format-String2 -Value "`b" | Verify-Equal "'`u{2408}'"
+        }
+
+        It "Escapes tab character to control picture" {
+            Format-String2 -Value "`t" | Verify-Equal "'`u{2409}'"
+        }
+
+        It "Escapes form feed character to control picture" {
+            Format-String2 -Value "`f" | Verify-Equal "'`u{240C}'"
+        }
+
+        It "Escapes carriage return character to control picture" {
+            Format-String2 -Value "`r" | Verify-Equal "'`u{240D}'"
+        }
+
+        It "Escapes newline character to control picture" {
+            Format-String2 -Value "`n" | Verify-Equal "'`u{240A}'"
+        }
+
+        It "Escapes ESC character to control picture" {
+            Format-String2 -Value "$([char]27)" | Verify-Equal "'`u{241B}'"
+        }
+
+        It "Leaves normal strings unchanged" {
+            Format-String2 -Value "hello" | Verify-Equal "'hello'"
+        }
+
+        It "Escapes ANSI sequence making escape char visible" {
+            # ESC[31m is a common ANSI red color code; the ESC byte should become ␛
+            $ansi = "$([char]27)[31m"
+            $result = Format-String2 -Value $ansi
+            $result | Verify-Equal "'`u{241B}[31m'"
+        }
+
+        It "Escapes multiple control chars in one string" {
+            $value = "a`t`nb"
+            $result = Format-String2 -Value $value
+            $result | Verify-Equal "'a`u{2409}`u{240A}b'"
+        }
+
+        It "Escaped output contains no actual control characters" {
+            # Round-trip: the escaped output should be a clean displayable string
+            $value = "`0`a`b`t`f`r`n$([char]27)"
+            $result = Format-String2 -Value $value
+            # The result should not contain any of the original control characters
+            $result | Should -Not -Match '[\x00-\x1F]'
+        }
     }
 }