Add more test coverage, ensure that try #require(throws: Never.self) only

throws if you try to cast the result to `any Error` (can't instantiate `Never`),
add a way to suppress our diagnostics in our own unit tests.

Author: grynspan

Sources/Testing/Expectations/Expectation+Macro.swift

@@ -235,7 +235,7 @@ public macro require<T>(
   _ comment: @autoclosure () -> Comment? = nil,
   sourceLocation: SourceLocation = #_sourceLocation,
   performing expression: () async throws -> R
-) -> E = #externalMacro(module: "TestingMacros", type: "RequireMacro") where E: Error
+) -> E = #externalMacro(module: "TestingMacros", type: "RequireThrowsMacro") where E: Error
 
 /// Check that an expression never throws an error, and throw an error if it
 /// does.

Sources/Testing/Expectations/ExpectationChecking+Macro.swift

@@ -821,18 +821,11 @@ 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
-/// types.
+/// types. It is disfavored so that `#expect(throws: Never.self)` preferentially
+/// returns `Void`.
 ///
 /// - Warning: This function is used to implement the `#expect()` and
 ///   `#require()` macros. Do not call it directly.
@@ -869,7 +862,8 @@ public func __checkClosureCall<E>(
 /// Check that an expression always throws an error.
 ///
 /// This overload is used for `await #expect(throws:) { }` invocations that take
-/// error types.
+/// error types. It is disfavored so that `#expect(throws: Never.self)`
+/// preferentially returns `Void`.
 ///
 /// - Warning: This function is used to implement the `#expect()` and
 ///   `#require()` macros. Do not call it directly.
@@ -923,7 +917,7 @@ public func __checkClosureCall(
   comments: @autoclosure () -> [Comment],
   isRequired: Bool,
   sourceLocation: SourceLocation
-) -> Result<Never?, any Error> {
+) -> Result<Void, any Error> {
   var success = true
   var mismatchExplanationValue: String? = nil
   do {
@@ -940,7 +934,7 @@ public func __checkClosureCall(
     comments: comments(),
     isRequired: isRequired,
     sourceLocation: sourceLocation
-  ).map { _ in nil }
+  ).map { _ in }
 }
 
 /// Check that an expression never throws an error.
@@ -960,7 +954,7 @@ public func __checkClosureCall(
   isRequired: Bool,
   isolation: isolated (any Actor)? = #isolation,
   sourceLocation: SourceLocation
-) async -> Result<Never?, any Error> {
+) async -> Result<Void, any Error> {
   var success = true
   var mismatchExplanationValue: String? = nil
   do {
@@ -977,7 +971,7 @@ public func __checkClosureCall(
     comments: comments(),
     isRequired: isRequired,
     sourceLocation: sourceLocation
-  ).map { _ in nil }
+  ).map { _ in }
 }
 
 // MARK: - Matching instances of equatable errors

Sources/Testing/Support/Additions/ResultAdditions.swift

@@ -37,17 +37,32 @@ extension Result {
 
   /// Handle this instance as if it were returned from a call to `#require()`.
   ///
-  /// If `#require()` is used with a `__check()` function that returns an
-  /// optional value on success, that implies that the value cannot actually be
-  /// `nil` on success and that it's safe to unwrap it. If the value really is
-  /// `nil` (which would be a corner case), the testing library throws an error
-  /// representing an issue of kind ``Issue/Kind-swift.enum/apiMisused``.
+  /// This overload of `__require()` assumes that the result cannot actually be
+  /// `nil` on success. The optionality is part of our ABI contract for the
+  /// `__check()` function family so that we can support uninhabited types and
+  /// "soft" failures.
   ///
   /// - Warning: This function is used to implement the `#expect()` and
   ///   `#require()` macros. Do not call it directly.
-  public func __required<T>() throws -> T where Success == T? {
+  @inlinable public func __required<T>() throws -> T where Success == T? {
+    try get()!
+  }
+
+  /// Handle this instance as if it were returned from a call to `#require()`.
+  ///
+  /// This overload of `__require()` is used by `#require(throws:)`. It has
+  /// special handling for a `nil` result so that `Never.self` (which can't be
+  /// instantiated) can be used as the error type in the macro call.
+  ///
+  /// If the value really is `nil` (i.e. we're dealing with `Never`), the
+  /// testing library throws an error representing an issue of kind
+  /// ``Issue/Kind-swift.enum/apiMisused``.
+  ///
+  /// - Warning: This function is used to implement the `#expect()` and
+  ///   `#require()` macros. Do not call it directly.
+  public func __required<T>() throws -> T where T: Error, 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.")
+      throw APIMisuseError(description: "Could not unwrap 'nil' value of type Optional<\(T.self)>. Consider using #expect(throws:) instead of #require(throws:) here.")
     }
     return result
   }

Sources/TestingMacros/ConditionMacro.swift

@@ -332,6 +332,35 @@ public struct NonOptionalRequireMacro: RefinedConditionMacro {
   }
 }
 
