Rethink how we capture expectation conditions and their subexpressions.

This PR completely rewrites how we capture expectation conditions. For example, given the
following expectation:

```swift
```

We currently detect that there is a binary operation and emit code that calls the binary
operator as a closure and passes the left-hand value and right-hand value, then checks
that the result of the operation is `true`.

This is sufficient for simpler expressions like that one, but more complex ones (including
any that involve `try` or `await` keywords) cannot be expanded correctly. With this PR,
such expressions _can_ generally be expanded correctly.

The change involves rewriting the macro condition as a closure to which is passed a local,
mutable "context" value. Subexpressions of the condition expression are then rewritten by
walking the syntax tree of the expression (using typical swift-syntax API) and replacing
them with calls into the context value that pass in the value and related state.

If the expectation ultimately fails, the collected data is transformed into an instance of
the SPI type `Expression` that contains the source code of the expression and interesting
subexpressions as well as the runtime values of those subexpressions.

Nodes in the syntax tree are identified by a unique ID which is composed of the
swift-syntax ID for that node as well as all its parent nodes in a compact bitmask format.
These IDs can be transformed into graph/trie key paths when expression/subexpression
relationships need to be reconstructed on failure, meaning that a single rewritten node
doesn't otherwise need to know its "place" in the overall expression.

There remain a few caveats (that also generally affect the current implementation):

- Mutating member functions are syntactically indistinguishable from non-mutating ones and
  miscompile when rewritten;
- Expressions involving move-only types are also indistinguishable, but need lifetime
  management to be rewritten correctly; and
- Expressions where the `try` or `await` keyword is _outside_ the `#expect` macro cannot
  be expanded correctly because the macro cannot see those keywords during expansion.

The first issue might be resolvable in the future using pointer tricks, although I don't
hold a lot of hope for it. The second issue is probably resolved by non-escaping types.
The third issue is an area of active exploration for us and the macros/swift-syntax team.

Author: grynspan

Package.swift

@@ -123,6 +123,13 @@ let package = Package(
       ],
       swiftSettings: .packageSettings
     ),
