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

@@ -1,4 +1,9 @@
-function Format-Collection2 ($Value, [switch]$Pretty) {
+# Control characters 0x00..0x1F that Format-String2 escapes to the Unicode
+# "Control Pictures" block so they are visible in error messages. Defined once
+# at module load time so the fast-path IndexOfAny check stays cheap.
+[char[]] $script:Format2ControlChars = foreach ($ch in 0..0x1F) { [char]$ch }
+
+function Format-Collection2 ($Value, [switch]$Pretty) {
     $length = 0
     $o = foreach ($v in $Value) {
         $formatted = Format-Nicely2 -Value $v -Pretty:$Pretty
@@ -46,11 +51,32 @@ 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>'
     }
 
-    "'$Value'"
+    # Fast path: special chars are uncommon, so quote-and-return without rebuilding
+    # the string when none are present. IndexOfAny is a single native scan.
+    if (0 -gt $Value.IndexOfAny($script:Format2ControlChars)) {
+        return "'$Value'"
+    }
+
+    # Slow path: rebuild the string once. Convert to char[] (one O(n) C-side
+    # copy), mutate in place, then re-create the string. Control chars in the
+    # range 0x00..0x1F are mapped to the Unicode "Control Pictures" block
+    # (U+2400..U+241F) by adding 0x2400, so they are visible in error messages
+    # instead of being invisible or breaking output. See
+    # https://github.com/pester/Pester/issues/2561
+    $chars = [char[]] $Value
+    $len = $chars.Length
+    for ($i = 0; $i -lt $len; $i++) {
+        if ([int] $chars[$i] -lt 0x20) {
+            $chars[$i] = [char]([int] $chars[$i] + 0x2400)
+        }
+    }
+    "'" + [string]::new($chars) + "'"
 }
 
 function Format-Null2 {

tst/Format2.Tests.ps1

@@ -241,5 +241,67 @@ 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.
+        # Note: control picture chars (U+2400-U+241B) are written as literal Unicode in
+        # single-quoted strings so the tests parse on PowerShell 5.1 too (`u{XXXX} is PS 6+).
+        It "Escapes null character to control picture" {
+            Format-String2 -Value "`0" | Verify-Equal "'␀'"
+        }
+
+        It "Escapes bell character to control picture" {
+            Format-String2 -Value "`a" | Verify-Equal "'␇'"
+        }
+
+        It "Escapes backspace character to control picture" {
+            Format-String2 -Value "`b" | Verify-Equal "'␈'"
+        }
+
+        It "Escapes tab character to control picture" {
+            Format-String2 -Value "`t" | Verify-Equal "'␉'"
+        }
+
+        It "Escapes form feed character to control picture" {
+            Format-String2 -Value "`f" | Verify-Equal "'␌'"
+        }
+
+        It "Escapes carriage return character to control picture" {
+            Format-String2 -Value "`r" | Verify-Equal "'␍'"
+        }
+
+        It "Escapes newline character to control picture" {
+            Format-String2 -Value "`n" | Verify-Equal "'␊'"
+        }
+
+        It "Escapes ESC character to control picture" {
+            Format-String2 -Value "$([char]27)" | Verify-Equal "'␛'"
+        }
+
+        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 "'␛[31m'"
+        }
+
+        It "Escapes multiple control chars in one string" {
+            $value = "a`t`nb"
+            $result = Format-String2 -Value $value
+            $result | Verify-Equal "'a␉␊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]'
+        }
     }
 }