Enhance closure-based expectation failures. (#1582)

This PR is a follow-up of #1572 and #1581. It cleans up the output
produced by the `#expect(throws:)` and `#expect(processExitsWith:)`
macros to more closely match what we now output for boolean and optional
expectations.

For instance, the following test:

```swift
@test func foo() {
  #expect(throws: MyError()) {
    throw MyParameterizedError(index: 0)
  }
}
```

Previously output:

```
◇ Test foo() started.
✘ Test foo() recorded an issue at [...]: Expectation failed: expected error "MyError()", but "MyParameterizedError(index: 0)" was thrown instead
↳ throw MyParameterizedError(index: 0) → MyParameterizedError(index: 0)
✘ Test foo() failed after 0.001 seconds with 1 issue.
```

But will now output:

```
◇ Test foo() started.
✘ Test foo() recorded an issue at [...]: Expectation failed: expected error "MyError()", but "MyParameterizedError(index: 0)" was thrown instead
↳ MyError() → MyParameterizedError(index: 0)
↳   index → 0
✘ Test foo() failed after 0.001 seconds with 1 issue.
```

And the following exit test:

```swift
@test func bar() async {
  await #expect(processExitsWith: .exitCode(EX_USAGE)) {
    exit(EX_IOERR)
  }
}
```

Previously output:

```
◇ Test bar() started.
✘ Test bar() recorded an issue at [...]: Expectation failed: .exitCode(EX_USAGE → 64)
↳ .exitCode(EX_USAGE → 64) → .exitCode(EX_IOERR → 74)
✘ Test bar() failed after 0.040 seconds with 1 issue.
```

But will now output:

```
◇ Test bar() started.
✘ Test bar() recorded an issue at [...]: Expectation failed: expected exit status ".exitCode(EX_USAGE)", but ".exitCode(EX_IOERR)" was reported instead
↳ .exitCode(EX_USAGE) → .exitCode(EX_IOERR)
↳   EX_USAGE → 64
↳   EX_IOERR → 74
✘ Test bar() failed after 0.038 seconds with 1 issue.
```

We already have code in Swift Testing that uses reflection to extract
information about fields of captured values, and Xcode uses this code,
but it's effectively dead when using `swift test`. With this change in
place, we'll output those subexpressions recursively. For example, the
following test:

```swift
struct S: Equatable, CustomStringConvertible {
  var x: Int
  var description: String { "DESC" }
}

@test func quux() {
  let s1 = S(x: 1)
  let s2 = S(x: 2)
  #expect(s1 == s2)
}
```

Would previously output:

```
◇ Test quux() started.
✘ Test quux() recorded an issue at [...]: Expectation failed: s1 == s2
↳ s1 == s2 → false
↳   s1 → DESC
↳   s2 → DESC
✘ Test quux() failed after 0.001 seconds with 1 issue.
```

And will now output:

```
◇ Test quux() started.
✘ Test quux() recorded an issue at [...]: Expectation failed: s1 == s2
↳ s1 == s2 → false
↳   s1 → DESC
↳     x → 1
↳   s2 → DESC
↳     x → 2
✘ Test quux() failed after 0.001 seconds with 1 issue.
```

### 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.EncodedExpression.swift

@@ -38,8 +38,9 @@ extension ABI {
       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
+      let subexpressions = expression.subexpressions
+      if !subexpressions.isEmpty {
+        children = subexpressions.map { [eventContext = copy eventContext] subexpression in
           Self(encoding: subexpression, in: eventContext)
         }
       }

Sources/Testing/ExitTests/ExitStatus.swift

@@ -113,41 +113,65 @@ private let _sigabbrev_np = symbol(named: "sigabbrev_np").map {
 @available(*, unavailable, message: "Exit tests are not available on this platform.")
 #endif
 extension ExitStatus: CustomStringConvertible {
-  public var description: String {
+  /// The name of the exit code or signal, if known.
+  var name: String? {
+    var result: String?
+
     switch self {
     case let .exitCode(exitCode):
-      if let name = swt_getExitCodeName(exitCode).flatMap(String.init(validatingCString:)) {
-        return ".exitCode(\(name) → \(exitCode))"
-      }
-      return ".exitCode(\(exitCode))"
+      result = swt_getExitCodeName(exitCode).flatMap(String.init(validatingCString:))
     case let .signal(signal):
-      var signalName: String?
-
 #if SWT_TARGET_OS_APPLE || os(FreeBSD) || os(OpenBSD) || os(Android)
 #if !SWT_NO_SYS_SIGNAME
       // These platforms define sys_signame with a size, which is imported
       // into Swift as a tuple.
-      withUnsafeBytes(of: sys_signame) { sys_signame in
+      result = withUnsafeBytes(of: sys_signame) { sys_signame in
         sys_signame.withMemoryRebound(to: UnsafePointer<CChar>.self) { sys_signame in
           if signal > 0 && signal < sys_signame.count {
-            signalName = String(validatingCString: sys_signame[Int(signal)])?.uppercased()
+            return String(validatingCString: sys_signame[Int(signal)])
+              .map { "SIG\($0.uppercased())" }
           }
+          return nil
         }
       }
 #endif
 #elseif os(Linux)
 #if !SWT_NO_DYNAMIC_LINKING
-      signalName = _sigabbrev_np?(signal).flatMap(String.init(validatingCString:))
+      result = _sigabbrev_np?(signal)
+        .flatMap(String.init(validatingCString:))
+        .map { "SIG\($0)" }
 #endif
 #elseif os(Windows) || os(WASI)
       // These platforms do not have API to get the programmatic name of a
       // signal constant.
 #else
 #warning("Platform-specific implementation missing: signal names unavailable")
 #endif
+    }
+
+    return result
+  }
+
+  /// The represented exit code or signal.
+  var code: CInt {
+    switch self {
+    case let .exitCode(exitCode):
+      exitCode
+    case let .signal(signal):
+      signal
+    }
+  }
 
-      if let signalName {
-        return ".signal(SIG\(signalName) → \(signal))"
+  public var description: String {
+    switch self {
+    case let .exitCode(exitCode):
+      if let name {
+        return ".exitCode(\(name))"
+      }
+      return ".exitCode(\(exitCode))"
+    case let .signal(signal):
+      if let name {
+        return ".signal(\(name))"
       }
       return ".signal(\(signal))"
     }

Sources/Testing/ExitTests/ExitTest.Condition.swift

@@ -53,6 +53,14 @@ extension ExitTest {
 
     /// The kind of condition.
     private var _kind: _Kind
+
+    /// The represented exit status, if a specific one exists.
+    var exitStatus: ExitStatus? {
+      if case let .exitStatus(exitStatus) = _kind {
+        return exitStatus
+      }
+      return nil
+    }
   }
 }
 

Sources/Testing/ExitTests/ExitTest.swift

@@ -527,11 +527,27 @@ func callExitTest(
   }
 
   // Plumb the exit test's result through the general expectation machinery.
-  let expression = __Expression(String(describingForTest: expectedExitCondition))
+  func expressionWithCapturedRuntimeValues() -> __Expression {
+    var expression = expression.capturingRuntimeValues(result.exitStatus)
+
+    expression.subexpressions = [expectedExitCondition.exitStatus, result.exitStatus]
+      .compactMap { exitStatus in
+        guard let exitStatus, let exitStatusName = exitStatus.name else {
+          return nil
+        }
+        return __Expression(
+          exitStatusName,
+          runtimeValue: __Expression.Value(describing: exitStatus.code)
+        )
+      }
+
+    return expression
+  }
   return __checkValue(
     expectedExitCondition.isApproximatelyEqual(to: result.exitStatus),
     expression: expression,
-    expressionWithCapturedRuntimeValues: expression.capturingRuntimeValues(result.exitStatus),
+    expressionWithCapturedRuntimeValues: expressionWithCapturedRuntimeValues(),
+    mismatchedExitConditionDescription: #"expected exit status "\#(expectedExitCondition)", but "\#(result.exitStatus)" was reported instead"#,
     comments: comments(),
     isRequired: isRequired,
     sourceLocation: sourceLocation

Sources/Testing/Expectations/Expectation+Macro.swift

@@ -195,7 +195,7 @@ public macro expect<E, R>(
   _ comment: @autoclosure () -> Comment? = nil,
   sourceLocation: SourceLocation = #_sourceLocation,
   performing expression: () throws -> R
-) -> E? = #externalMacro(module: "TestingMacros", type: "ExpectMacro") where E: Error
+) -> E? = #externalMacro(module: "TestingMacros", type: "ExpectThrowsMacro") where E: Error
 
 /// Check that an expression always throws an error of a given type.
 ///
@@ -259,7 +259,7 @@ public macro expect<E, R>(
   _ comment: @autoclosure () -> Comment? = nil,
   sourceLocation: SourceLocation = #_sourceLocation,
   performing expression: () async throws -> R
-) -> E? = #externalMacro(module: "TestingMacros", type: "ExpectMacro") where E: Error
+) -> E? = #externalMacro(module: "TestingMacros", type: "ExpectThrowsMacro") where E: Error
 
 /// Check that an expression always throws an error of a given type, and throw
 /// an error if it does not.
@@ -441,7 +441,7 @@ public macro expect<E, R>(
   _ comment: @autoclosure () -> Comment? = nil,
   sourceLocation: SourceLocation = #_sourceLocation,
   performing expression: () throws -> R
-) -> E? = #externalMacro(module: "TestingMacros", type: "ExpectMacro") where E: Error & Equatable
+) -> E? = #externalMacro(module: "TestingMacros", type: "ExpectThrowsMacro") where E: Error & Equatable
 
 /// Check that an expression always throws a specific error.
 ///
@@ -481,7 +481,7 @@ public macro expect<E, R>(
   _ comment: @autoclosure () -> Comment? = nil,
   sourceLocation: SourceLocation = #_sourceLocation,
   performing expression: () async throws -> R
-) -> E? = #externalMacro(module: "TestingMacros", type: "ExpectMacro") where E: Error & Equatable
+) -> E? = #externalMacro(module: "TestingMacros", type: "ExpectThrowsMacro") where E: Error & Equatable
 
 /// Check that an expression always throws a specific error, and throw an error
 /// if it does not.
@@ -527,7 +527,7 @@ public macro require<E, R>(
   _ comment: @autoclosure () -> Comment? = nil,
   sourceLocation: SourceLocation = #_sourceLocation,
   performing expression: () throws -> R
-) -> E = #externalMacro(module: "TestingMacros", type: "RequireMacro") where E: Error & Equatable
+) -> E = #externalMacro(module: "TestingMacros", type: "RequireThrowsMacro") where E: Error & Equatable
 
 /// Check that an expression always throws a specific error, and throw an error
 /// if it does not.
@@ -571,7 +571,7 @@ public macro require<E, R>(
   _ comment: @autoclosure () -> Comment? = nil,
   sourceLocation: SourceLocation = #_sourceLocation,
   performing expression: () async throws -> R
-) -> E = #externalMacro(module: "TestingMacros", type: "RequireMacro") where E: Error & Equatable
+) -> E = #externalMacro(module: "TestingMacros", type: "RequireThrowsMacro") where E: Error & Equatable
 
 // MARK: - Arbitrary error matching
 
@@ -637,7 +637,7 @@ public macro expect<R>(
   sourceLocation: SourceLocation = #_sourceLocation,
   performing expression: () throws -> R,
   throws errorMatcher: (any Error) throws -> Bool
-) -> (any Error)? = #externalMacro(module: "TestingMacros", type: "ExpectMacro")
+) -> (any Error)? = #externalMacro(module: "TestingMacros", type: "ExpectThrowsMacro")
 
 /// Check that an expression always throws an error matching some condition.
 ///
@@ -699,7 +699,7 @@ public macro expect<R>(
   sourceLocation: SourceLocation = #_sourceLocation,
   performing expression: () async throws -> R,
   throws errorMatcher: (any Error) async throws -> Bool
-) -> (any Error)? = #externalMacro(module: "TestingMacros", type: "ExpectMacro")
+) -> (any Error)? = #externalMacro(module: "TestingMacros", type: "ExpectThrowsMacro")
 
 /// Check that an expression always throws an error matching some condition, and
 /// throw an error if it does not.
