Merge pull request #27 from apple/jgrynspan/112974442-sourcelocation-arg

Allow specifying the source location of `#expect()` and `#require()`.

Author: grynspan

Sources/Testing/Expectations/Expectation+Macro.swift

@@ -15,12 +15,15 @@
 /// - Parameters:
 ///   - condition: The condition to be evaluated.
 ///   - comment: A comment describing the expectation.
+///   - sourceLocation: The source location to which recorded expectations and
+///     issues should be attributed.
 ///
 /// If `condition` evaluates to `false`, an ``Issue`` is recorded for the test
 /// that is running in the current task.
 @freestanding(expression) public macro expect(
   _ condition: Bool,
-  _ comment: @autoclosure () -> Comment? = nil
+  _ comment: @autoclosure () -> Comment? = nil,
+  sourceLocation: SourceLocation = SourceLocation()
 ) = #externalMacro(module: "TestingMacros", type: "ExpectMacro")
 
 /// Check that an expectation has passed after a condition has been evaluated
@@ -29,6 +32,8 @@
 /// - Parameters:
 ///   - condition: The condition to be evaluated.
 ///   - comment: A comment describing the expectation.
+///   - sourceLocation: The source location to which recorded expectations and
+///     issues should be attributed.
 ///
 /// - Throws: An instance of ``ExpectationFailedError`` if `condition` evaluates
 ///   to `false`.
@@ -38,7 +43,8 @@
 /// ``ExpectationFailedError`` is thrown.
 @freestanding(expression) public macro require(
   _ condition: Bool,
-  _ comment: @autoclosure () -> Comment? = nil
+  _ comment: @autoclosure () -> Comment? = nil,
+  sourceLocation: SourceLocation = SourceLocation()
 ) = #externalMacro(module: "TestingMacros", type: "RequireMacro")
 
 // MARK: - Optional checking
@@ -48,6 +54,8 @@
 /// - Parameters:
 ///   - optionalValue: The optional value to be unwrapped.
 ///   - comment: A comment describing the expectation.
+///   - sourceLocation: The source location to which recorded expectations and
+///     issues should be attributed.
 ///
 /// - Returns: The unwrapped value of `value`.
 ///
@@ -57,7 +65,8 @@
 /// in the current task and an instance of ``ExpectationFailedError`` is thrown.
 @freestanding(expression) public macro require<T>(
   _ optionalValue: T?,
-  _ comment: @autoclosure () -> Comment? = nil
+  _ comment: @autoclosure () -> Comment? = nil,
+  sourceLocation: SourceLocation = SourceLocation()
 ) -> T = #externalMacro(module: "TestingMacros", type: "RequireMacro")
 
 // MARK: - Matching errors by type
@@ -69,6 +78,8 @@
 ///     `expression` could throw _any_ error, or the specific type of thrown
 ///     error is unimportant, pass `any Error.self`.
 ///   - comment: A comment describing the expectation.
+///   - sourceLocation: The source location to which recorded expectations and
+///     issues should be attributed.
 ///   - expression: The expression to be evaluated.
 ///
 /// Use this overload of `#expect()` when the expression `expression` _should_
@@ -87,18 +98,22 @@
 /// discarded.
 ///
 /// If the thrown error need only equal another instance of [`Error`](https://developer.apple.com/documentation/swift/error),
-/// use ``expect(throws:_:performing:)-1s3lx`` instead. If `expression` should
-/// _never_ throw any error, use ``expect(throws:_:performing:)-jtjw`` instead.
+/// use ``expect(throws:_:sourceLocation:performing:)-1xr34`` instead. If
+/// `expression` should _never_ throw any error, use
+/// ``expect(throws:_:sourceLocation:performing:)-5lzjz`` instead.
 @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
 
 /// Check that an expression never throws an error.
 ///
 /// - Parameters:
 ///   - comment: A comment describing the expectation.
+///   - sourceLocation: The source location to which recorded expectations and
+///     issues should be attributed.
 ///   - expression: The expression to be evaluated.
 ///
 /// Use this overload of `#expect()` when the expression `expression` should
@@ -123,12 +138,13 @@
 /// naturally.
 ///
 /// If the thrown error need only be an instance of a particular type, use
-/// ``expect(throws:_:performing:)-2j0od`` instead. If the thrown error need
-/// only equal another instance of [`Error`](https://developer.apple.com/documentation/swift/error),
-/// use ``expect(throws:_:performing:)-1s3lx`` instead.
+/// ``expect(throws:_:sourceLocation:performing:)-79piu`` 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.
 @freestanding(expression) public macro expect<R>(
   throws _: Never.Type,
   _ comment: @autoclosure () -> Comment? = nil,
+  sourceLocation: SourceLocation = SourceLocation(),
   performing expression: () async throws -> R
 ) = #externalMacro(module: "TestingMacros", type: "ExpectMacro")
 