+/// A type describing the expansion of the `#require(throws:)` macro.
+///
+/// This macro makes a best effort to check if the type argument is `Never.self`
+/// (as we only have the syntax tree here) and diagnoses it as redundant if so.
+/// See also ``RequireThrowsNeverMacro`` which is used when full type checking
+/// is contextually available.
+///
+/// This type is otherwise exactly equivalent to ``RequireMacro``.
+public struct RequireThrowsMacro: RefinedConditionMacro {
+  public typealias Base = RequireMacro
+
+  public static func expansion(
+    of macro: some FreestandingMacroExpansionSyntax,
+    in context: some MacroExpansionContext
+  ) throws -> ExprSyntax {
+    if let argument = macro.arguments.first {
+      let argumentTokens: [String] = argument.expression.tokens(viewMode: .fixedUp).lazy
+        .filter { $0.tokenKind != .period }
+        .map(\.textWithoutBackticks)
+      if argumentTokens == ["Swift", "Never", "self"] || argumentTokens == ["Never", "self"] {
+        context.diagnose(.requireThrowsNeverIsRedundant(argument.expression, in: macro))
+      }
+    }
+
+    // Perform the normal macro expansion for #require().
+    return try RequireMacro.expansion(of: macro, in: context)
+  }
+}
+
 /// A type describing the expansion of the `#require(throws:)` macro when it is
 /// passed `Never.self`, which is redundant.
 ///

Sources/TestingMacros/Support/Additions/MacroExpansionContextAdditions.swift

