Unlock expression expansions for negated expressions. (#364)

This PR enables expression expansion for expressions of the forms `!x`,
`!f()`, `!y.g()`, etc. such that the value of the expressions they
negate are available at runtime to inspect in a test failure. For
example, consider this test:

```swift
func f() -> Int { 123 }
func g() -> Int { 123 }

@test func myTest() {
  #expect(!(f() == g())) // ♦️ Expectation failed: !(f() == g())
}
```

(i.e., testing that the result of `f()` is not equal to the result of
`g()`, but using `!(==)` instead of the more typical `!=`.)

This is a trivial/contrived example where we can tell at a glance that
the values equal `123`, of course. Still, previously this test would
(correctly) fail, but would not be able to provide the return values of
`f()` and `g()`. With this change, the following test issue is recorded:

```swift
 #expect(!(f() == g())) // ♦️ Expectation failed: !((f() → 123) == (g() → 123) → true)
```

This increasing the amount of diagnostic information available.

This PR also makes adjustments to the `Expression` type to improve the
information we log during test runs. In particular, when `--verbose` is
passed to `swift test`, we will capture type information about more
parts of a failed expectation/expression.

### 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/Events/Recorder/Event.HumanReadableOutputRecorder.swift

@@ -371,7 +371,7 @@ extension Event.HumanReadableOutputRecorder {
       if verbose, case let .expectationFailed(expectation) = issue.kind {
         let expression = expectation.evaluatedExpression
         func addMessage(about expression: Expression) {
-          let description = expression.expandedDescription(includingTypeNames: true, includingParenthesesIfNeeded: false)
+          let description = expression.expandedDebugDescription()
           additionalMessages.append(Message(symbol: .details, stringValue: description))
         }
         let subexpressions = expression.subexpressions

Sources/Testing/Expectations/ExpectationChecking+Macro.swift

@@ -68,11 +68,27 @@ public func __checkValue(
   isRequired: Bool,
   sourceLocation: SourceLocation
 ) -> Result<Void, any Error> {
+  // If the expression being evaluated is a negation (!x instead of x), flip
+  // the condition here so that we evaluate it in the correct sense. We loop
+  // in case of multiple prefix operators (!!(a == b), for example.)
+  var condition = condition
+  do {
+    var expression: Expression? = expression
+    while case let .negation(subexpression, _) = expression?.kind {
+      defer {
+        expression = subexpression
+      }
+      condition = !condition
+    }
+  }
+
   // Capture the correct expression in the expectation.
-  let expression = if !condition, let expressionWithCapturedRuntimeValues = expressionWithCapturedRuntimeValues() {
-    expressionWithCapturedRuntimeValues
-  } else {
-    expression
+  var expression = expression
+  if !condition, let expressionWithCapturedRuntimeValues = expressionWithCapturedRuntimeValues() {
+    expression = expressionWithCapturedRuntimeValues
+    if expression.runtimeValue == nil, case .negation = expression.kind {
+      expression = expression.capturingRuntimeValue(condition)
+    }
   }
 
   // Post an event for the expectation regardless of whether or not it passed.

Sources/Testing/Parameterization/TypeInfo.swift

@@ -281,6 +281,16 @@ extension TypeInfo: CustomStringConvertible, CustomDebugStringConvertible {
 // MARK: - Equatable, Hashable
 
 extension TypeInfo: Hashable {
+  /// Check if this instance describes a given type.
+  ///
+  /// - Parameters:
+  ///   - type: The type to compare against.
+  ///
+  /// - Returns: Whether or not this instance represents `type`.
+  public func describes(_ type: Any.Type) -> Bool {
+    self == TypeInfo(describing: type)
+  }
+
   public static func ==(lhs: Self, rhs: Self) -> Bool {
     switch (lhs._kind, rhs._kind) {
     case let (.type(lhs), .type(rhs)):

Sources/Testing/SourceAttribution/Expression+Macro.swift

@@ -66,7 +66,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 __functionCall(_ value: Expression?, _ functionName: String, _ arguments: (label: String?, value: Expression)...) -> Self {
+  public static func __fromFunctionCall(_ value: Expression?, _ functionName: String, _ arguments: (label: String?, value: Expression)...) -> Self {
     let arguments = arguments.map(Expression.Kind.FunctionCallArgument.init)
     return Self(kind: .functionCall(value: value, functionName: functionName, arguments: arguments))
   }
@@ -85,4 +85,21 @@ extension Expression {
   public static func __fromPropertyAccess(_ value: Expression, _ keyPath: Expression) -> Self {
     return Self(kind: .propertyAccess(value: value, keyPath: keyPath))
   }
+
+  /// Create an instance of ``Expression`` representing a negated expression
+  /// using the `!` operator..
+  ///
+  /// - Parameters:
+  ///   - expression: The expression that was negated.
+  ///   - isParenthetical: Whether or not `expression` was enclosed in
+  ///     parentheses (and the `!` operator was outside it.) This argument
+  ///     affects how this expression is represented as a string.
+  ///
+  /// - Returns: A new instance of ``Expression``.
+  ///
+  /// - Warning: This function is used to implement the `@Test`, `@Suite`,
+  ///   `#expect()` and `#require()` macros. Do not call it directly.
+  public static func __fromNegation(_ expression: Expression, _ isParenthetical: Bool) -> Self {
+    return Self(kind: .negation(expression, isParenthetical: isParenthetical))
+  }
 }

Sources/Testing/SourceAttribution/Expression.swift

@@ -78,6 +78,18 @@ public struct Expression: Sendable {
     ///   - keyPath: The key path, relative to `value`, that was accessed, not
     ///     including a leading backslash or period.
     indirect case propertyAccess(value: Expression, keyPath: Expression)
+
+    /// The expression negates another expression.
+    ///
+    /// - Parameters:
+    ///   - expression: The expression that was negated.
+    ///   - isParenthetical: Whether or not `expression` was enclosed in
+    ///     parentheses (and the `!` operator was outside it.) This argument
+    ///     affects how this expression is represented as a string.
+    ///
+    /// Unlike other cases in this enumeration, this case affects the runtime
+    /// behavior of the `__check()` family of functions.
+    indirect case negation(_ expression: Expression, isParenthetical: Bool)
   }
 
   /// The kind of syntax node represented by this instance.
@@ -109,6 +121,12 @@ public struct Expression: Sendable {
       return "\(functionName)(\(argumentList))"
     case let .propertyAccess(value, keyPath):
       return "\(value.sourceCode).\(keyPath.sourceCode)"
+    case let .negation(expression, isParenthetical):
+      var sourceCode = expression.sourceCode
+      if isParenthetical {
+        sourceCode = "(\(sourceCode))"
+      }
+      return "!\(sourceCode)"
     }
   }
 
@@ -192,6 +210,9 @@ public struct Expression: Sendable {
   func capturingRuntimeValue(_ value: (some Any)?) -> Self {
     var result = self
     result.runtimeValue = value.map { Value(reflecting: $0) }
+    if case let .negation(subexpression, isParenthetical) = kind, let value = value as? Bool {
+      result.kind = .negation(subexpression.capturingRuntimeValue(!value), isParenthetical: isParenthetical)
+    }
     return result
   }
 
@@ -237,58 +258,128 @@ public struct Expression: Sendable {
         value: value.capturingRuntimeValues(firstValue),
         keyPath: keyPath.capturingRuntimeValues(additionalValuesArray.first ?? nil)
       )
+    case let .negation(expression, isParenthetical):
+      result.kind = .negation(
+        expression.capturingRuntimeValues(firstValue, repeat each additionalValues),
+        isParenthetical: isParenthetical
+      )
     }
 
     return result
   }
 
+  /// Get an expanded description of this instance that contains the source
+  /// code and runtime value (or values) it represents.
+  ///
+  /// - Returns: A string describing this instance.
+  @_spi(ForToolsIntegrationOnly)
+  public func expandedDescription() -> String {
+    _expandedDescription(in: _ExpandedDescriptionContext())
+  }
+
+  /// Get an expanded description of this instance that contains the source
+  /// code and runtime value (or values) it represents.
+  ///
+  /// - Returns: A string describing this instance.
+  ///
+  /// This function produces a more detailed description than
+  /// ``expandedDescription()``, similar to how `String(reflecting:)` produces
+  /// a more detailed description than `String(describing:)`.
+  func expandedDebugDescription() -> String {
+    var context = _ExpandedDescriptionContext()
+    context.includeTypeNames = true
+    context.includeParenthesesIfNeeded = false
+    return _expandedDescription(in: context)
+  }
+
+  /// A structure describing the state tracked while calling
+  /// `_expandedDescription(in:)`.
+  private struct _ExpandedDescriptionContext {
+    /// The depth of recursion at which the function is being called.
+    var depth = 0
+
+    /// Whether or not to include type names in output.
+    var includeTypeNames = false
+
+    /// Whether or not to enclose the resulting string in parentheses (as needed
+    /// depending on what information the resulting string contains.)
+    var includeParenthesesIfNeeded = true
+  }
+
   /// Get an expanded description of this instance that contains the source
   /// code and runtime value (or values) it represents.
   ///
   /// - Parameters:
-  ///   - depth: The depth of recursion at which this function is being called.
-  ///   - includingTypeNames: Whether or not to include type names in output.
-  ///   - includingParenthesesIfNeeded: Whether or not to enclose the
-  ///     resulting string in parentheses (as needed depending on what
-  ///     information this instance contains.)
+  ///   - context: The context for this call.
   ///
   /// - Returns: A string describing this instance.
-  @_spi(ForToolsIntegrationOnly)
-  public func expandedDescription(depth: Int = 0, includingTypeNames: Bool = false, includingParenthesesIfNeeded: Bool = true) -> String {
+  ///
+  /// This function provides the implementation of ``expandedDescription()`` and
+  /// ``expandedDebugDescription()``.
+  private func _expandedDescription(in context: _ExpandedDescriptionContext) -> String {
+    // Create a (default) context value to pass to recursive calls for
+    // subexpressions.
+    var childContext = context
+    do {
+      // Bump the depth so that recursive calls track the next depth level.
+      childContext.depth += 1
+
+      // Subexpressions do not automatically disable parentheses if the parent
+      // does; they must opt in.
+      childContext.includeParenthesesIfNeeded = true
+    }
+
     var result = ""
     switch kind {
     case let .generic(sourceCode), let .stringLiteral(sourceCode, _):
-      result = if includingTypeNames, let qualifiedName = runtimeValue?.typeInfo.fullyQualifiedName {
+      result = if context.includeTypeNames, let qualifiedName = runtimeValue?.typeInfo.fullyQualifiedName {
         "\(sourceCode): \(qualifiedName)"
       } else {
         sourceCode
       }
     case let .binaryOperation(lhsExpr, op, rhsExpr):
-      result = "\(lhsExpr.expandedDescription(depth: depth + 1)) \(op) \(rhsExpr.expandedDescription(depth: depth + 1))"
+      result = "\(lhsExpr._expandedDescription(in: childContext)) \(op) \(rhsExpr._expandedDescription(in: childContext))"
     case let .functionCall(value, functionName, arguments):
-      let includeParentheses = arguments.count > 1
+      var argumentContext = childContext
+      argumentContext.includeParenthesesIfNeeded = (arguments.count > 1)
       let argumentList = arguments.lazy
         .map { argument in
-          (argument.label, argument.value.expandedDescription(depth: depth + 1, includingParenthesesIfNeeded: includeParentheses))
+          (argument.label, argument.value._expandedDescription(in: argumentContext))
         }.map { label, value in
           if let label {
             return "\(label): \(value)"
           }
           return value
         }.joined(separator: ", ")
       result = if let value {
-        "\(value.expandedDescription(depth: depth + 1)).\(functionName)(\(argumentList))"
+        "\(value._expandedDescription(in: childContext)).\(functionName)(\(argumentList))"
       } else {
         "\(functionName)(\(argumentList))"
       }
     case let .propertyAccess(value, keyPath):
-      result = "\(value.expandedDescription(depth: depth + 1)).\(keyPath.expandedDescription(depth: depth + 1, includingParenthesesIfNeeded: false))"
+      var keyPathContext = childContext
+      keyPathContext.includeParenthesesIfNeeded = false
+      result = "\(value._expandedDescription(in: childContext)).\(keyPath._expandedDescription(in: keyPathContext))"
+    case let .negation(expression, isParenthetical):
+      childContext.includeParenthesesIfNeeded = !isParenthetical
+      var expandedDescription = expression._expandedDescription(in: childContext)
+      if isParenthetical {
+        expandedDescription = "(\(expandedDescription))"
+      }
+      result = "!\(expandedDescription)"
     }
 
-    // If this expression is at the root of the expression graph and has no
-    // value, don't bother reporting the placeholder string for it.
-    if depth == 0 && runtimeValue == nil {
-      return result
+    // If this expression is at the root of the expression graph...
+    if context.depth == 0 {
+      if runtimeValue == nil {
+        // ... and has no value, don't bother reporting the placeholder string
+        // for it...
+        return result
+      } else if let runtimeValue, runtimeValue.typeInfo.describes(Bool.self) {
+        // ... or if it is a boolean value, also don't bother (because it can be
+        // inferred from context.)
+        return result
+      }
     }
 
     let runtimeValueDescription = runtimeValue.map(String.init(describing:)) ?? "<not evaluated>"
@@ -297,7 +388,7 @@ public struct Expression: Sendable {
       result
     } else if runtimeValueDescription == result {
       result
-    } else if includingParenthesesIfNeeded && depth > 0 {
+    } else if context.includeParenthesesIfNeeded && context.depth > 0 {
       "(\(result) → \(runtimeValueDescription))"
     } else {
       "\(result) → \(runtimeValueDescription)"
@@ -322,6 +413,8 @@ public struct Expression: Sendable {
       }
     case let .propertyAccess(value: value, keyPath: keyPath):
       [value, keyPath]
+    case let .negation(expression, _):
+      [expression]
     }
   }
 

Sources/TestingMacros/Support/ConditionArgumentParsing.swift

@@ -74,7 +74,7 @@ private func _diagnoseTrivialBooleanValue(from expr: ExprSyntax, for macro: some
     default:
       break
     }
-  } else if let literal = _negatedExpression(expr, in: context)?.as(BooleanLiteralExprSyntax.self) {
+  } else if let literal = _negatedExpression(expr)?.0.as(BooleanLiteralExprSyntax.self) {
     // This expression is of the form !true or !false.
     switch literal.literal.tokenKind {
     case .keyword(.true):
@@ -97,11 +97,15 @@ private func _diagnoseTrivialBooleanValue(from expr: ExprSyntax, for macro: some
 ///   negation expression.
 ///
 /// This function handles expressions such as `!foo` or `!(bar)`.
-private func _negatedExpression(_ expr: ExprSyntax, in context: some MacroExpansionContext) -> ExprSyntax? {
+private func _negatedExpression(_ expr: ExprSyntax) -> (ExprSyntax, isParenthetical: Bool)? {
   let expr = removeParentheses(from: expr) ?? expr
   if let op = expr.as(PrefixOperatorExprSyntax.self),
      op.operator.tokenKind == .prefixOperator("!") {
-    return removeParentheses(from: op.expression) ?? op.expression
+    if let negatedExpr = removeParentheses(from: op.expression) {
+      return (negatedExpr, true)
+    } else {
+      return (op.expression, false)
+    }
   }
 
   return nil
@@ -443,6 +447,23 @@ private func _parseCondition(from expr: MemberAccessExprSyntax, for macro: some
   )
 }
 
+/// Parse a condition argument from a property access.
+///
+/// - Parameters:
+///   - expr: The expression that was negated.
+///   - isParenthetical: Whether or not `expression` was enclosed in
+///     parentheses (and the `!` operator was outside it.) This argument
+///     affects how this expression is represented as a string.
+///   - macro: The macro expression being expanded.
+///   - context: The macro context in which the expression is being parsed.
+///
+/// - Returns: An instance of ``Condition`` describing `expr`.
+private func _parseCondition(negating expr: ExprSyntax, isParenthetical: Bool, for macro: some FreestandingMacroExpansionSyntax, in context: some MacroExpansionContext) -> Condition {
+  var result = _parseCondition(from: expr, for: macro, in: context)
+  result.expression = createExpressionExprForNegation(of: result.expression, isParenthetical: isParenthetical)
+  return result
+}
+
 /// Parse a condition argument from an arbitrary expression.
 ///
 /// - Parameters:
@@ -476,6 +497,11 @@ private func _parseCondition(from expr: ExprSyntax, for macro: some Freestanding
     return _parseCondition(from: memberAccessExpr, for: macro, in: context)
   }
 
+  // Handle negation.
+  if let negatedExpr = _negatedExpression(expr) {
+    return _parseCondition(negating: negatedExpr.0, isParenthetical: negatedExpr.isParenthetical, for: macro, in: context)
+  }
+
   // Parentheses are parsed as if they were tuples, so (true && false) appears
   // to the parser as a tuple containing one expression, `true && false`.
   if let expr = removeParentheses(from: expr) {
@@ -496,9 +522,7 @@ private func _parseCondition(from expr: ExprSyntax, for macro: some Freestanding
 ///
 /// - Returns: An instance of ``Condition`` describing `expr`.
 func parseCondition(from expr: ExprSyntax, for macro: some FreestandingMacroExpansionSyntax, in context: some MacroExpansionContext) -> Condition {
+  _diagnoseTrivialBooleanValue(from: expr, for: macro, in: context)
   let result = _parseCondition(from: expr, for: macro, in: context)
-  if result.arguments.count == 1, let onlyArgument = result.arguments.first {
-    _diagnoseTrivialBooleanValue(from: onlyArgument.expression, for: macro, in: context)
-  }
   return result
 }