@@ -140,6 +156,8 @@
 ///     `expression` could throw _any_ error, or the specific type of thrown
 ///     error is unimportant, pass `any Error.self`.
 ///   - comment: A comment describing the expectation.
+///   - sourceLocation: The source location to which recorded expectations and
+///     issues should be attributed.
 ///   - expression: The expression to be evaluated.
 ///
 /// - Throws: An instance of ``ExpectationFailedError`` if `expression` does not
@@ -161,13 +179,14 @@
 /// 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:_:performing:)-84jir`` instead.
+/// use ``require(throws:_:sourceLocation:performing:)-7v83e`` instead.
 ///
 /// If `expression` should _never_ throw, simply invoke the code without using
 /// this macro. The test will then fail if an error is thrown.
 @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
 
@@ -176,6 +195,8 @@
 ///
 /// - Parameters:
 ///   - comment: A comment describing the expectation.
+///   - sourceLocation: The source location to which recorded expectations and
+///     issues should be attributed.
 ///   - expression: The expression to be evaluated.
 ///
 /// - Throws: An instance of ``ExpectationFailedError`` if `expression` throws
@@ -184,6 +205,7 @@
 @freestanding(expression) public macro require<R>(
   throws _: Never.Type,
   _ comment: @autoclosure () -> Comment? = nil,
+  sourceLocation: SourceLocation = SourceLocation(),
   performing expression: () async throws -> R
 ) = #externalMacro(module: "TestingMacros", type: "RequireMacro")
 
@@ -194,6 +216,8 @@
 /// - Parameters:
 ///   - error: The error that is expected to be thrown.
 ///   - comment: A comment describing the expectation.
+///   - sourceLocation: The source location to which recorded expectations and
+///     issues should be attributed.
 ///   - expression: The expression to be evaluated.
 ///
 /// Use this overload of `#expect()` when the expression `expression` _should_
@@ -211,11 +235,13 @@
 /// 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:_:performing:)-2j0od`` instead. If `expression` should
-/// _never_ throw any error, use ``expect(throws:_:performing:)-jtjw`` instead.
+/// ``expect(throws:_:sourceLocation:performing:)-79piu`` instead. If
+/// `expression` should _never_ throw any error, use
+/// ``expect(throws:_:sourceLocation:performing:)-5lzjz`` instead.
 @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
 
@@ -225,6 +251,8 @@
 /// - Parameters:
 ///   - error: The error that is expected to be thrown.
 ///   - comment: A comment describing the expectation.
+///   - sourceLocation: The source location to which recorded expectations and
+///     issues should be attributed.
 ///   - expression: The expression to be evaluated.
 ///
 /// - Throws: An instance of ``ExpectationFailedError`` if `expression` does not
@@ -246,10 +274,11 @@
 /// Any value returned by `expression` is discarded.
 ///
 /// If the thrown error need only be an instance of a particular type, use
-/// ``require(throws:_:performing:)-8762f`` instead.
+/// ``require(throws:_:sourceLocation:performing:)-76bjn`` instead.
 @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
 
@@ -259,6 +288,8 @@
 ///
 /// - Parameters:
 ///   - comment: A comment describing the expectation.
+///   - sourceLocation: The source location to which recorded expectations and
+///     issues should be attributed.
 ///   - expression: The expression to be evaluated.
 ///   - errorMatcher: A closure to invoke when `expression` throws an error that
 ///     indicates if it matched or not.
@@ -283,12 +314,14 @@
 /// discarded.
 ///
 /// If the thrown error need only be an instance of a particular type, use
-/// ``expect(throws:_:performing:)-2j0od`` instead. If the thrown error need
-/// only equal another instance of [`Error`](https://developer.apple.com/documentation/swift/error),
-/// use ``expect(throws:_:performing:)-1s3lx`` instead. If an error should
-/// _never_ be thrown, use ``expect(throws:_:performing:)-jtjw`` instead.
+/// ``expect(throws:_:sourceLocation:performing:)-79piu`` 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. If an
+/// error should _never_ be thrown, use
+/// ``expect(throws:_:sourceLocation:performing:)-5lzjz`` instead.
 @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")
@@ -298,6 +331,8 @@
 ///
 /// - Parameters:
 ///   - comment: A comment describing the expectation.
+///   - sourceLocation: The source location to which recorded expectations and
+///     issues should be attributed.
 ///   - expression: The expression to be evaluated.
 ///   - errorMatcher: A closure to invoke when `expression` throws an error that
 ///     indicates if it matched or not.
@@ -326,14 +361,15 @@
 /// discarded.
 ///
 /// If the thrown error need only be an instance of a particular type, use
