This PR completely rewrites how we capture expectation conditions.

 ### Explanation

For example, given the following expectation:

```swift
 #expect(x.f() == 123)
```

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.

 ### Examples

As an example, this expectation…

```swift
 #expect(g() > 500)
```

… previously expanded to…

```swift
Testing.__checkBinaryOperation(
  g(),
  { $0 > $1() },
  500,
  expression: .__fromBinaryOperation(
    .__fromSyntaxNode("g()"),
    ">",
    .__fromSyntaxNode("500")
  ),
  comments: [],
  isRequired: false,
  sourceLocation: Testing.SourceLocation.__here()
).__expected()
```

… but will now expand to:

```swift
Testing.__checkCondition(
  { (__ec: inout Testing.__ExpectationContext) -> Swift.Bool in
    __ec(__ec(g(),0x2) > 500,0x0)
  },
  sourceCode: [
    0x0: "g() > 500",
    0x2: "g()"
  ],
  comments: [],
  isRequired: false,
  sourceLocation: Testing.SourceLocation.__here()
).__expected()
```

More interestingly, an expression with side effects or complex nested operations can also be translated. For example, this throwing expression…

```swift
 #expect((try g() > 500) && true)
```

… was…

```swift
Testing.__checkValue(
  (try g() > 500) && true,
  expression: .__fromSyntaxNode("(try g() > 500) && true"),
  comments: [],
  isRequired: false,
  sourceLocation: Testing.SourceLocation.__here()
).__expected()
```

… but now becomes:

```swift
try Testing.__checkCondition(
  { (__ec: inout Testing.__ExpectationContext) -> Swift.Bool in
    try Testing.__requiringTry(__ec(__ec((try __ec(__ec(g(),0x1ba) > 500,0xba)),0x2) && __ec(true,0x400000),0x0))
  },
  sourceCode: [
    0x0: "(try g() > 500) && true",
    0x2: "(try g() > 500)",
    0xba: "g() > 500",
    0x1ba: "g()",
    0x400000: "true"
  ],
  comments: [],
  isRequired: false,
  sourceLocation: Testing.SourceLocation.__here()
).__expected()
```

 ### Caveats

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.~~ This is now resolved.
- Operations that cause us to capture move-only values (which is disallowed in most contexts) are syntactically indistinguishable from "normal" operations, which causes compilation of such code to fail obscurely.

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.

 ### Resolved Issues

Resolves #162.
Resolves rdar://135437448.

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

Package.swift

@@ -186,6 +186,13 @@ let package = Package(
       path: "Tests/_MemorySafeTestingTests",
       swiftSettings: .packageSettings + [.strictMemorySafety()]
     ),
