Show subexpressions separately in expectation failures. (#1572)

This PR refactors how we capture and display subexpressions when an
expectation fails. For example, given the following test:

```swift
@test func foo() {
  let lhs = "abc123"
  let rhs = "d"
  #expect(lhs.contains(rhs))
}
```

We currently output:

```
< > Test foo() started.
<X> Test foo() recorded an issue at FileName.swift:X:Y: Expectation failed: (lhs → "abc123").contains(rhs → "d")
<X> Test foo() failed after 0.003 seconds with 1 issue.
```

This can be hard to read for more complex expressions as the real values
are nested inside a single line. With this change, we instead output:

```
< > Test foo() started.
<X> Test foo() recorded an issue at FileName.swift:X:Y: Expectation failed: lhs.contains(rhs)
--> lhs.contains(rhs) → false
-->   lhs → "abc123"
-->   rhs → "d"
<X> Test foo() failed after 0.003 seconds with 1 issue.
```

This change also adds the subexpression breakdown to our JSON schema as
an experimental field of the "issue" event record:

```json
{
   "kind" : "event",
   "payload" : {
      /* ... */
      "issue" : {
         /* ... */
         "_expectation" : {
            "_expression" : {
               "children" : [
                  {
                     "runtimeTypeName" : "Swift.String",
                     "runtimeValue" : "\"abc123\"",
                     "sourceCode" : "lhs"
                  },
                  {
                     "runtimeTypeName" : "Swift.String",
                     "runtimeValue" : "\"d\"",
                     "sourceCode" : "rhs"
                  }
               ],
               "runtimeTypeName" : "Swift.Bool",
               "runtimeValue" : "false",
               "sourceCode" : "lhs.contains(rhs)"
            }
         },
         /* ... */
      },
   },
   "version" : "99.0.0"
}
```

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

Sources/Testing/ABI/Encoded/ABI.EncodedExpectation.swift

@@ -0,0 +1,34 @@
+//
+// 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 ABI {
+  /// A type implementing the JSON encoding of ``Expectation`` for the ABI entry
+  /// point and event stream output.
+  ///
+  /// This type is not part of the public interface of the testing library. It
+  /// assists in converting values to JSON; clients that consume this JSON are
+  /// expected to write their own decoders.
+  ///
+  /// - Warning: Expectations are not yet part of the JSON schema.
+  struct EncodedExpectation<V>: Sendable where V: ABI.Version {
+    /// The expression evaluated by this expectation.
+    ///
+    /// - Warning: Expressions are not yet part of the JSON schema.
+    var _expression: EncodedExpression<V>
+
+    init(encoding expectation: borrowing Expectation, in eventContext: borrowing Event.Context) {
+      _expression = EncodedExpression<V>(encoding: expectation.evaluatedExpression, in: eventContext)
+    }
+  }
+}
+
+// MARK: - Codable
+
+extension ABI.EncodedExpectation: Codable {}

Sources/Testing/ABI/Encoded/ABI.EncodedExpression.swift

@@ -0,0 +1,52 @@
+//
+// 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 ABI {
+  /// A type implementing the JSON encoding of ``Expression`` for the ABI entry
+  /// point and event stream output.
+  ///
+  /// This type is not part of the public interface of the testing library. It
+  /// assists in converting values to JSON; clients that consume this JSON are
+  /// expected to write their own decoders.
+  ///
+  /// - Warning: Expressions are not yet part of the JSON schema.
+  struct EncodedExpression<V>: Sendable where V: ABI.Version {
+    /// The source code of the original captured expression.
+    var sourceCode: String
+
+    /// A string representation of the runtime value of this expression.
+    ///
+    /// If the runtime value of this expression has not been evaluated, the
+    /// value of this property is `nil`.
+    var runtimeValue: String?
+
+    /// The fully-qualified name of the type of value represented by
+    /// `runtimeValue`, or `nil` if that value has not been captured.
+    var runtimeTypeName: String?
+
+    /// Any child expressions within this expression.
+    var children: [EncodedExpression]?
+
+    init(encoding expression: borrowing __Expression, in eventContext: borrowing Event.Context) {
+      sourceCode = expression.sourceCode
+      runtimeValue = expression.runtimeValue.map(String.init(describingForTest:))
+      runtimeTypeName = expression.runtimeValue.map(\.typeInfo.fullyQualifiedName)
+      if !expression.subexpressions.isEmpty {
+        children = expression.subexpressions.map { [eventContext = copy eventContext] subexpression in
+          Self(encoding: subexpression, in: eventContext)
+        }
+      }
+    }
+  }
+}
+
+// MARK: - Codable
+
+extension ABI.EncodedExpression: Codable {}

