Add a utility tool for previewing event symbol rendering (#984)

This adds a development-only utility executable target to the package
which allows previewing the event symbols rendered using various console
output styles.

<img width="815" alt="Screenshot 2025-02-28 at 2 14 47 PM"
src="https://github.com/user-attachments/assets/6a1a58d3-10e0-4c51-8c1c-c3581fa0f310"
/>

### Motivation:

This is a tool I made and found useful while working on #983.

### Checklist:

- [x] Code and documentation should follow the style of the [Style
Guide](https://github.com/apple/swift-testing/blob/main/Documentation/StyleGuide.md).
- [x] If public symbols are renamed or modified, DocC references should
be updated.

Author: stmontgomery

Package.swift

@@ -134,6 +134,16 @@ let package = Package(
         .enableLibraryEvolution(applePlatformsOnly: true),
       ]
     ),
+
+    // Utility targets: These are utilities intended for use when developing
+    // this package, not for distribution.
+    .executableTarget(
+      name: "SymbolShowcase",
+      dependencies: [
+        "Testing",
+      ],
+      swiftSettings: .packageSettings
+    ),
   ],
 
   cxxLanguageStandard: .cxx20

Sources/SymbolShowcase/SymbolShowcaseMain.swift

@@ -0,0 +1,117 @@
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2025 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+//
+
+@_spi(Experimental) @_spi(ForToolsIntegrationOnly) import Testing
+import Foundation
+
+/// A type which acts as the main entry point for this executable target.
+@main enum SymbolShowcaseMain {
+  static func main() {
+    let nameColumnWidth = symbols.reduce(into: 0) { $0 = max($0, $1.0.count) } + 4
+    let styleColumnWidth = styles.reduce(into: 0) { $0 = max($0, $1.label.count) } + 2
+    let totalHeaderWidth = nameColumnWidth + (styleColumnWidth * styles.count)
+
+    // Print the table header.
+    print("Name".padding(toLength: nameColumnWidth), terminator: "")
+    for style in styles {
+      print(style.label.padding(toLength: styleColumnWidth), terminator: "")
+    }
+    print()
+    print(String(repeating: "=", count: totalHeaderWidth))
+
+    // Print a row for each symbol, with a preview of each style.
+    for (label, symbol) in symbols {
+      print(label.padding(toLength: nameColumnWidth), terminator: "")
+      for style in styles {
+        print(style.string(for: symbol), terminator: "")
+        print("".padding(toLength: styleColumnWidth - 1), terminator: "")
+      }
+      print()
+    }
+  }
+
+  /// The symbols to preview.
+  fileprivate static var symbols: KeyValuePairs<String, Event.Symbol> {
+    [
+      "Default": .default,
+      "Pass": .pass(knownIssueCount: 0),
+      "Pass w/known issues": .pass(knownIssueCount: 1),
+      "Pass with warnings": .passWithWarnings,
+      "Skip": .skip,
+      "Fail": .fail,
+      "Difference": .difference,
+      "Warning": .warning,
+      "Details": .details,
+      "Attachment": .attachment,
+    ]
+  }
+
+  /// The styles to preview.
+  fileprivate static var styles: [Style] {
+    var styles: [Style] = [
+      Style(label: "Unicode", usesColor: false),
+      Style(label: "w/color", usesColor: true),
+    ]
+
+#if os(macOS) || (os(iOS) && targetEnvironment(macCatalyst))
+    styles.append(contentsOf: [
+      Style(label: "SF Symbols", usesColor: false, usesSFSymbols: true),
+      Style(label: "w/color", usesColor: true, usesSFSymbols: true),
+    ])
+#endif
+
+    return styles
+  }
+}
+
+/// A type representing a style of symbol to preview.
+fileprivate struct Style {
+  /// The label for this style, displayed in its column header.
+  var label: String
+
+  /// Whether this style should render symbols using ANSI color.
+  var usesColor: Bool
+
+#if os(macOS) || (os(iOS) && targetEnvironment(macCatalyst))
+  /// Whether this style should use SF Symbols.
+  var usesSFSymbols: Bool = false
+#endif
+
+  /// Return a string for the specified symbol based on this style's options.
+  ///
+  /// - Parameters:
+  ///   - symbol: The symbol to format into a string.
+  ///
+  /// - Returns: A formatted string representing the specified symbol.
+  func string(for symbol: Event.Symbol) -> String {
+    var options = Event.ConsoleOutputRecorder.Options()
+    options.useANSIEscapeCodes = usesColor
+    options.ansiColorBitDepth = usesColor ? 8 : 1
+#if os(macOS) || (os(iOS) && targetEnvironment(macCatalyst))
+    options.useSFSymbols = usesSFSymbols
+#endif
+
+    return symbol.stringValue(options: options)
+  }
+}
+
+extension String {
+  /// Returns a new string formed from this String by either removing characters
+  /// from the end, or by appending as many occurrences as necessary of a given
+  /// pad string.
+  ///
+  /// - Parameters:
+  ///   - newLength: The length to pad to.
+  ///
+  /// - Returns: A padded string.
+  fileprivate func padding(toLength newLength: Int) -> Self {
+    padding(toLength: newLength, withPad: " ", startingAt: 0)
+  }
+}

Sources/Testing/Events/Recorder/Event.ConsoleOutputRecorder.swift

@@ -136,7 +136,7 @@ extension Event.Symbol {
   ///
   /// - Returns: A string representation of `self` appropriate for writing to
   ///   a stream.
-  fileprivate func stringValue(options: Event.ConsoleOutputRecorder.Options) -> String {
+  package func stringValue(options: Event.ConsoleOutputRecorder.Options) -> String {
     let useColorANSIEscapeCodes = options.useANSIEscapeCodes && options.ansiColorBitDepth >= 4
 
     var symbolCharacter = String(unicodeCharacter)