+    .testTarget(
+      name: "SubexpressionShowcase",
+      dependencies: [
+        "Testing",
+      ],
+      swiftSettings: .packageSettings
+    ),
 
     .macro(
       name: "TestingMacros",
@@ -258,6 +265,7 @@ extension Array where Element == PackageDescription.SwiftSetting {
 
     result += [
       .enableUpcomingFeature("ExistentialAny"),
+      .enableExperimentalFeature("NonescapableTypes"),
 
       .enableExperimentalFeature("AccessLevelOnImport"),
       .enableUpcomingFeature("InternalImportsByDefault"),

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

@@ -45,6 +45,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) {
       _severity = switch issue.severity {
       case .warning: .warning
@@ -58,6 +63,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

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

Sources/Testing/CMakeLists.txt

@@ -17,6 +17,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
@@ -40,6 +42,8 @@ add_library(Testing
   Expectations/Expectation.swift
   Expectations/Expectation+Macro.swift
   Expectations/ExpectationChecking+Macro.swift
+  Expectations/ExpectationContext.swift
+  Expectations/ExpectationContext+Pointers.swift
   Issues/Confirmation.swift
   Issues/ErrorSnapshot.swift
   Issues/Issue.swift
@@ -62,7 +66,7 @@ add_library(Testing
   SourceAttribution/Backtrace+Symbolication.swift
   SourceAttribution/CustomTestStringConvertible.swift
   SourceAttribution/Expression.swift
-  SourceAttribution/Expression+Macro.swift
+  SourceAttribution/ExpressionID.swift
   SourceAttribution/SourceContext.swift
   SourceAttribution/SourceLocation.swift
   SourceAttribution/SourceLocation+Macro.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:
@@ -171,7 +187,7 @@ extension Event.Symbol {
       case .attachment:
         return "\(_ansiEscapeCodePrefix)94m\(symbolCharacter)\(_resetANSIEscapeCode)"
       case .details:
-        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(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

@@ -25,6 +25,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
 
@@ -450,20 +459,18 @@ extension Event.HumanReadableOutputRecorder {
       }
       additionalMessages += _formattedComments(issue.comments)
 
-      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)" } ?? ""

Sources/Testing/ExitTests/ExitTest.swift

@@ -359,7 +359,7 @@ func callExitTest(
   identifiedBy exitTestID: (UInt64, UInt64, UInt64, UInt64),
   exitsWith expectedExitCondition: ExitTest.Condition,
   observing observedValues: [any PartialKeyPath<ExitTest.Result> & Sendable],
-  expression: __Expression,
+  sourceCode: @escaping @autoclosure @Sendable () -> [__ExpressionID: String],
   comments: @autoclosure () -> [Comment],
   isRequired: Bool,
   isolation: isolated (any Actor)? = #isolation,
@@ -416,10 +416,14 @@ func callExitTest(
   let actualStatusAtExit = result.statusAtExit
 
   // Plumb the exit test's result through the general expectation machinery.
-  return __checkValue(
+  let expectationContext = __ExpectationContext(
+    sourceCode: sourceCode(),
+    runtimeValues: [.root: { Expression.Value(reflecting: actualStatusAtExit) }]
+  )
+  return check(
     expectedExitCondition.isApproximatelyEqual(to: actualStatusAtExit),
-    expression: expression,
-    expressionWithCapturedRuntimeValues: expression.capturingRuntimeValues(actualStatusAtExit),
+    expectationContext: expectationContext,
+    mismatchedErrorDescription: nil,
     mismatchedExitConditionDescription: String(describingForTest: expectedExitCondition),
     comments: comments(),
     isRequired: isRequired,

Sources/Testing/Expectations/Expectation+Macro.swift

@@ -66,10 +66,10 @@
 /// running in the current task and an instance of ``ExpectationFailedError`` is
 /// thrown.
 @freestanding(expression) public macro require<T>(
-  _ optionalValue: T?,
+  _ optionalValue: consuming T?,
   _ comment: @autoclosure () -> Comment? = nil,
   sourceLocation: SourceLocation = #_sourceLocation
-) -> T = #externalMacro(module: "TestingMacros", type: "RequireMacro")
+) -> T = #externalMacro(module: "TestingMacros", type: "UnwrapMacro") where T: ~Copyable
 
 /// Unwrap an optional boolean value or, if it is `nil`, fail and throw an
 /// error.
@@ -124,10 +124,10 @@ public macro require(
 @freestanding(expression)
 @_documentation(visibility: private)
 public macro require<T>(
-  _ optionalValue: T,
+  _ optionalValue: consuming T,
   _ comment: @autoclosure () -> Comment? = nil,
   sourceLocation: SourceLocation = #_sourceLocation
-) -> T = #externalMacro(module: "TestingMacros", type: "NonOptionalRequireMacro")
+) -> T = #externalMacro(module: "TestingMacros", type: "NonOptionalRequireMacro") where T: ~Copyable
 
 // MARK: - Matching errors by type
 

Sources/Testing/Expectations/Expectation.swift

@@ -12,14 +12,14 @@
 public struct Expectation: Sendable {
   /// The expression evaluated by this expectation.
   @_spi(ForToolsIntegrationOnly)
-  public var evaluatedExpression: Expression
+  public internal(set) var evaluatedExpression: Expression
 
   /// A description of the error mismatch that occurred, if any.
   ///
   /// If this expectation passed, the value of this property is `nil` because no
   /// error mismatch occurred.
   @_spi(Experimental) @_spi(ForToolsIntegrationOnly)
-  public var mismatchedErrorDescription: String?
+  public internal(set) var mismatchedErrorDescription: String?
 
   /// A description of the difference between the operands in the expression
   /// evaluated by this expectation, if the difference could be determined.
@@ -28,7 +28,9 @@ public struct Expectation: Sendable {
   /// the difference is only computed when necessary to assist with diagnosing
   /// test failures.
   @_spi(Experimental) @_spi(ForToolsIntegrationOnly)
-  public var differenceDescription: String?
+  public var differenceDescription: String? {
+    evaluatedExpression.differenceDescription
+  }
 
   /// A description of the exit condition that was expected to be matched.
   ///