Merge branch 'main' into main-6.3-merge

Author: stmontgomery

README.md

@@ -106,14 +106,23 @@ Swift.
 The table below describes the current level of support that Swift Testing has
 for various platforms:
 
-| **Platform** | **Support Status** |
-|-|-|
-| Apple platforms | Supported |
-| Linux | Supported |
-| Windows | Supported |
-| FreeBSD, OpenBSD | Experimental |
-| Wasm | Experimental |
-| Android | Experimental |
+| **Platform**     | **Support Status** | **Qualification[^1]**  |
+| ---------------- | ------------------ | ---------------------- |
+| Apple platforms  | Supported          | Automated              |
+| Linux            | Supported          | Automated              |
+| Windows          | Supported          | Automated              |
+| Wasm             | Experimental       | Automated (Build Only) |
+| Android          | Experimental       | Automated (Build Only) |
+| FreeBSD, OpenBSD | Experimental       | Manual                 |
+
+[^1]:
+    Most platforms have "Automated" qualification, where continuous integration
+    automatically verifies that the project builds and passes all tests. This
+    ensures that any changes meet our highest quality standards, so it is our
+    goal for all supported platforms.
+
+    Presently, some platforms rely on manual test ("Automated (Build Only)"
+    qualification) or manual build and test ("Manual" qualification).
 
 ### Works with XCTest
 
@@ -127,7 +136,7 @@ Detailed documentation for Swift Testing can be found on the
 [Swift Package Index](https://swiftpackageindex.com/swiftlang/swift-testing/main/documentation/testing).
 There, you can delve into comprehensive guides, tutorials, and API references to
 make the most out of this package. Swift Testing is included with the Swift 6
-toolchain and Xcode 16.  You do not need to add it as a package dependency to
+toolchain and Xcode 16. You do not need to add it as a package dependency to
 your Swift package or Xcode project.
 
 > [!IMPORTANT]
@@ -136,5 +145,5 @@ your Swift package or Xcode project.
 > repository requires a recent **main-branch development snapshot** toolchain.
 
 Other documentation resources for this project can be found in the
-[README](https://github.com/swiftlang/swift-testing/blob/main/Documentation/README.md) 
+[README](https://github.com/swiftlang/swift-testing/blob/main/Documentation/README.md)
 of the `Documentation/` subdirectory.

Sources/Testing/Test+Cancellation.swift

@@ -195,7 +195,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
@@ -222,17 +223,13 @@ extension Test: TestCancellable {
   /// current test has been cancelled, but does not attempt to cancel the test a
   /// second time.
   ///
-  /// @Comment {
-  ///   TODO: Document the interaction between an exit test and test
-  ///   cancellation. In particular, the error thrown by this function isn't
-  ///   thrown into the parent process and task cancellation doesn't propagate
-  ///   (because the exit test _de facto_ runs in a detached task.)
-  /// }
-  ///
   /// - 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)
+  ///
+  /// @Metadata {
+  ///   @Available(Swift, introduced: 6.3)
+  /// }
   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)

Sources/Testing/Testing.docc/EnablingAndDisabling.md

@@ -121,19 +121,17 @@ func allIngredientsAvailable(for food: Food) -> Bool { ... }
 func makeSundae() async throws { ... }
 ```
 
-<!--
 ### End a test after it has already started
 
-TODO: document Test.cancel() and Test.Case.cancel() here
-
-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")
+func makeSundae() throws {
+  guard let iceCreamMaker = IceCreamMaker() else {
+    try Test.cancel("The ice cream maker isn't working right now")
+  }
+  ...
+}
 ```
-
-If the test is parameterized and you only want to cancel the current test case
-rather than the entire test, use ``Test/Case/cancel(_:sourceLocation:)``.
--->

Sources/Testing/Testing.docc/MigratingFromXCTest.md

@@ -556,13 +556,9 @@ test function with an instance of this trait type to control whether it runs:
   }
 }
 
-<!-- TODO: document Test.cancel() and Test.Case.cancel() here, and update
-     relevant links to use proper DocC symbol references.
-
-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 {
@@ -593,10 +589,6 @@ cancel the task associated with the current test:
   }
 }
 
-If the test is parameterized and you only want to cancel the current test case
-rather than the entire test, use `Test/Case/cancel(_:sourceLocation:)`.
--->
-
 ### Annotate known issues
 
 A test may have a known issue that sometimes or always prevents it from passing.