Sources/Testing/ABI/Encoded/ABI.EncodedIssue.swift

@@ -60,6 +60,11 @@ extension ABI {
     /// - Warning: Errors are not yet part of the JSON schema.
     var _error: EncodedError<V>?
 
+    /// The expectation associated with this issue, if applicable.
+    ///
+    /// - Warning: Expectations are not yet part of the JSON schema.
+    var _expectation: EncodedExpectation<V>?
+
     init(encoding issue: borrowing Issue, in eventContext: borrowing Event.Context) {
       // >= v0
       isKnown = issue.isKnown
@@ -82,6 +87,9 @@ extension ABI {
         if let error = issue.error {
           _error = EncodedError(encoding: error, in: eventContext)
         }
+        if case let .expectationFailed(expectation) = issue.kind {
+          _expectation = EncodedExpectation(encoding: expectation, in: eventContext)
+        }
       }
     }
   }

Sources/Testing/ABI/Encoded/ABI.EncodedMessage.swift

@@ -67,9 +67,20 @@ extension ABI {
     /// The human-readable, unformatted text associated with this message.
     var text: String
 
+    /// How much to indent this message when presenting it.
+    ///
+    /// - Warning: This property is not yet part of the JSON schema.
+    var _indentation: Int?
+
     init(encoding message: borrowing Event.HumanReadableOutputRecorder.Message) {
       symbol = Symbol(encoding: message.symbol ?? .default)
       text = message.conciseStringValue ?? message.stringValue
+
+      if V.includesExperimentalFields {
+        if message.indentation > 0 {
+          _indentation = message.indentation
+        }
+      }
     }
   }
 }

Sources/Testing/CMakeLists.txt

@@ -18,6 +18,8 @@ add_library(Testing
   ABI/Encoded/ABI.EncodedBacktrace.swift
   ABI/Encoded/ABI.EncodedError.swift
   ABI/Encoded/ABI.EncodedEvent.swift
+  ABI/Encoded/ABI.EncodedExpectation.swift
+  ABI/Encoded/ABI.EncodedExpression.swift
   ABI/Encoded/ABI.EncodedInstant.swift
   ABI/Encoded/ABI.EncodedIssue.swift
   ABI/Encoded/ABI.EncodedMessage.swift

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

@@ -129,6 +129,22 @@ private let _ansiEscapeCodePrefix = "\u{001B}["
 private let _resetANSIEscapeCode = "\(_ansiEscapeCodePrefix)0m"
 
 extension Event.Symbol {
+  /// Get the string value to use for a message with no associated symbol.
+  ///
+  /// - Parameters:
+  ///   - options: Options to use when writing the symbol.
+  ///
+  /// - Returns: A string representation of "no symbol" appropriate for writing
+  ///   to a stream.
+  fileprivate static func placeholderStringValue(options: Event.ConsoleOutputRecorder.Options) -> String {
+#if os(macOS) || (os(iOS) && targetEnvironment(macCatalyst))
+    if options.useSFSymbols {
+      return "  "
+    }
+#endif
+    return " "
+  }
+
   /// Get the string value for this symbol with the given write options.
   ///
   /// - Parameters:
@@ -174,7 +190,7 @@ extension Event.Symbol {
         return symbolCharacter
       }
     }
-    return "\(symbolCharacter)"
+    return symbolCharacter
   }
 }
 
