Add experimental AdvancedConsoleOutputRecorder skeleton framework (#1253)

Add experimental AdvancedConsoleOutputRecorder skeleton framework

### Motivation:

The current console output for `swift test` is a static log, which
presents challenges for developers in understanding test progress and
diagnosing failures, especially in large, parallel test suites. This PR
introduces the foundational "skeleton" for a new, advanced console
reporter to address these issues.

The recorder is marked as experimental and must be explicitly enabled
via the `SWT_ENABLE_EXPERIMENTAL_CONSOLE_OUTPUT` environment variable,
ensuring it doesn't affect existing functionality.

### Modifications:

- **Added `Event.AdvancedConsoleOutputRecorder.swift`**: New
experimental console output recorder skeleton with:
  - Basic structure and minimal configuration options
- Currently delegates to `Event.ConsoleOutputRecorder` for actual output
- Foundation framework ready for future development of advanced features

The implementation provides the foundation structure following
established patterns in the codebase, ready for future development of
advanced console features.

### 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: tienquocbui

Sources/Testing/ABI/EntryPoints/EntryPoint.swift

@@ -54,12 +54,29 @@ func entryPoint(passing args: __CommandLineArguments_v0?, eventHandler: Event.Ha
 #if !SWT_NO_FILE_IO
     // Configure the event recorder to write events to stderr.
     if configuration.verbosity > .min {
-      let eventRecorder = Event.ConsoleOutputRecorder(options: .for(.stderr)) { string in
-        try? FileHandle.stderr.write(string)
-      }
-      configuration.eventHandler = { [oldEventHandler = configuration.eventHandler] event, context in
-        eventRecorder.record(event, in: context)
-        oldEventHandler(event, context)
+      // Check for experimental console output flag
+      if Environment.flag(named: "SWT_ENABLE_EXPERIMENTAL_CONSOLE_OUTPUT") == true {
+        // Use experimental AdvancedConsoleOutputRecorder
+        var advancedOptions = Event.AdvancedConsoleOutputRecorder.Options()
+        advancedOptions.base = .for(.stderr)
+        
+        let eventRecorder = Event.AdvancedConsoleOutputRecorder(options: advancedOptions) { string in
+          try? FileHandle.stderr.write(string)
+        }
+        
+        configuration.eventHandler = { [oldEventHandler = configuration.eventHandler] event, context in
+          eventRecorder.record(event, in: context)
+          oldEventHandler(event, context)
+        }
+      } else {
+        // Use the standard console output recorder (default behavior)
+        let eventRecorder = Event.ConsoleOutputRecorder(options: .for(.stderr)) { string in
+          try? FileHandle.stderr.write(string)
+        }
+        configuration.eventHandler = { [oldEventHandler = configuration.eventHandler] event, context in
+          eventRecorder.record(event, in: context)
+          oldEventHandler(event, context)
+        }
       }
     }
 #endif

Sources/Testing/CMakeLists.txt

@@ -26,6 +26,7 @@ add_library(Testing
   Attachments/Attachment.swift
   Events/Clock.swift
   Events/Event.swift
+  Events/Recorder/Event.AdvancedConsoleOutputRecorder.swift
   Events/Recorder/Event.ConsoleOutputRecorder.swift
   Events/Recorder/Event.HumanReadableOutputRecorder.swift
   Events/Recorder/Event.JUnitXMLRecorder.swift

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

@@ -0,0 +1,63 @@
+//
+// 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
+//
+
+extension Event {
+  /// An experimental console output recorder that provides enhanced test result
+  /// display capabilities.
+  ///
+  /// This recorder is currently experimental and must be enabled via the
+  /// `SWT_ENABLE_EXPERIMENTAL_CONSOLE_OUTPUT` environment variable.
+  struct AdvancedConsoleOutputRecorder: Sendable {
+    /// Configuration options for the advanced console output recorder.
+    struct Options: Sendable {
+      /// Base console output recorder options to inherit from.
+      var base: Event.ConsoleOutputRecorder.Options
+      
+      init() {
+        self.base = Event.ConsoleOutputRecorder.Options()
+      }
+    }
+    
+    /// The options for this recorder.
+    let options: Options
+    
+    /// The write function for this recorder.
+    let write: @Sendable (String) -> Void
+    
+    /// The fallback console recorder for standard output.
+    private let _fallbackRecorder: Event.ConsoleOutputRecorder
+    
+    /// Initialize the advanced console output recorder.
+    ///
+    /// - Parameters:
+    ///   - options: Configuration options for the recorder.
+    ///   - write: A closure that writes output to its destination.
+    init(options: Options = Options(), writingUsing write: @escaping @Sendable (String) -> Void) {
+      self.options = options
+      self.write = write
+      self._fallbackRecorder = Event.ConsoleOutputRecorder(options: options.base, writingUsing: write)
+    }
+  }
+}
+
+extension Event.AdvancedConsoleOutputRecorder {
+  /// Record an event by processing it and generating appropriate output.
+  ///
+  /// Currently this is a skeleton implementation that delegates to
+  /// ``Event/ConsoleOutputRecorder``.
+  ///
+  /// - Parameters:
+  ///   - event: The event to record.
+  ///   - eventContext: The context associated with the event.
+  func record(_ event: borrowing Event, in eventContext: borrowing Event.Context) {
+    // Skeleton implementation: delegate to ConsoleOutputRecorder
+    _fallbackRecorder.record(event, in: eventContext)
+  }
+}