@@ -80,30 +80,60 @@ extension MacroExpansionContext {
 // MARK: -
 
 extension MacroExpansionContext {
+  /// Whether or not our generated warnings are suppressed in the current
+  /// lexical context.
+  ///
+  /// The value of this property is `true` if the current lexical context
+  /// contains a node with the `@_semantics("testing.macros.nowarnings")`
+  /// attribute applied to it.
+  ///
+  /// - Warning: This functionality is not part of the public interface of the
+  ///   testing library. It may be modified or removed in a future update.
+  var areWarningsSuppressed: Bool {
+    for lexicalContext in self.lexicalContext {
+      guard let lexicalContext = lexicalContext.asProtocol((any WithAttributesSyntax).self) else {
+        continue
+      }
+      for attribute in lexicalContext.attributes {
+        if case let .attribute(attribute) = attribute,
+           attribute.attributeNameText == "_semantics",
+           case let .string(argument) = attribute.arguments,
+           argument.representedLiteralValue == "testing.macros.nowarnings" {
+          return true
+        }
+      }
+    }
+    return false
+  }
+
   /// Emit a diagnostic message.
   ///
   /// - Parameters:
   ///   - message: The diagnostic message to emit. The `node` and `position`
   ///     arguments to `Diagnostic.init()` are derived from the message's
   ///     `syntax` property.
   func diagnose(_ message: DiagnosticMessage) {
-    diagnose(
-      Diagnostic(
-        node: message.syntax,
-        position: message.syntax.positionAfterSkippingLeadingTrivia,
-        message: message,
-        fixIts: message.fixIts
-      )
-    )
+    diagnose(CollectionOfOne(message))
   }
 
   /// Emit a sequence of diagnostic messages.
   ///
   /// - Parameters:
   ///   - messages: The diagnostic messages to emit.
-  func diagnose(_ messages: some Sequence<DiagnosticMessage>) {
+  func diagnose(_ messages: some Collection<DiagnosticMessage>) {
+    lazy var areWarningsSuppressed = areWarningsSuppressed
     for message in messages {
-      diagnose(message)
+      if message.severity == .warning && areWarningsSuppressed {
+        continue
+      }
+      diagnose(
+        Diagnostic(
+          node: message.syntax,
+          position: message.syntax.positionAfterSkippingLeadingTrivia,
+          message: message,
+          fixIts: message.fixIts
+        )
+      )
     }
   }
 

Sources/TestingMacros/TestingMacrosMain.swift

@@ -24,6 +24,7 @@ struct TestingMacrosMain: CompilerPlugin {
       RequireMacro.self,
       AmbiguousRequireMacro.self,
       NonOptionalRequireMacro.self,
+      RequireThrowsMacro.self,
       RequireThrowsNeverMacro.self,
       ExitTestExpectMacro.self,
       ExitTestRequireMacro.self,

Tests/TestingMacrosTests/ConditionMacroTests.swift

@@ -354,6 +354,8 @@ struct ConditionMacroTests {
 
   @Test("#require(throws: Never.self) produces a diagnostic",
     arguments: [
+      "#requireThrows(throws: Swift.Never.self)",
+      "#requireThrows(throws: Never.self)",
       "#requireThrowsNever(throws: Never.self)",
     ]
   )

Tests/TestingMacrosTests/TestSupport/Parse.swift

@@ -23,6 +23,7 @@ fileprivate let allMacros: [String: any Macro.Type] = [
   "require": RequireMacro.self,
   "requireAmbiguous": AmbiguousRequireMacro.self, // different name needed only for unit testing
   "requireNonOptional": NonOptionalRequireMacro.self, // different name needed only for unit testing
+  "requireThrows": RequireThrowsMacro.self, // different name needed only for unit testing
   "requireThrowsNever": RequireThrowsNeverMacro.self, // different name needed only for unit testing
   "expectExitTest": ExitTestRequireMacro.self, // different name needed only for unit testing
   "requireExitTest": ExitTestRequireMacro.self, // different name needed only for unit testing

Tests/TestingTests/IssueTests.swift

@@ -992,6 +992,25 @@ final class IssueTests: XCTestCase {
     await fulfillment(of: [errorCaught, apiMisused, expectationFailed], timeout: 0.0)
   }
 
+  @_semantics("testing.macros.nowarnings")
+  func testErrorCheckingWithRequire_ResultValueIsNever_VariousSyntaxes() throws {
+    // Basic expressions succeed and don't diagnose.
+    #expect(throws: Never.self) {}
+    try #require(throws: Never.self) {}
+
+    // Casting to specific types succeeds and doesn't diagnose.
+    let _: Void = try #require(throws: Never.self) {}
+    let _: Any = try #require(throws: Never.self) {}
+
+    // Casting to any Error throws an API misuse error because Never cannot be
+    // instantiated. NOTE: inner function needed for lexical context.
+    @_semantics("testing.macros.nowarnings")
+    func castToAnyError() throws {
+      let _: any Error = try #require(throws: Never.self) {}
+    }
+    #expect(throws: APIMisuseError.self, performing: castToAnyError)
+  }
+
   func testFail() async throws {
     var configuration = Configuration()
     configuration.eventHandler = { event, _ in