-/// ``require(throws:_:performing:)-8762f`` instead. If the thrown error need
+/// ``require(throws:_:sourceLocation:performing:)-76bjn`` instead. If the thrown error need
 /// only equal another instance of [`Error`](https://developer.apple.com/documentation/swift/error),
-/// use ``require(throws:_:performing:)-84jir`` instead.
+/// use ``require(throws:_:sourceLocation:performing:)-7v83e`` instead.
 ///
 /// If `expression` should _never_ throw, simply invoke the code without using
 /// this macro. The test will then fail if an error is thrown.
 @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")

Sources/Testing/Issues/Issue+Recording.swift

@@ -81,8 +81,8 @@ extension Issue {
   /// - Returns: The issue that was recorded.
   ///
   /// Use this function if, while running a test, an issue occurs that cannot be
-  /// represented as an expectation (using the ``expect(_:_:)`` or
-  /// ``require(_:_:)-6lago`` macros.)
+  /// represented as an expectation (using the ``expect(_:_:sourceLocation:)``
+  /// or ``require(_:_:sourceLocation:)-5l63q`` macros.)
   @discardableResult public static func record(
     _ comment: Comment? = nil,
     fileID: String = #fileID,

Sources/Testing/Issues/Issue.swift

@@ -17,7 +17,7 @@ public struct Issue: Sendable {
     case unconditional
 
     /// An issue due to a failed expectation, such as those produced by
-    /// ``expect(_:_:)``.
+    /// ``expect(_:_:sourceLocation:)``.
     ///
     /// - Parameters:
     ///   - expectation: The expectation that failed.

Sources/Testing/Testing.docc/ExpectThrows.md

@@ -29,17 +29,17 @@ runtime not to mark the test as failing when those issues occur.
 
 ### Validating that errors are thrown
 
-- ``expect(throws:_:performing:)-2j0od``
-- ``expect(throws:_:performing:)-1s3lx``
-- ``expect(_:performing:throws:)``
-- ``require(throws:_:performing:)-8762f``
-- ``require(throws:_:performing:)-84jir``
-- ``require(_:performing:throws:)``
+- ``expect(throws:_:sourceLocation:performing:)-79piu``
+- ``expect(throws:_:sourceLocation:performing:)-1xr34``
+- ``expect(_:sourceLocation:performing:throws:)``
+- ``require(throws:_:sourceLocation:performing:)-76bjn``
+- ``require(throws:_:sourceLocation:performing:)-7v83e``
+- ``require(_:sourceLocation:performing:throws:)``
 
 ### Validating that errors are not thrown
 
-- ``expect(throws:_:performing:)-jtjw``
-- ``require(throws:_:performing:)-4a80i``
+- ``expect(throws:_:sourceLocation:performing:)-5lzjz``
+- ``require(throws:_:sourceLocation:performing:)-36uzc``
 
 ### Recording known issues in tests
 

Sources/Testing/Testing.docc/Expectations.md

@@ -21,9 +21,9 @@ built-in expectation APIs.
 
 ### Validating behavior using expectations
 
-- ``expect(_:_:)``
-- ``require(_:_:)-6lago``
-- ``require(_:_:)-3wq2g``
+- ``expect(_:_:sourceLocation:)``
+- ``require(_:_:sourceLocation:)-5l63q``
+- ``require(_:_:sourceLocation:)-6w9oo``
 
 ### Validating asynchronous behavior using confirmations
 

Sources/Testing/Testing.docc/MigratingFromXCTest.md

@@ -193,9 +193,10 @@ see <doc:DefiningTests>.
 XCTest uses a family of approximately 40 functions to assert test requirements.
 These functions are collectively referred to as
 [`XCTAssert()`](https://developer.apple.com/documentation/xctest/1500669-xctassert).
-The testing library has two replacements, ``expect(_:_:)`` and
-``require(_:_:)-6lago``. They both behave similarly to `XCTAssert()` except that
-``require(_:_:)-6lago`` will throw an error if its condition is not met:
+The testing library has two replacements, ``expect(_:_:sourceLocation:)`` and
+``require(_:_:sourceLocation:)-5l63q``. They both behave similarly to
+`XCTAssert()` except that ``require(_:_:sourceLocation:)-5l63q`` will throw an
+error if its condition is not met:
 
 @Row {
   @Column {
@@ -232,8 +233,8 @@ The testing library has two replacements, ``expect(_:_:)`` and
 
 XCTest also has a function, [`XCTUnwrap()`](https://developer.apple.com/documentation/xctest/3380195-xctunwrap),
 that tests if an optional value is `nil` and throws an error if it is. When
-using the testing library, you can use ``require(_:_:)-3wq2g`` with optional
-expressions to unwrap them:
+using the testing library, you can use ``require(_:_:sourceLocation:)-6w9oo``
+with optional expressions to unwrap them:
 
 @Row {
   @Column {