Return the thrown error from #expect(throws:) and #require(throws:).

This PR changes the signatures of the various `throws:` overloads of `#expect`
and `#require` so that on success they return the error that was thrown rather
than `Void`. This then allows more ergonomic inspection of the error's
properties:

```swift
let error = try #require(throws: MyError.self) {
  try f()
}
 #expect(error.hasWidget)
 #expect(error.userName == "John Smith")
```

It is not possible to overload a macro or function solely by return type without
the compiler reporting `Ambiguous use of 'f()'`, so we are not able to stage
this change in using `@_spi(Experimental)` without breaking test code that
already imports our SPI.

This change is potentially source-breaking for tests that inadvertently forward
the result of these macro invocations to an enclosing scope. For example, the
compiler will start emitting a warning here:

```swift
func bar(_ pfoo: UnsafePointer<Foo>) throws { ... }

withUnsafePointer(to: foo) { pfoo in // ⚠️ Result of call to 'withUnsafePointer(to:_:)' is unused
  #expect(throws: BadFooError.self) {
    bar(pfoo)
  }
}
```

This warning can be suppressed by assigning the result of `#expect` (or of
`withUnsafePointer(to:_:)`) to `_`:

```swift
func bar(_ pfoo: UnsafePointer<Foo>) throws { ... }

withUnsafePointer(to: foo) { pfoo in
  _ = #expect(throws: BadFooError.self) {
    bar(pfoo)
  }
}
```

Because `#expect` and `#require` are macros, they cannot be referenced by name
like functions, so you cannot assign them to variables (and then run into
trouble with the types of those variables.)

Author: grynspan

Diff for: Sources/Testing/Expectations/Expectation+Macro.swift

