From 5f518e83e5c4f6e3cf4abc4331a5a9f5a8a3b467 Mon Sep 17 00:00:00 2001 From: Jonathan Grynspan Date: Fri, 20 Dec 2024 21:54:45 -0500 Subject: [PATCH] Mark `#expect(_:throws:)` and `#require(_:throws:)` as to-be-deprecated. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit These symbols should go through a transition period where they are documented as to-be-deprecated rather than being deprecated outright. My mistake. With this change applied, Xcode treats these macros as deprecated (deemphasizing them in autocomplete, for instance) and DocC marks them as deprecated in an unspecified Swift version, but no warning is emitted if they are used. This is consistent with API marked `API_TO_BE_DEPRECATED` or `deprecated: 100000.0` in Apple's SDKs. > [!NOTE] There is a bug in the DocC compiler that emits a diagnostic of the form: > > > ⚠️ 'require(_:sourceLocation:performing:throws:)' isn't unconditionally deprecated > > This issue is being tracked already with rdar://141785948. Resolves #873. --- .../Proposals/0006-return-errors-from-expect-throws.md | 4 ++-- Sources/Testing/Expectations/Expectation+Macro.swift | 4 ++-- .../Testing.docc/AvailabilityStubs/ExpectComplexThrows.md | 6 +++--- .../AvailabilityStubs/RequireComplexThrows.md | 6 +++--- .../Testing.docc/testing-for-errors-in-swift-code.md | 4 ++-- Tests/TestingTests/IssueTests.swift | 8 -------- 6 files changed, 12 insertions(+), 20 deletions(-) diff --git a/Documentation/Proposals/0006-return-errors-from-expect-throws.md b/Documentation/Proposals/0006-return-errors-from-expect-throws.md index 2f15c02ba..94f25bef8 100644 --- a/Documentation/Proposals/0006-return-errors-from-expect-throws.md +++ b/Documentation/Proposals/0006-return-errors-from-expect-throws.md @@ -105,7 +105,7 @@ is not statically available. The problematic overloads will also be deprecated: -) where E: Error & Equatable +) -> E where E: Error & Equatable -+@available(*, deprecated, message: "Examine the result of '#expect(throws:)' instead.") ++@available(swift, introduced: 6.0, deprecated: 100000.0, message: "Examine the result of '#expect(throws:)' instead.") +@discardableResult @freestanding(expression) public macro expect( _ comment: @autoclosure () -> Comment? = nil, @@ -115,7 +115,7 @@ is not statically available. The problematic overloads will also be deprecated: -) +) -> (any Error)? -+@available(*, deprecated, message: "Examine the result of '#require(throws:)' instead.") ++@available(swift, introduced: 6.0, deprecated: 100000.0, message: "Examine the result of '#require(throws:)' instead.") +@discardableResult @freestanding(expression) public macro require( _ comment: @autoclosure () -> Comment? = nil, diff --git a/Sources/Testing/Expectations/Expectation+Macro.swift b/Sources/Testing/Expectations/Expectation+Macro.swift index c8a691e85..83bf045db 100644 --- a/Sources/Testing/Expectations/Expectation+Macro.swift +++ b/Sources/Testing/Expectations/Expectation+Macro.swift @@ -375,7 +375,7 @@ public macro require( /// ``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:)-7du1h`` instead. -@available(*, deprecated, message: "Examine the result of '#expect(throws:)' instead.") +@available(swift, introduced: 6.0, deprecated: 100000.0, message: "Examine the result of '#expect(throws:)' instead.") @discardableResult @freestanding(expression) public macro expect( _ comment: @autoclosure () -> Comment? = nil, @@ -427,7 +427,7 @@ public macro require( /// /// If `expression` should _never_ throw, simply invoke the code without using /// this macro. The test will then fail if an error is thrown. -@available(*, deprecated, message: "Examine the result of '#require(throws:)' instead.") +@available(swift, introduced: 6.0, deprecated: 100000.0, message: "Examine the result of '#require(throws:)' instead.") @discardableResult @freestanding(expression) public macro require( _ comment: @autoclosure () -> Comment? = nil, diff --git a/Sources/Testing/Testing.docc/AvailabilityStubs/ExpectComplexThrows.md b/Sources/Testing/Testing.docc/AvailabilityStubs/ExpectComplexThrows.md index 755bf5089..3114002d2 100644 --- a/Sources/Testing/Testing.docc/AvailabilityStubs/ExpectComplexThrows.md +++ b/Sources/Testing/Testing.docc/AvailabilityStubs/ExpectComplexThrows.md @@ -11,11 +11,11 @@ See https://swift.org/CONTRIBUTORS.txt for Swift project authors --> @Metadata { - @Available(Swift, introduced: 6.0, deprecated: 999.0) - @Available(Xcode, introduced: 16.0, deprecated: 999.0) + @Available(Swift, introduced: 6.0) + @Available(Xcode, introduced: 16.0) } -@DeprecationSummary { +@DeprecationSummary { Examine the result of ``expect(throws:_:sourceLocation:performing:)-7du1h`` or ``expect(throws:_:sourceLocation:performing:)-1hfms`` instead: diff --git a/Sources/Testing/Testing.docc/AvailabilityStubs/RequireComplexThrows.md b/Sources/Testing/Testing.docc/AvailabilityStubs/RequireComplexThrows.md index ff42dc40f..291ac0d32 100644 --- a/Sources/Testing/Testing.docc/AvailabilityStubs/RequireComplexThrows.md +++ b/Sources/Testing/Testing.docc/AvailabilityStubs/RequireComplexThrows.md @@ -11,11 +11,11 @@ See https://swift.org/CONTRIBUTORS.txt for Swift project authors --> @Metadata { - @Available(Swift, introduced: 6.0, deprecated: 999.0) - @Available(Xcode, introduced: 16.0, deprecated: 999.0) + @Available(Swift, introduced: 6.0) + @Available(Xcode, introduced: 16.0) } -@DeprecationSummary { +@DeprecationSummary { Examine the result of ``require(throws:_:sourceLocation:performing:)-7n34r`` or ``require(throws:_:sourceLocation:performing:)-4djuw`` instead: diff --git a/Sources/Testing/Testing.docc/testing-for-errors-in-swift-code.md b/Sources/Testing/Testing.docc/testing-for-errors-in-swift-code.md index 2611f8835..7053d0fa5 100644 --- a/Sources/Testing/Testing.docc/testing-for-errors-in-swift-code.md +++ b/Sources/Testing/Testing.docc/testing-for-errors-in-swift-code.md @@ -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:)-1xr34`` or -``require(_:_:sourceLocation:)-5l63q``: +``expect(throws:_:sourceLocation:performing:)-1hfms`` or +``require(throws:_:sourceLocation:performing:)-7n34r``: ```swift @Test func cannotAddToppingToPizzaBeforeStartOfList() { diff --git a/Tests/TestingTests/IssueTests.swift b/Tests/TestingTests/IssueTests.swift index a73f0706d..4a4fda631 100644 --- a/Tests/TestingTests/IssueTests.swift +++ b/Tests/TestingTests/IssueTests.swift @@ -491,7 +491,6 @@ final class IssueTests: XCTestCase { }.run(configuration: .init()) } - @available(*, deprecated) func testErrorCheckingWithExpect() async throws { let expectationFailed = expectation(description: "Expectation failed") expectationFailed.isInverted = true @@ -540,7 +539,6 @@ final class IssueTests: XCTestCase { await fulfillment(of: [expectationFailed], timeout: 0.0) } - @available(*, deprecated) func testErrorCheckingWithExpect_Mismatching() async throws { let expectationFailed = expectation(description: "Expectation failed") expectationFailed.expectedFulfillmentCount = 13 @@ -665,7 +663,6 @@ final class IssueTests: XCTestCase { await fulfillment(of: [expectationFailed], timeout: 0.0) } - @available(*, deprecated) func testErrorCheckingWithExpectAsync() async throws { let expectationFailed = expectation(description: "Expectation failed") expectationFailed.isInverted = true @@ -709,7 +706,6 @@ final class IssueTests: XCTestCase { await fulfillment(of: [expectationFailed], timeout: 0.0) } - @available(*, deprecated) func testErrorCheckingWithExpectAsync_Mismatching() async throws { let expectationFailed = expectation(description: "Expectation failed") expectationFailed.expectedFulfillmentCount = 13 @@ -826,7 +822,6 @@ final class IssueTests: XCTestCase { await fulfillment(of: [expectationFailed], timeout: 0.0) } - @available(*, deprecated) func testErrorCheckingWithExpect_ThrowingFromErrorMatcher() async throws { let errorCaught = expectation(description: "Error matcher's error caught") let expectationFailed = expectation(description: "Expectation failed") @@ -854,7 +849,6 @@ final class IssueTests: XCTestCase { await fulfillment(of: [errorCaught, expectationFailed], timeout: 0.0) } - @available(*, deprecated) func testErrorCheckingWithExpectAsync_ThrowingFromErrorMatcher() async throws { let errorCaught = expectation(description: "Error matcher's error caught") let expectationFailed = expectation(description: "Expectation failed") @@ -882,7 +876,6 @@ final class IssueTests: XCTestCase { await fulfillment(of: [errorCaught, expectationFailed], timeout: 0.0) } - @available(*, deprecated) func testErrorCheckingWithRequire_ThrowingFromErrorMatcher() async throws { let errorCaught = expectation(description: "Error matcher's error caught") let expectationFailed = expectation(description: "Expectation failed") @@ -911,7 +904,6 @@ final class IssueTests: XCTestCase { await fulfillment(of: [errorCaught, expectationFailed], timeout: 0.0) } - @available(*, deprecated) func testErrorCheckingWithRequireAsync_ThrowingFromErrorMatcher() async throws { let errorCaught = expectation(description: "Error matcher's error caught") let expectationFailed = expectation(description: "Expectation failed")