Fix #2561: Escape control characters in assertion error messages (#2690)

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,11 +46,17 @@ 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'"
+    # Escape ASCII control characters (0x00..0x1F) to the Unicode "Control
+    # Pictures" block (U+2400..U+241F) so they remain visible in error messages.
+    # See https://github.com/pester/Pester/issues/2561. Hot loop lives in C#
+    # (Pester.Formatter) for speed.
+    "'" + [Pester.Formatter]::EscapeControlChars($Value) + "'"
 }
 
 function Format-Null2 {

src/csharp/Pester/Formatter.cs

@@ -0,0 +1,59 @@
+using System;
+
+namespace Pester
+{
+    public static class Formatter
+    {
+        private static readonly char[] ControlChars = BuildControlChars();
+
+        private static char[] BuildControlChars()
+        {
+            var chars = new char[0x20];
+            for (int i = 0; i < 0x20; i++)
+            {
+                chars[i] = (char)i;
+            }
+            return chars;
+        }
+
+        /// <summary>
+        /// Replaces ASCII control characters (0x00..0x1F) in <paramref name="value"/>
+        /// with the matching Unicode "Control Pictures" code point
+        /// (U+2400..U+241F) so they are visible when printed. See
+        /// https://github.com/pester/Pester/issues/2561.
+        ///
+        /// Returns <paramref name="value"/> unchanged when it is null, empty, or
+        /// contains no control characters — common case, no allocation beyond
+        /// the IndexOfAny scan.
+        /// </summary>
+        public static string EscapeControlChars(string value)
+        {
+            if (string.IsNullOrEmpty(value))
+            {
+                return value;
+            }
+
+            int firstControl = value.IndexOfAny(ControlChars);
+            if (firstControl < 0)
+            {
+                return value;
+            }
+
+            int len = value.Length;
+            var buf = new char[len];
+            value.CopyTo(0, buf, 0, len);
+
+            // Everything before firstControl is known to be safe; start from there.
+            for (int i = firstControl; i < len; i++)
+            {
+                char c = buf[i];
+                if (c < 0x20)
+                {
+                    buf[i] = (char)(c + 0x2400);
+                }
+            }
+
+            return new string(buf);
+        }
+    }
+}

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]'
+        }
     }
 }