@@ -305,18 +321,12 @@ extension Event.ConsoleOutputRecorder {
   /// - Returns: Whether any output was produced and written to this instance's
   ///   destination.
   @discardableResult public func record(_ event: borrowing Event, in context: borrowing Event.Context) -> Bool {
-    let messages = _humanReadableOutputRecorder.record(event, in: context)
-
-    // Padding to use in place of a symbol for messages that don't have one.
-    var padding = " "
-#if os(macOS) || (os(iOS) && targetEnvironment(macCatalyst))
-    if options.useSFSymbols {
-      padding = "  "
-    }
-#endif
+    let symbolPlaceholder = Event.Symbol.placeholderStringValue(options: options)
 
+    let messages = _humanReadableOutputRecorder.record(event, in: context)
     let lines = messages.lazy.map { [test = context.test] message in
-      let symbol = message.symbol?.stringValue(options: options) ?? padding
+      let symbol = message.symbol?.stringValue(options: options) ?? symbolPlaceholder
+      let indentation = String(repeating: "  ", count: message.indentation)
 
       if case .details = message.symbol {
         // Special-case the detail symbol to apply grey to the entire line of
@@ -325,17 +335,17 @@ extension Event.ConsoleOutputRecorder {
         // to the indentation provided by the symbol.
         var lines = message.stringValue.split(omittingEmptySubsequences: false, whereSeparator: \.isNewline)
         lines = CollectionOfOne(lines[0]) + lines.dropFirst().map { line in
-          "\(padding) \(line)"
+          "\(indentation)\(symbolPlaceholder) \(line)"
         }
         let stringValue = lines.joined(separator: "\n")
         if options.useANSIEscapeCodes, options.ansiColorBitDepth > 1 {
-          return "\(_ansiEscapeCodePrefix)90m\(symbol) \(stringValue)\(_resetANSIEscapeCode)\n"
+          return "\(_ansiEscapeCodePrefix)90m\(symbol) \(indentation)\(stringValue)\(_resetANSIEscapeCode)\n"
         } else {
-          return "\(symbol) \(stringValue)\n"
+          return "\(symbol) \(indentation)\(stringValue)\n"
         }
       } else {
         let colorDots = test.map { self.colorDots(for: $0.tags) } ?? ""
-        return "\(symbol) \(colorDots)\(message.stringValue)\n"
+        return "\(symbol) \(indentation)\(colorDots)\(message.stringValue)\n"
       }
     }
 

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

@@ -29,6 +29,15 @@ extension Event {
       /// The symbol associated with this message, if any.
       var symbol: Symbol?
 
+      /// How much to indent this message when presenting it.
+      ///
+      /// The way in which this additional indentation is rendered is
+      /// implementation-defined. Typically, the greater the value of this
+      /// property, the more whitespace characters are inserted.
+      ///
+      /// Rendering of indentation is optional.
+      var indentation = 0
+
       /// The human-readable message.
       var stringValue: String
 
@@ -503,20 +512,18 @@ extension Event.HumanReadableOutputRecorder {
         additionalMessages.append(_formattedComment(knownIssueComment))
       }
 
-      if verbosity > 0, case let .expectationFailed(expectation) = issue.kind {
+      if verbosity >= 0, case let .expectationFailed(expectation) = issue.kind {
         let expression = expectation.evaluatedExpression
-        func addMessage(about expression: __Expression) {
-          let description = expression.expandedDebugDescription()
-          additionalMessages.append(Message(symbol: .details, stringValue: description))
-        }
-        let subexpressions = expression.subexpressions
-        if subexpressions.isEmpty {
-          addMessage(about: expression)
-        } else {
-          for subexpression in subexpressions {
-            addMessage(about: subexpression)
+        func addMessage(about expression: __Expression, depth: Int) {
+          let description = expression.expandedDescription(verbose: verbosity > 0)
+          if description != expression.sourceCode {
+            additionalMessages.append(Message(symbol: .details, indentation: depth, stringValue: description))
+          }
+          for subexpression in expression.subexpressions {
+            addMessage(about: subexpression, depth: depth + 1)
           }
         }
+        addMessage(about: expression, depth: 0)
       }
 
       let atSourceLocation = issue.sourceLocation.map { " at \($0)" } ?? ""