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

@@ -56,6 +56,13 @@ let package = Package(
       ],
       swiftSettings: .packageSettings
     ),
+    .testTarget(
+      name: "SubexpressionShowcase",
+      dependencies: [
+        "Testing",
+      ],
+      swiftSettings: .packageSettings
+    ),
 
     .macro(
       name: "TestingMacros",

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

@@ -61,11 +61,20 @@ extension ABIv0 {
     /// The symbol associated with this message.
     var symbol: Symbol
 
+    /// The amount of extra padding to insert between the symbol and string
+    /// value when presenting this message.
+    ///
+    /// - Warning: This property is not yet part of the JSON schema.
+    var _padding: 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.padding > 0 {
+        _padding = message.padding
+      }
       text = message.conciseStringValue ?? message.stringValue
     }
   }

Sources/Testing/CMakeLists.txt

@@ -61,7 +61,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

@@ -169,7 +169,11 @@ extension Event.Symbol {
       case .attachment:
         return "\(_ansiEscapeCodePrefix)94m\(symbolCharacter)\(_resetANSIEscapeCode)"
       case .details:
-        return symbolCharacter
+        var padding = "  "
+#if os(macOS) || (os(iOS) && targetEnvironment(macCatalyst))
+        padding = "   "
+#endif
+        return "\(padding)\(symbolCharacter)"
       }
     }
     return "\(symbolCharacter)"
@@ -306,14 +310,15 @@ extension Event.ConsoleOutputRecorder {
     let messages = _humanReadableOutputRecorder.record(event, in: context)
     for message in messages {
       let symbol = message.symbol?.stringValue(options: options) ?? " "
+      let padding = String(repeating: "  ", count: message.padding)
 
       if case .details = message.symbol, options.useANSIEscapeCodes, options.ansiColorBitDepth > 1 {
         // Special-case the detail symbol to apply grey to the entire line of
         // text instead of just the symbol.
-        write("\(_ansiEscapeCodePrefix)90m\(symbol) \(message.stringValue)\(_resetANSIEscapeCode)\n")
+        write("\(_ansiEscapeCodePrefix)90m\(symbol) \(padding)\(message.stringValue)\(_resetANSIEscapeCode)\n")
       } else {
         let colorDots = context.test.map(\.tags).map { self.colorDots(for: $0) } ?? ""
-        write("\(symbol) \(colorDots)\(message.stringValue)\n")
+        write("\(symbol) \(padding)\(colorDots)\(message.stringValue)\n")
       }
     }
     return !messages.isEmpty

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

@@ -25,6 +25,14 @@ extension Event {
       /// The symbol associated with this message, if any.
       var symbol: Symbol?
 
+      /// The amount of extra padding to insert between the symbol and string
+      /// value when presenting this message.
+      ///
+      /// The nature of this additional padding depends on how the message is
+      /// presented; typically, the greater the value of this property, the more
+      /// whitespace characters are inserted.
+      var padding = 0
+
       /// The human-readable message.
       var stringValue: String
 
@@ -427,20 +435,22 @@ 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 = if verbosity <= 0 {
+            expression.expandedDescription()
+          } else {
+            expression.expandedDebugDescription()
+          }
+          if description != expression.sourceCode {
+            additionalMessages.append(Message(symbol: .details, padding: 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

@@ -241,7 +241,7 @@ extension ExitTest {
 func callExitTest(
   exitsWith expectedExitCondition: ExitCondition,
   observing observedValues: [any PartialKeyPath<ExitTestArtifacts> & Sendable],
-  expression: __Expression,
+  sourceCode: String,
   comments: @autoclosure () -> [Comment],
   isRequired: Bool,
   isolation: isolated (any Actor)? = #isolation,
@@ -293,10 +293,13 @@ func callExitTest(
   let actualExitCondition = result.exitCondition
 
   // Plumb the exit test's result through the general expectation machinery.
-  return __checkValue(
+  var expectationContext = __ExpectationContext()
+  expectationContext.sourceCode[""] = sourceCode
+  expectationContext.runtimeValues[""] = { Expression.Value(reflecting: actualExitCondition) }
+  return check(
     expectedExitCondition == actualExitCondition,
-    expression: expression,
-    expressionWithCapturedRuntimeValues: expression.capturingRuntimeValues(actualExitCondition),
+    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: "RequireMacro") 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