@@ -142,6 +142,9 @@ public macro require<T>(
 ///     issues should be attributed.
 ///   - expression: The expression to be evaluated.
 ///
+/// - Returns: If the expectation passes, the instance of `errorType` that was
+///   thrown by `expression`. If the expectation fails, the result is `nil`.
+///
 /// Use this overload of `#expect()` when the expression `expression` _should_
 /// throw an error of a given type:
 ///
@@ -158,7 +161,7 @@ public macro require<T>(
 /// discarded.
 ///
 /// If the thrown error need only equal another instance of [`Error`](https://developer.apple.com/documentation/swift/error),
-/// use ``expect(throws:_:sourceLocation:performing:)-1xr34`` instead.
+/// use ``expect(throws:_:sourceLocation:performing:)-7du1h`` instead.
 ///
 /// ## Expressions that should never throw
 ///
@@ -181,12 +184,13 @@ public macro require<T>(
 /// fail when an error is thrown by `expression`, rather than to explicitly
 /// check that an error is _not_ thrown by it, do not use this macro. Instead,
 /// simply call the code in question and allow it to throw an error naturally.
+@discardableResult
 @freestanding(expression) public macro expect<E, R>(
   throws errorType: E.Type,
   _ comment: @autoclosure () -> Comment? = nil,
   sourceLocation: SourceLocation = #_sourceLocation,
   performing expression: () async throws -> R
-) = #externalMacro(module: "TestingMacros", type: "ExpectMacro") where E: Error
+) -> E? = #externalMacro(module: "TestingMacros", type: "ExpectMacro") where E: Error
 
 /// Check that an expression always throws an error of a given type, and throw
 /// an error if it does not.
@@ -200,6 +204,8 @@ public macro require<T>(
 ///     issues should be attributed.
 ///   - expression: The expression to be evaluated.
 ///
+/// - Returns: The instance of `errorType` that was thrown by `expression`.
+///
 /// - Throws: An instance of ``ExpectationFailedError`` if `expression` does not
 ///   throw a matching error. The error thrown by `expression` is not rethrown.
 ///
@@ -219,16 +225,17 @@ public macro require<T>(
 /// is thrown. Any value returned by `expression` is discarded.
 ///
 /// If the thrown error need only equal another instance of [`Error`](https://developer.apple.com/documentation/swift/error),
-/// use ``require(throws:_:sourceLocation:performing:)-7v83e`` instead.
+/// use ``require(throws:_:sourceLocation:performing:)-4djuw`` instead.
 ///
 /// If `expression` should _never_ throw, simply invoke the code without using
 /// this macro. The test will then fail if an error is thrown.
+@discardableResult
 @freestanding(expression) public macro require<E, R>(
   throws errorType: E.Type,
   _ comment: @autoclosure () -> Comment? = nil,
   sourceLocation: SourceLocation = #_sourceLocation,
   performing expression: () async throws -> R
-) = #externalMacro(module: "TestingMacros", type: "RequireMacro") where E: Error
+) -> E = #externalMacro(module: "TestingMacros", type: "RequireMacro") where E: Error
 
 /// Check that an expression never throws an error, and throw an error if it
 /// does.
@@ -261,6 +268,10 @@ public macro require<R>(
 ///     issues should be attributed.
 ///   - expression: The expression to be evaluated.
 ///
+/// - Returns: If the expectation passes, the instance of `E` that was thrown by
+///   `expression` and is equal to `error`. If the expectation fails, the result
+///   is `nil`.
+///
 /// Use this overload of `#expect()` when the expression `expression` _should_
 /// throw a specific error:
 ///
@@ -276,13 +287,14 @@ public macro require<R>(
 /// in the current task. Any value returned by `expression` is discarded.
 ///
 /// If the thrown error need only be an instance of a particular type, use
-/// ``expect(throws:_:sourceLocation:performing:)-79piu`` instead.
+/// ``expect(throws:_:sourceLocation:performing:)-1hfms`` instead.
+@discardableResult
 @freestanding(expression) public macro expect<E, R>(
   throws error: E,
   _ comment: @autoclosure () -> Comment? = nil,
   sourceLocation: SourceLocation = #_sourceLocation,
   performing expression: () async throws -> R
-) = #externalMacro(module: "TestingMacros", type: "ExpectMacro") where E: Error & Equatable
+) -> E? = #externalMacro(module: "TestingMacros", type: "ExpectMacro") where E: Error & Equatable
 
 /// Check that an expression always throws a specific error, and throw an error
 /// if it does not.
@@ -293,6 +305,9 @@ public macro require<R>(
 ///   - sourceLocation: The source location to which recorded expectations and
 ///     issues should be attributed.
 ///   - expression: The expression to be evaluated.
+
+/// - Returns: The instance of `E` that was thrown by `expression` and is equal
+///   to `error`.
 ///
 /// - Throws: An instance of ``ExpectationFailedError`` if `expression` does not
 ///   throw a matching error. The error thrown by `expression` is not rethrown.
@@ -313,13 +328,14 @@ public macro require<R>(
 /// Any value returned by `expression` is discarded.
 ///
 /// If the thrown error need only be an instance of a particular type, use
-/// ``require(throws:_:sourceLocation:performing:)-76bjn`` instead.
+/// ``require(throws:_:sourceLocation:performing:)-7n34r`` instead.
+@discardableResult
 @freestanding(expression) public macro require<E, R>(
   throws error: E,
   _ comment: @autoclosure () -> Comment? = nil,
   sourceLocation: SourceLocation = #_sourceLocation,
   performing expression: () async throws -> R
-) = #externalMacro(module: "TestingMacros", type: "RequireMacro") where E: Error & Equatable
+) -> E = #externalMacro(module: "TestingMacros", type: "RequireMacro") where E: Error & Equatable
 
 // MARK: - Arbitrary error matching
 
@@ -333,6 +349,9 @@ public macro require<R>(
 ///   - errorMatcher: A closure to invoke when `expression` throws an error that
 ///     indicates if it matched or not.
 ///
+/// - Returns: If the expectation passes, the error that was thrown by
+///   `expression`. If the expectation fails, the result is `nil`.
+///
 /// Use this overload of `#expect()` when the expression `expression` _should_
 /// throw an error, but the logic to determine if the error matches is complex:
 ///
@@ -353,15 +372,16 @@ public macro require<R>(
 /// discarded.
 ///
 /// If the thrown error need only be an instance of a particular type, use
-/// ``expect(throws:_:sourceLocation:performing:)-79piu`` instead. If the thrown
+/// ``expect(throws:_:sourceLocation:performing:)-1hfms`` instead. If the thrown
 /// error need only equal another instance of [`Error`](https://developer.apple.com/documentation/swift/error),
-/// use ``expect(throws:_:sourceLocation:performing:)-1xr34`` instead.
+/// use ``expect(throws:_:sourceLocation:performing:)-7du1h`` instead.
+@discardableResult
 @freestanding(expression) public macro expect<R>(
   _ comment: @autoclosure () -> Comment? = nil,
   sourceLocation: SourceLocation = #_sourceLocation,
   performing expression: () async throws -> R,
   throws errorMatcher: (any Error) async throws -> Bool
-) = #externalMacro(module: "TestingMacros", type: "ExpectMacro")
+) -> (any Error)? = #externalMacro(module: "TestingMacros", type: "ExpectMacro")
 
 /// Check that an expression always throws an error matching some condition, and
 /// throw an error if it does not.
@@ -374,6 +394,8 @@ public macro require<R>(
 ///   - errorMatcher: A closure to invoke when `expression` throws an error that
 ///     indicates if it matched or not.
 ///
+/// - Returns: The error that was thrown by `expression`.
+///
 /// - Throws: An instance of ``ExpectationFailedError`` if `expression` does not
 ///   throw a matching error. The error thrown by `expression` is not rethrown.
 ///
@@ -398,18 +420,19 @@ public macro require<R>(
 /// discarded.
 ///
 /// If the thrown error need only be an instance of a particular type, use
-/// ``require(throws:_:sourceLocation:performing:)-76bjn`` instead. If the thrown error need
+/// ``require(throws:_:sourceLocation:performing:)-7n34r`` instead. If the thrown error need
 /// only equal another instance of [`Error`](https://developer.apple.com/documentation/swift/error),
-/// use ``require(throws:_:sourceLocation:performing:)-7v83e`` instead.
+/// use ``require(throws:_:sourceLocation:performing:)-4djuw`` instead.
 ///
 /// If `expression` should _never_ throw, simply invoke the code without using
 /// this macro. The test will then fail if an error is thrown.
+@discardableResult
 @freestanding(expression) public macro require<R>(
   _ comment: @autoclosure () -> Comment? = nil,
   sourceLocation: SourceLocation = #_sourceLocation,
   performing expression: () async throws -> R,
   throws errorMatcher: (any Error) async throws -> Bool
-) = #externalMacro(module: "TestingMacros", type: "RequireMacro")
+) -> any Error = #externalMacro(module: "TestingMacros", type: "RequireMacro")
 
 // MARK: - Exit tests
 
@@ -425,7 +448,7 @@ public macro require<R>(
 ///     issues should be attributed.
 ///   - expression: The expression to be evaluated.
 ///
-/// - Returns: If the exit test passed, an instance of ``ExitTestArtifacts``
+/// - Returns: If the exit test passes, an instance of ``ExitTestArtifacts``
 ///   describing the state of the exit test when it exited. If the exit test
 ///   fails, the result is `nil`.
 ///

Diff for: Sources/Testing/Expectations/ExpectationChecking+Macro.swift

@@ -821,6 +821,14 @@ public func __checkCast<V, T>(
 
 // MARK: - Matching errors by type
 
+/// A placeholder type representing `Never` if a test attempts to instantiate it
+/// by calling `#expect(throws:)` and taking the result.
+///
+/// Errors of this type are never thrown; they act as placeholders in `Result`
+/// so that `#expect(throws: Never.self)` always produces `nil` (since `Never`
+/// cannot be instantiated.)
+private struct _CannotInstantiateNeverError: Error {}
+
 /// Check that an expression always throws an error.
 ///
 /// This overload is used for `#expect(throws:) { }` invocations that take error
@@ -835,7 +843,7 @@ public func __checkClosureCall<E>(
   comments: @autoclosure () -> [Comment],
   isRequired: Bool,
   sourceLocation: SourceLocation
-) -> Result<Void, any Error> where E: Error {
+) -> Result<E?, any Error> where E: Error {
   if errorType == Never.self {
     __checkClosureCall(
       throws: Never.self,
@@ -844,7 +852,7 @@ public func __checkClosureCall<E>(
       comments: comments(),
       isRequired: isRequired,
       sourceLocation: sourceLocation
-    )
+    ).map { _ in nil }
   } else {
     __checkClosureCall(
       performing: body,
@@ -854,7 +862,7 @@ public func __checkClosureCall<E>(
       comments: comments(),
       isRequired: isRequired,
       sourceLocation: sourceLocation
-    )
+    ).map { $0 as? E }
   }
 }
 
@@ -873,7 +881,7 @@ public func __checkClosureCall<E>(
   isRequired: Bool,
   isolation: isolated (any Actor)? = #isolation,
   sourceLocation: SourceLocation
-) async -> Result<Void, any Error> where E: Error {
+) async -> Result<E?, any Error> where E: Error {
   if errorType == Never.self {
     await __checkClosureCall(
       throws: Never.self,
@@ -883,7 +891,7 @@ public func __checkClosureCall<E>(
       isRequired: isRequired,
       isolation: isolation,
       sourceLocation: sourceLocation
-    )
+    ).map { _ in nil }
   } else {
     await __checkClosureCall(
       performing: body,
@@ -894,7 +902,7 @@ public func __checkClosureCall<E>(
       isRequired: isRequired,
       isolation: isolation,
       sourceLocation: sourceLocation
-    )
+    ).map { $0 as? E }
   }
 }
 
@@ -915,7 +923,7 @@ public func __checkClosureCall(
   comments: @autoclosure () -> [Comment],
   isRequired: Bool,
   sourceLocation: SourceLocation
-) -> Result<Void, any Error> {
+) -> Result<Never?, any Error> {
   var success = true
   var mismatchExplanationValue: String? = nil
   do {
@@ -932,7 +940,7 @@ public func __checkClosureCall(
     comments: comments(),
     isRequired: isRequired,
     sourceLocation: sourceLocation
-  )
+  ).map { _ in nil }
 }
 
 /// Check that an expression never throws an error.
@@ -952,7 +960,7 @@ public func __checkClosureCall(
   isRequired: Bool,
   isolation: isolated (any Actor)? = #isolation,
   sourceLocation: SourceLocation
-) async -> Result<Void, any Error> {
+) async -> Result<Never?, any Error> {
   var success = true
   var mismatchExplanationValue: String? = nil
   do {
@@ -969,7 +977,7 @@ public func __checkClosureCall(
     comments: comments(),
     isRequired: isRequired,
     sourceLocation: sourceLocation
-  )
+  ).map { _ in nil }
 }
 
 // MARK: - Matching instances of equatable errors
@@ -988,7 +996,7 @@ public func __checkClosureCall<E>(
   comments: @autoclosure () -> [Comment],
   isRequired: Bool,
   sourceLocation: SourceLocation
-) -> Result<Void, any Error> where E: Error & Equatable {
+) -> Result<E?, any Error> where E: Error & Equatable {
   __checkClosureCall(
     performing: body,
     throws: { true == (($0 as? E) == error) },
@@ -997,7 +1005,7 @@ public func __checkClosureCall<E>(
     comments: comments(),
     isRequired: isRequired,
     sourceLocation: sourceLocation
-  )
+  ).map { $0 as? E }
 }
 
 /// Check that an expression always throws an error.
@@ -1015,7 +1023,7 @@ public func __checkClosureCall<E>(
   isRequired: Bool,
   isolation: isolated (any Actor)? = #isolation,
   sourceLocation: SourceLocation
-) async -> Result<Void, any Error> where E: Error & Equatable {
+) async -> Result<E?, any Error> where E: Error & Equatable {
   await __checkClosureCall(
     performing: body,
     throws: { true == (($0 as? E) == error) },
@@ -1025,7 +1033,7 @@ public func __checkClosureCall<E>(
     isRequired: isRequired,
     isolation: isolation,
     sourceLocation: sourceLocation
-  )
+  ).map { $0 as? E }
 }
 
 // MARK: - Arbitrary error matching
@@ -1044,10 +1052,11 @@ public func __checkClosureCall<R>(
   comments: @autoclosure () -> [Comment],
   isRequired: Bool,
   sourceLocation: SourceLocation
-) -> Result<Void, any Error> {
+) -> Result<(any Error)?, any Error> {
   var errorMatches = false
   var mismatchExplanationValue: String? = nil
   var expression = expression
+  var caughtError: (any Error)?
   do {
     let result = try body()
 
@@ -1057,6 +1066,7 @@ public func __checkClosureCall<R>(
     }
     mismatchExplanationValue = explanation
   } catch {
+    caughtError = error
     expression = expression.capturingRuntimeValues(error)
     let secondError = Issue.withErrorRecording(at: sourceLocation) {
       errorMatches = try errorMatcher(error)
@@ -1075,7 +1085,7 @@ public func __checkClosureCall<R>(
     comments: comments(),
     isRequired: isRequired,
     sourceLocation: sourceLocation
-  )
+  ).map { caughtError }
 }
 
 /// Check that an expression always throws an error.
@@ -1093,10 +1103,11 @@ public func __checkClosureCall<R>(
   isRequired: Bool,
   isolation: isolated (any Actor)? = #isolation,
   sourceLocation: SourceLocation
-) async -> Result<Void, any Error> {
+) async -> Result<(any Error)?, any Error> {
   var errorMatches = false
   var mismatchExplanationValue: String? = nil
   var expression = expression
+  var caughtError: (any Error)?
   do {
     let result = try await body()
 
@@ -1106,6 +1117,7 @@ public func __checkClosureCall<R>(
     }
     mismatchExplanationValue = explanation
   } catch {
+    caughtError = error
     expression = expression.capturingRuntimeValues(error)
     let secondError = await Issue.withErrorRecording(at: sourceLocation) {
       errorMatches = try await errorMatcher(error)
@@ -1124,7 +1136,7 @@ public func __checkClosureCall<R>(
     comments: comments(),
     isRequired: isRequired,
     sourceLocation: sourceLocation
-  )
+  ).map { caughtError }
 }
 
 // MARK: - Exit tests