From d9fbe509582b71282d5f541f991a73868df4c184 Mon Sep 17 00:00:00 2001 From: Jonathan Grynspan Date: Wed, 29 Oct 2025 17:11:39 -0400 Subject: [PATCH 1/2] Enable `Test.cancel()` as API. Pending approval of [ST-0016](https://github.com/swiftlang/swift-evolution/blob/main/proposals/testing/0016-test-cancellation.md). --- Sources/Testing/Test+Cancellation.swift | 4 ++-- .../Testing/Testing.docc/EnablingAndDisabling.md | 15 +++++++-------- .../Testing/Testing.docc/MigratingFromXCTest.md | 9 +-------- 3 files changed, 10 insertions(+), 18 deletions(-) diff --git a/Sources/Testing/Test+Cancellation.swift b/Sources/Testing/Test+Cancellation.swift index 5a4b425c7..e09ebc8d9 100644 --- a/Sources/Testing/Test+Cancellation.swift +++ b/Sources/Testing/Test+Cancellation.swift @@ -169,7 +169,8 @@ extension Test: TestCancellable { /// attribute the cancellation. /// /// - Throws: An error indicating that the current test or test case has been - /// cancelled. + /// cancelled. The testing library does not treat this error as a test + /// failure. /// /// The testing library runs each test and each test case in its own task. /// When you call this function, the testing library cancels the task @@ -206,7 +207,6 @@ extension Test: TestCancellable { /// - Important: If the current task is not associated with a test (for /// example, because it was created with [`Task.detached(name:priority:operation:)`](https://developer.apple.com/documentation/swift/task/detached(name:priority:operation:)-795w1)) /// this function records an issue and cancels the current task. - @_spi(Experimental) public static func cancel(_ comment: Comment? = nil, sourceLocation: SourceLocation = #_sourceLocation) throws -> Never { let skipInfo = SkipInfo(comment: comment, sourceContext: SourceContext(backtrace: nil, sourceLocation: sourceLocation)) try Self.cancel(with: skipInfo) diff --git a/Sources/Testing/Testing.docc/EnablingAndDisabling.md b/Sources/Testing/Testing.docc/EnablingAndDisabling.md index 7e3f31bde..4508e2dd0 100644 --- a/Sources/Testing/Testing.docc/EnablingAndDisabling.md +++ b/Sources/Testing/Testing.docc/EnablingAndDisabling.md @@ -121,19 +121,18 @@ func allIngredientsAvailable(for food: Food) -> Bool { ... } func makeSundae() async throws { ... } ``` - diff --git a/Sources/Testing/Testing.docc/MigratingFromXCTest.md b/Sources/Testing/Testing.docc/MigratingFromXCTest.md index 6b1d9f381..3753d7456 100644 --- a/Sources/Testing/Testing.docc/MigratingFromXCTest.md +++ b/Sources/Testing/Testing.docc/MigratingFromXCTest.md @@ -556,11 +556,8 @@ test function with an instance of this trait type to control whether it runs: } } - - ### Annotate known issues A test may have a known issue that sometimes or always prevents it from passing. From 660e522e6b5df4c018e1fb47f6951a195adbb846 Mon Sep 17 00:00:00 2001 From: Jonathan Grynspan Date: Fri, 31 Oct 2025 17:38:37 -0400 Subject: [PATCH 2/2] Adjust docs text --- Sources/Testing/Testing.docc/EnablingAndDisabling.md | 5 ++--- Sources/Testing/Testing.docc/MigratingFromXCTest.md | 7 +++---- 2 files changed, 5 insertions(+), 7 deletions(-) diff --git a/Sources/Testing/Testing.docc/EnablingAndDisabling.md b/Sources/Testing/Testing.docc/EnablingAndDisabling.md index 4508e2dd0..9957dac68 100644 --- a/Sources/Testing/Testing.docc/EnablingAndDisabling.md +++ b/Sources/Testing/Testing.docc/EnablingAndDisabling.md @@ -123,9 +123,8 @@ func makeSundae() async throws { ... } ### End a test after it has already started -If a test has already started running and you determine it cannot complete and -should end early without failing, use ``Test/cancel(_:sourceLocation:)`` to -cancel the test: +If a test is running and you determine it cannot complete and should end early +without failing, use ``Test/cancel(_:sourceLocation:)`` to cancel the test: ```swift @Test("Can make sundaes") diff --git a/Sources/Testing/Testing.docc/MigratingFromXCTest.md b/Sources/Testing/Testing.docc/MigratingFromXCTest.md index 3753d7456..9f104d626 100644 --- a/Sources/Testing/Testing.docc/MigratingFromXCTest.md +++ b/Sources/Testing/Testing.docc/MigratingFromXCTest.md @@ -556,10 +556,9 @@ test function with an instance of this trait type to control whether it runs: } } -If a test has already started running and you determine it cannot complete and -should end early without failing, use ``Test/cancel(_:sourceLocation:)`` instead -of [`XCTSkip`](https://developer.apple.com/documentation/xctest/xctskip) to -cancel the task associated with the current test: +If a test is running and you determine it cannot complete and should end early +without failing, use ``Test/cancel(_:sourceLocation:)`` instead of [`XCTSkip`](https://developer.apple.com/documentation/xctest/xctskip) +to cancel the task associated with the current test: @Row { @Column {