@@ -770,7 +770,7 @@ public macro require<R>(
   sourceLocation: SourceLocation = #_sourceLocation,
   performing expression: () throws -> R,
   throws errorMatcher: (any Error) throws -> Bool
-) -> any Error = #externalMacro(module: "TestingMacros", type: "RequireMacro")
+) -> any Error = #externalMacro(module: "TestingMacros", type: "RequireThrowsMacro")
 
 /// Check that an expression always throws an error matching some condition, and
 /// throw an error if it does not.
@@ -839,7 +839,7 @@ public macro require<R>(
   sourceLocation: SourceLocation = #_sourceLocation,
   performing expression: () async throws -> R,
   throws errorMatcher: (any Error) async throws -> Bool
-) -> any Error = #externalMacro(module: "TestingMacros", type: "RequireMacro")
+) -> any Error = #externalMacro(module: "TestingMacros", type: "RequireThrowsMacro")
 
 // MARK: - Exit tests
 

Sources/Testing/SourceAttribution/Expression+Macro.swift

@@ -20,7 +20,7 @@ extension __Expression {
   /// - Warning: This function is used to implement the `@Test`, `@Suite`,
   ///   `#expect()` and `#require()` macros. Do not call it directly.
   public static func __fromSyntaxNode(_ syntaxNode: String) -> Self {
-    Self(kind: .generic(syntaxNode))
+    Self(syntaxNode)
   }
 
   /// Create an instance of this type representing a string literal.
@@ -35,7 +35,7 @@ extension __Expression {
   /// - Warning: This function is used to implement the `@Test`, `@Suite`,
   ///   `#expect()` and `#require()` macros. Do not call it directly.
   public static func __fromStringLiteral(_ sourceCode: String, _ stringValue: String) -> Self {
-    Self(kind: .generic(sourceCode))
+    Self(sourceCode)
   }
 
   /// Create an instance of this type representing a binary operation.
@@ -51,7 +51,7 @@ extension __Expression {
   ///   `#expect()` and `#require()` macros. Do not call it directly.
   public static func __fromBinaryOperation(_ lhs: Self, _ op: String, _ rhs: Self) -> Self {
     return Self(
-      kind: .generic("\(lhs) \(op) \(rhs)"),
+      "\(lhs) \(op) \(rhs)",
       subexpressions: [lhs, rhs]
     )
   }
@@ -85,7 +85,7 @@ extension __Expression {
     sourceCode = "\(sourceCode)(\(argumentsSourceCode))"
 
     return Self(
-      kind: .generic(sourceCode),
+      sourceCode,
       subexpressions: Array(value) + arguments.map(\.value)
     )
   }
@@ -103,7 +103,7 @@ extension __Expression {
   ///   `#expect()` and `#require()` macros. Do not call it directly.
   public static func __fromPropertyAccess(_ value: Self, _ keyPath: Self) -> Self {
     Self(
-      kind: .generic("\(value.sourceCode).\(keyPath.sourceCode)"),
+      "\(value.sourceCode).\(keyPath.sourceCode)",
       subexpressions: [value, keyPath]
     )
   }
@@ -128,7 +128,7 @@ extension __Expression {
       "!\(expression.sourceCode)"
     }
     return Self(
-      kind: .generic(sourceCode),
+      sourceCode,
       isNegated: true,
       subexpressions: [expression]
     )

Sources/Testing/SourceAttribution/Expression.swift

@@ -46,6 +46,18 @@ public struct __Expression: Sendable {
   /// instance of this type.
   var kind: Kind
 
+  init(
+    _ sourceCode: String,
+    isNegated: Bool = false,
+    runtimeValue: Value? = nil,
+    subexpressions: [Self] = []
+  ) {
+    self.kind = .generic(sourceCode)
+    self.isNegated = isNegated
+    self.runtimeValue = runtimeValue
+    self._subexpressions = subexpressions
+  }
+
   /// Whether or not this instance represents a negated expression (`!foo`).
   var isNegated = false
 
@@ -340,9 +352,32 @@ public struct __Expression: Sendable {
     return result
   }
 
+  /// Storage for ``subexpressions``.
+  private var _subexpressions = [Self]()
+
   /// The set of parsed and captured subexpressions contained in this instance.
   @_spi(ForToolsIntegrationOnly)
-  public internal(set) var subexpressions = [Self]()
+  public internal(set) var subexpressions: [Self] {
+    get {
+      if !_subexpressions.isEmpty {
+        return _subexpressions
+      }
+      // If there were no explicitly-added subexpressions, look for any
+      // subexpressions captured via reflection instead.
+      if let children = runtimeValue?.children {
+        return children.compactMap { child in
+          guard let label = child.label else {
+            return nil
+          }
+          return __Expression(label, runtimeValue: child)
+        }
+      }
+      return []
+    }
+    set {
+      _subexpressions = newValue
+    }
+  }
 
   /// A description of the difference between the operands in this expression,
   /// if that difference could be determined.
@@ -383,7 +418,7 @@ extension __Expression: CustomStringConvertible, CustomDebugStringConvertible {
   /// This initializer does not attempt to parse `sourceCode`.
   @_spi(ForToolsIntegrationOnly)
   public init(_ sourceCode: String) {
-    self.init(kind: .generic(sourceCode))
+    self.init(sourceCode, isNegated: false)
   }
 
   public var description: String {