+    .testTarget(
+      name: "SubexpressionShowcase",
+      dependencies: [
+        "Testing",
+      ],
+      swiftSettings: .packageSettings
+    ),
 
     .macro(
       name: "TestingMacros",

Sources/Testing/CMakeLists.txt

@@ -52,6 +52,7 @@ add_library(Testing
   Expectations/Expectation.swift
   Expectations/Expectation+Macro.swift
   Expectations/ExpectationChecking+Macro.swift
+  Expectations/ExpectationContext.swift
   Issues/Confirmation.swift
   Issues/ErrorSnapshot.swift
   Issues/Issue.swift
@@ -74,7 +75,7 @@ add_library(Testing
   SourceAttribution/Backtrace+Symbolication.swift
   SourceAttribution/CustomTestStringConvertible.swift
   SourceAttribution/Expression.swift
-  SourceAttribution/Expression+Macro.swift
+  SourceAttribution/ExpressionID.swift
   SourceAttribution/SourceBounds.swift
   SourceAttribution/SourceContext.swift
   SourceAttribution/SourceLocation.swift

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

@@ -187,7 +187,7 @@ extension Event.Symbol {
       case .attachment:
         return "\(_ansiEscapeCodePrefix)94m\(symbolCharacter)\(_resetANSIEscapeCode)"
       case .details:
-        return symbolCharacter
+        return "\(symbolCharacter)"
       }
     }
     return symbolCharacter

Sources/Testing/ExitTests/ExitTest.swift

@@ -464,17 +464,16 @@ extension ExitTest {
 /// This function contains the common implementation for all
 /// `await #expect(processExitsWith:) { }` invocations regardless of calling
 /// convention.
-func callExitTest(
+nonisolated(nonsending) func callExitTest(
   identifiedBy exitTestID: (UInt64, UInt64, UInt64, UInt64),
   encodingCapturedValues capturedValues: [ExitTest.CapturedValue],
   processExitsWith expectedExitCondition: ExitTest.Condition,
   observing observedValues: [any PartialKeyPath<ExitTest.Result> & Sendable],
-  expression: __Expression,
+  sourceCode: @escaping @autoclosure @Sendable () -> KeyValuePairs<__ExpressionID, String>,
   comments: @autoclosure () -> [Comment],
   isRequired: Bool,
-  isolation: isolated (any Actor)? = #isolation,
   sourceLocation: SourceLocation
-) async -> Result<ExitTest.Result?, any Error> {
+) async -> Result<ExitTest.Result?, ExpectationFailedError> {
   guard let configuration = Configuration.current ?? Configuration.all.first else {
     preconditionFailure("A test must be running on the current task to use #expect(processExitsWith:).")
   }
@@ -527,27 +526,14 @@ func callExitTest(
   }
 
   // Plumb the exit test's result through the general expectation machinery.
-  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(
+  let expectationContext = __ExpectationContext<Bool>(
+    sourceCode: [.root: String(describingForTest: expectedExitCondition)],
+    runtimeValues: [.root: { Expression.Value(reflecting: result.exitStatus) }]
+  )
+  return check(
     expectedExitCondition.isApproximatelyEqual(to: result.exitStatus),
-    expression: expression,
-    expressionWithCapturedRuntimeValues: expressionWithCapturedRuntimeValues(),
-    mismatchedExitConditionDescription: #"expected exit status "\#(expectedExitCondition)", but "\#(result.exitStatus)" was reported instead"#,
+    expectationContext: expectationContext,
+    mismatchedErrorDescription: nil,
     comments: comments(),
     isRequired: isRequired,
     sourceLocation: sourceLocation

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.
@@ -89,7 +89,7 @@
 /// running in the current task and an instance of ``ExpectationFailedError`` is
 /// thrown.
 ///
-/// This overload of ``require(_:_:sourceLocation:)-6w9oo`` checks if
+/// This overload of ``require(_:_:sourceLocation:)-5l63q`` checks if
 /// `optionalValue` may be ambiguous (i.e. it is unclear if the developer
 /// intended to check for a boolean value or unwrap an optional boolean value)
 /// and provides additional compile-time diagnostics when it is.
@@ -118,16 +118,16 @@ public macro require(
 /// running in the current task and an instance of ``ExpectationFailedError`` is
 /// thrown.
 ///
-/// This overload of ``require(_:_:sourceLocation:)-6w9oo`` is used when a
+/// This overload of ``require(_:_:sourceLocation:)-5l63q`` is used when a
 /// non-optional, non-`Bool` value is passed to `#require()`. It emits a warning
 /// diagnostic indicating that the expectation is redundant.
 @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,14 +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?
-
-  /// A description of the exit condition that was expected to be matched.
-  ///
-  /// If this expectation passed, the value of this property is `nil` because no
-  /// exit test failed.
-  @_spi(Experimental) @_spi(ForToolsIntegrationOnly)
-  public var mismatchedExitConditionDescription: String?
+  public var differenceDescription: String? {
+    evaluatedExpression.differenceDescription
+  }
 
   /// Whether the expectation passed or failed.
   ///
@@ -100,7 +95,7 @@ extension Expectation {
     /// - Parameter expectation: The real expectation.
     public init(snapshotting expectation: borrowing Expectation) {
       self.evaluatedExpression = expectation.evaluatedExpression
-      self.mismatchedErrorDescription = expectation.mismatchedErrorDescription ?? expectation.mismatchedExitConditionDescription
+      self.mismatchedErrorDescription = expectation.mismatchedErrorDescription
       self.differenceDescription = expectation.differenceDescription
       self.isPassing = expectation.isPassing
       self.isRequired = expectation.isRequired