Adopt typed throws in the implementation of #expect()/#require().

This PR adopts typed throws (`throws(E)` instead of `throws`) in the `#expect()`
and `#require()` macros' declarations and in their implementations. In
particular, the return type of the implementation functions changes from
`Result<R, any Error>` to `Result<R, ExpectationFailedError>` and all
implementation functions that take a closure have been updated with an
additional generic `E` parameter.

`#expect(throws:)` and `#require(throws:)` take two generic error types,
`EExpected` and `EActual`. The former is the error type specified by the test
author, while the latter is the actual error type inferred from the body
closure. In common usage, both will resolve to `any Error`.

The deprecated `#expect {} throws: {}` and `#require {} throws: {}` variants are
marked `@_unavailableInEmbedded` and continue to use `any Error`.

Author: grynspan

Sources/Testing/ExitTests/ExitTest.swift

@@ -466,7 +466,7 @@ func callExitTest(
   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:).")
   }

Sources/Testing/Expectations/Expectation+Macro.swift

@@ -19,7 +19,7 @@ extension Result {
   ///
   /// - Warning: This function is used to implement the `#expect()` and
   ///   `#require()` macros. Do not call it directly.
-  @inlinable public func __required() throws -> Success {
+  @inlinable public func __required() throws(Failure) -> Success {
     try get()
   }
 }
@@ -48,7 +48,7 @@ extension Result {
   ///
   /// - Warning: This function is used to implement the `#expect()` and
   ///   `#require()` macros. Do not call it directly.
-  @discardableResult public func __required<T>() throws -> T where Success == T? {
+  @discardableResult public func __required<T>() throws(any Error) -> T where Success == T? {
     guard let result = try get() else {
       throw APIMisuseError(description: "Could not unwrap 'nil' value of type Optional<\(T.self)>. Consider using #expect() instead of #require() here.")
     }

Sources/Testing/Expectations/ExpectationChecking+Macro.swift

@@ -65,11 +65,11 @@ the test when the code doesn't satisfy a requirement, use
 ### Checking that errors are thrown
 
 - <doc:testing-for-errors-in-swift-code>
-- ``expect(throws:_:sourceLocation:performing:)-1hfms``
-- ``expect(throws:_:sourceLocation:performing:)-7du1h``
+- ``expect(throws:_:sourceLocation:performing:)-7p3ic``
+- ``expect(throws:_:sourceLocation:performing:)-3y3oo``
 - ``expect(_:sourceLocation:performing:throws:)``
-- ``require(throws:_:sourceLocation:performing:)-7n34r``
-- ``require(throws:_:sourceLocation:performing:)-4djuw``
+- ``require(throws:_:sourceLocation:performing:)-1zgzw``
+- ``require(throws:_:sourceLocation:performing:)-5qhyv``
 - ``require(_:sourceLocation:performing:throws:)``
 
 ### Checking how processes exit

Sources/Testing/Support/Additions/ResultAdditions.swift

@@ -26,7 +26,7 @@ If the code throws an error, then your test fails.
 
 To check that the code under test throws a specific error, or to continue a
 longer test function after the code throws an error, pass that error as the
-first argument of ``expect(throws:_:sourceLocation:performing:)-7du1h``, and
+first argument of ``expect(throws:_:sourceLocation:performing:)-3y3oo``, and
 pass a closure that calls the code under test:
 
 ```swift
@@ -48,8 +48,8 @@ running your test if the code doesn't throw the expected error.
 
 To check that the code under test throws an error of any type, pass
 `(any Error).self` as the first argument to either
-``expect(throws:_:sourceLocation:performing:)-1hfms`` or
-``require(throws:_:sourceLocation:performing:)-7n34r``:
+``expect(throws:_:sourceLocation:performing:)-7p3ic`` or
+``require(throws:_:sourceLocation:performing:)-1zgzw``:
 
 ```swift
 @Test func cannotAddToppingToPizzaBeforeStartOfList() {
@@ -81,7 +81,7 @@ the error to `Never`:
 If the closure throws _any_ error, the testing library records an issue.
 If you need the test to stop when the code throws an error, include the
 code inline in the test function instead of wrapping it in a call to
-``expect(throws:_:sourceLocation:performing:)-7du1h``.
+``expect(throws:_:sourceLocation:performing:)-3y3oo``.
 
 ## Inspect an error thrown by your code
 

Sources/Testing/Testing.docc/Expectations.md

@@ -511,12 +511,14 @@ final class IssueTests: XCTestCase {
 
     let randomNumber = Int.random(in: 0 ... .max)
     await Test {
+#if !hasFeature(Embedded)
       #expect {
         asyncNotRequired()
         throw MyError()
       } throws: {
         $0 is MyError
       }
+#endif
       #expect(throws: MyError.self) {
         asyncNotRequired()
         throw MyError()
@@ -541,7 +543,11 @@ final class IssueTests: XCTestCase {
 
   func testErrorCheckingWithExpect_Mismatching() async throws {
     let expectationFailed = expectation(description: "Expectation failed")
+#if !hasFeature(Embedded)
     expectationFailed.expectedFulfillmentCount = 13
+#else
+    expectationFailed.expectedFulfillmentCount = 10
+#endif
 
     var configuration = Configuration()
     configuration.eventHandler = { event, _ in
@@ -559,11 +565,13 @@ final class IssueTests: XCTestCase {
     let randomNumber = Int.random(in: 0 ... .max)
 
     await Test {
+#if !hasFeature(Embedded)
       #expect {
         asyncNotRequired()
       } throws: {
         $0 is MyError
       }
+#endif
       #expect(throws: MyError.self) {
         asyncNotRequired()
       }
@@ -582,11 +590,13 @@ final class IssueTests: XCTestCase {
       #expect(throws: MyError()) {
         throw MyDescriptiveError(description: "something wrong")
       }
+#if !hasFeature(Embedded)
       #expect {
         throw MyDescriptiveError(description: "something wrong")
       } throws: {
         _ in false
       }
+#endif
       #expect(throws: Never.self) {
         throw MyError()
       }
@@ -600,12 +610,14 @@ final class IssueTests: XCTestCase {
       #expect(throws: MyError.self) {
         try nonVoidReturning()
       }
+#if !hasFeature(Embedded)
       #expect {
         throw MyError()
       } throws: { error in
         let parameterizedError = try #require(error as? MyParameterizedError)
         return parameterizedError.index == 123
       }
+#endif
     }.run(configuration: configuration)
 
     await fulfillment(of: [expectationFailed], timeout: 0.0)
@@ -681,11 +693,13 @@ final class IssueTests: XCTestCase {
 
     let randomNumber = Int.random(in: 0 ... .max)
     await Test {
+#if !hasFeature(Embedded)
       await #expect { () async throws in
         throw MyError()
       } throws: {
         $0 is MyError
       }
+#endif
       await #expect(throws: MyError.self) { () async throws in
         throw MyError()
       }
@@ -708,7 +722,11 @@ final class IssueTests: XCTestCase {
 
   func testErrorCheckingWithExpectAsync_Mismatching() async throws {
     let expectationFailed = expectation(description: "Expectation failed")
+#if !hasFeature(Embedded)
     expectationFailed.expectedFulfillmentCount = 13
+#else
+    expectationFailed.expectedFulfillmentCount = 10
+#endif
 
     var configuration = Configuration()
     configuration.eventHandler = { event, _ in
@@ -724,9 +742,11 @@ final class IssueTests: XCTestCase {
 
     let randomNumber = Int.random(in: 0 ... .max)
     await Test {
+#if !hasFeature(Embedded)
       await #expect { () async in } throws: {
         $0 is MyError
       }
+#endif
       await #expect(throws: MyError.self) { () async in }
       await #expect(throws: MyParameterizedError(index: randomNumber)) { () async in }
       await #expect(throws: MyError.self) { () async throws in
@@ -741,11 +761,13 @@ final class IssueTests: XCTestCase {
       await #expect(throws: MyError()) { () async throws in
         throw MyDescriptiveError(description: "something wrong")
       }
+#if !hasFeature(Embedded)
       await #expect { () async throws in
         throw MyDescriptiveError(description: "something wrong")
       } throws: {
         _ in false
       }
+#endif
       await #expect(throws: Never.self) { () async throws in
         throw MyError()
       }
@@ -759,12 +781,14 @@ final class IssueTests: XCTestCase {
       await #expect(throws: MyError.self) {
         try await nonVoidReturning()
       }
+#if !hasFeature(Embedded)
       await #expect { () async throws in
         throw MyError()
       } throws: { error in
         let parameterizedError = try #require(error as? MyParameterizedError)
         return parameterizedError.index == 123
       }
+#endif
     }.run(configuration: configuration)
 
     await fulfillment(of: [expectationFailed], timeout: 0.0)
@@ -822,6 +846,7 @@ final class IssueTests: XCTestCase {
     await fulfillment(of: [expectationFailed], timeout: 0.0)
   }
 
+#if !hasFeature(Embedded)
   func testErrorCheckingWithExpect_ThrowingFromErrorMatcher() async throws {
     let errorCaught = expectation(description: "Error matcher's error caught")
     let expectationFailed = expectation(description: "Expectation failed")
@@ -931,6 +956,7 @@ final class IssueTests: XCTestCase {
 
     await fulfillment(of: [errorCaught, expectationFailed], timeout: 0.0)
   }
+#endif
 
   func testErrorCheckingWithExpect_ResultValue() throws {
     let error = #expect(throws: MyDescriptiveError.self) {