Add experimental SPI to cancel a running test.

Sources/Testing/ABI/Encoded/ABI.EncodedAttachment.swift

@@ -38,12 +38,6 @@ extension ABI {
     /// - Warning: Inline attachment content is not yet part of the JSON schema.
     var _bytes: Bytes?
 
-    /// The source location where this attachment was created.
-    ///
-    /// - Warning: Attachment source locations are not yet part of the JSON
-    ///   schema.
-    var _sourceLocation: SourceLocation?
-
     init(encoding attachment: borrowing Attachment<AnyAttachable>, in eventContext: borrowing Event.Context) {
       path = attachment.fileSystemPath
 
@@ -55,8 +49,6 @@ extension ABI {
             return Bytes(rawValue: [UInt8](bytes))
           }
         }
-
-        _sourceLocation = attachment.sourceLocation
       }
     }
 

Sources/Testing/ABI/Encoded/ABI.EncodedEvent.swift

@@ -29,8 +29,10 @@ extension ABI {
       case issueRecorded
       case valueAttached
       case testCaseEnded
+      case testCaseCancelled = "_testCaseCancelled"
       case testEnded
       case testSkipped
+      case testCancelled = "_testCancelled"
       case runEnded
     }
 
@@ -64,6 +66,38 @@ extension ABI {
     /// - Warning: Test cases are not yet part of the JSON schema.
     var _testCase: EncodedTestCase<V>?
 
+    /// The comments the test author provided for this event, if any.
+    ///
+    /// The value of this property contains the comments related to the primary
+    /// user action that caused this event to be generated.
+    ///
+    /// Some kinds of events have additional associated comments. For example,
+    /// when using ``withKnownIssue(_:isIntermittent:sourceLocation:_:)``, there
+    /// can be separate comments for the "underlying" issue versus the known
+    /// issue matcher, and either can be `nil`. In such cases, the secondary
+    /// comment(s) are represented via a distinct property depending on the kind
+    /// of that event.
+    ///
+    /// - Warning: Comments at this level are not yet part of the JSON schema.
+    var _comments: [String]?
+
+    /// A source location associated with this event, if any.
+    ///
+    /// The value of this property represents the source location most closely
+    /// related to the primary user action that caused this event to be
+    /// generated.
+    ///
+    /// Some kinds of events have additional associated source locations. For
+    /// example, when using ``withKnownIssue(_:isIntermittent:sourceLocation:_:)``,
+    /// there can be separate source locations for the "underlying" issue versus
+    /// the known issue matcher. In such cases, the secondary source location(s)
+    /// are represented via a distinct property depending on the kind of that
+    /// event.
+    ///
+    /// - Warning: Source locations at this level of the JSON schema are not yet
+    ///   part of said JSON schema.
+    var _sourceLocation: SourceLocation?
+
     init?(encoding event: borrowing Event, in eventContext: borrowing Event.Context, messages: borrowing [Event.HumanReadableOutputRecorder.Message]) {
       switch event.kind {
       case .runStarted:
@@ -78,18 +112,31 @@ extension ABI {
       case let .issueRecorded(recordedIssue):
         kind = .issueRecorded
         issue = EncodedIssue(encoding: recordedIssue, in: eventContext)
+        _comments = recordedIssue.comments.map(\.rawValue)
+        _sourceLocation = recordedIssue.sourceLocation
       case let .valueAttached(attachment):
         kind = .valueAttached
         self.attachment = EncodedAttachment(encoding: attachment, in: eventContext)
+        _sourceLocation = attachment.sourceLocation
       case .testCaseEnded:
         if eventContext.test?.isParameterized == false {
           return nil
         }
         kind = .testCaseEnded
+      case let .testCaseCancelled(skipInfo):
+        kind = .testCaseCancelled
+        _comments = Array(skipInfo.comment).map(\.rawValue)
+        _sourceLocation = skipInfo.sourceLocation
       case .testEnded:
         kind = .testEnded
-      case .testSkipped:
+      case let .testSkipped(skipInfo):
         kind = .testSkipped
+        _comments = Array(skipInfo.comment).map(\.rawValue)
+        _sourceLocation = skipInfo.sourceLocation
+      case let .testCancelled(skipInfo):
+        kind = .testCancelled
+        _comments = Array(skipInfo.comment).map(\.rawValue)
+        _sourceLocation = skipInfo.sourceLocation
       case .runEnded:
         kind = .runEnded
       default:

Sources/Testing/CMakeLists.txt

@@ -93,6 +93,7 @@ add_library(Testing
   Test.ID.Selection.swift
   Test.ID.swift
   Test.swift
+  Test+Cancellation.swift
   Test+Discovery.swift
   Test+Discovery+Legacy.swift
   Test+Macro.swift

Sources/Testing/Events/Event.swift

@@ -74,6 +74,18 @@ public struct Event: Sendable {
     /// that was passed to the event handler along with this event.
     case testCaseEnded
 
+    /// A test case was cancelled.
+    ///
+    /// - Parameters:
+    ///   - skipInfo: A ``SkipInfo`` with details about the cancelled test case.
+    ///
+    /// This event is generated by a call to ``Test/Case/cancel(_:sourceLocation:)``.
+    ///
+    /// The test case that was cancelled is contained in the ``Event/Context``
+    /// instance that was passed to the event handler along with this event.
+    @_spi(Experimental)
+    indirect case testCaseCancelled(_ skipInfo: SkipInfo)
+
     /// An expectation was checked with `#expect()` or `#require()`.
     ///
     /// - Parameters:
@@ -121,6 +133,18 @@ public struct Event: Sendable {
     /// available from this event's ``Event/testID`` property.
     indirect case testSkipped(_ skipInfo: SkipInfo)
 
+    /// A test was cancelled.
+    ///
+    /// - Parameters:
+    ///   - skipInfo: A ``SkipInfo`` with details about the cancelled test.
+    ///
+    /// This event is generated by a call to ``Test/cancel(_:sourceLocation:)``.
+    ///
+    /// The test that was cancelled is contained in the ``Event/Context``
+    /// instance that was passed to the event handler along with this event.
+    @_spi(Experimental)
+    indirect case testCancelled(_ skipInfo: SkipInfo)
+
     /// A step in the runner plan ended.
     ///
     /// - Parameters:
@@ -395,6 +419,18 @@ extension Event.Kind {
     /// A test case ended.
     case testCaseEnded
 
+    /// A test case was cancelled.
+    ///
+    /// - Parameters:
+    ///   - skipInfo: A ``SkipInfo`` with details about the cancelled test case.
+    ///
+    /// This event is generated by a call to ``Test/Case/cancel(_:sourceLocation:)``.
+    ///
+    /// The test case that was cancelled is contained in the ``Event/Context``
+    /// instance that was passed to the event handler along with this event.
+    @_spi(Experimental)
+    indirect case testCaseCancelled(_ skipInfo: SkipInfo)
+
     /// An expectation was checked with `#expect()` or `#require()`.
     ///
     /// - Parameters:
@@ -431,6 +467,18 @@ extension Event.Kind {
     ///   - skipInfo: A ``SkipInfo`` containing details about this skipped test.
     indirect case testSkipped(_ skipInfo: SkipInfo)
 
+    /// A test was cancelled.
+    ///
+    /// - Parameters:
+    ///   - skipInfo: A ``SkipInfo`` with details about the cancelled test.
+    ///
+    /// This event is generated by a call to ``Test/cancel(_:sourceLocation:)``.
+    ///
+    /// The test that was cancelled is contained in the ``Event/Context``
+    /// instance that was passed to the event handler along with this event.
+    @_spi(Experimental)
+    indirect case testCancelled(_ skipInfo: SkipInfo)
+
     /// A step in the runner plan ended.
     ///
     /// - Parameters:
@@ -479,6 +527,8 @@ extension Event.Kind {
         self = .testCaseStarted
       case .testCaseEnded:
         self = .testCaseEnded
+      case let .testCaseCancelled(skipInfo):
+        self = .testCaseCancelled(skipInfo)
       case let .expectationChecked(expectation):
         let expectationSnapshot = Expectation.Snapshot(snapshotting: expectation)
         self = Snapshot.expectationChecked(expectationSnapshot)
@@ -490,6 +540,8 @@ extension Event.Kind {
         self = .testEnded
       case let .testSkipped(skipInfo):
         self = .testSkipped(skipInfo)
+      case let .testCancelled(skipInfo):
+        self = .testCancelled(skipInfo)
       case .planStepEnded:
         self = .planStepEnded
       case let .iterationEnded(index):

Sources/Testing/Events/Recorder/Event.HumanReadableOutputRecorder.swift

@@ -73,6 +73,9 @@ extension Event {
 
         /// The number of known issues recorded for the test.
         var knownIssueCount = 0
+
+        /// Information about the cancellation of this test or test case.
+        var cancellationInfo: SkipInfo?
       }
 
       /// Data tracked on a per-test basis.
@@ -251,6 +254,7 @@ extension Event.HumanReadableOutputRecorder {
       0
     }
     let test = eventContext.test
+    let testCase = eventContext.testCase
     let keyPath = eventContext.keyPath
     let testName = if let test {
       if let displayName = test.displayName {
@@ -310,6 +314,9 @@ extension Event.HumanReadableOutputRecorder {
       case .testCaseStarted:
         context.testData[keyPath] = .init(startInstant: instant)
 
+      case let .testCancelled(skipInfo), let .testCaseCancelled(skipInfo):
+        context.testData[keyPath]?.cancellationInfo = skipInfo
+
       default:
         // These events do not manipulate the context structure.
         break
@@ -404,21 +411,29 @@ extension Event.HumanReadableOutputRecorder {
       } else {
         ""
       }
-      return if issues.errorIssueCount > 0 {
-        CollectionOfOne(
-          Message(
-            symbol: .fail,
-            stringValue: "\(_capitalizedTitle(for: test)) \(testName)\(testCasesCount) failed after \(duration)\(issues.description)."
-          )
-        ) + _formattedComments(for: test)
+      var cancellationComment = "."
+      let (symbol, verbed): (Event.Symbol, String)
+      if issues.errorIssueCount > 0 {
+        (symbol, verbed) = (.fail, "failed")
+      } else if !test.isParameterized, let cancellationInfo = testData.cancellationInfo {
+        if let comment = cancellationInfo.comment {
+          cancellationComment = ": \"\(comment.rawValue)\""
+        }
+        (symbol, verbed) = (.skip, "was cancelled")
       } else {
-        [
-          Message(
-            symbol: .pass(knownIssueCount: issues.knownIssueCount),
-            stringValue: "\(_capitalizedTitle(for: test)) \(testName)\(testCasesCount) passed after \(duration)\(issues.description)."
-          )
-        ]
+        (symbol, verbed) = (.pass(knownIssueCount: issues.knownIssueCount), "passed")
+      }
+
+      var result = [
+        Message(
+          symbol: symbol,
+          stringValue: "\(_capitalizedTitle(for: test)) \(testName)\(testCasesCount) \(verbed) after \(duration)\(issues.description)\(cancellationComment)"
+        )
+      ]
+      if issues.errorIssueCount > 0 {
+        result += _formattedComments(for: test)
       }
+      return result
 
     case let .testSkipped(skipInfo):
       let test = test!
@@ -443,7 +458,7 @@ extension Event.HumanReadableOutputRecorder {
       } else {
         0
       }
-      let labeledArguments = if let testCase = eventContext.testCase {
+      let labeledArguments = if let testCase {
         testCase.labeledArguments()
       } else {
         ""
@@ -523,7 +538,7 @@ extension Event.HumanReadableOutputRecorder {
       return result
 
     case .testCaseStarted:
-      guard let testCase = eventContext.testCase, testCase.isParameterized, let arguments = testCase.arguments else {
+      guard let testCase, testCase.isParameterized, let arguments = testCase.arguments else {
         break
       }
 
@@ -535,7 +550,7 @@ extension Event.HumanReadableOutputRecorder {
       ]
 
     case .testCaseEnded:
-      guard verbosity > 0, let testCase = eventContext.testCase, testCase.isParameterized, let arguments = testCase.arguments else {
+      guard verbosity > 0, let test, let testCase, testCase.isParameterized, let arguments = testCase.arguments else {
         break
       }
 
@@ -544,18 +559,28 @@ extension Event.HumanReadableOutputRecorder {
       let issues = _issueCounts(in: testDataGraph)
       let duration = testData.startInstant.descriptionOfDuration(to: instant)
 
-      let message = if issues.errorIssueCount > 0 {
-        Message(
-          symbol: .fail,
-          stringValue: "Test case passing \(arguments.count.counting("argument")) \(testCase.labeledArguments(includingQualifiedTypeNames: verbosity > 0)) to \(testName) failed after \(duration)\(issues.description)."
-        )
+      var cancellationComment = "."
+      let (symbol, verbed): (Event.Symbol, String)
+      if issues.errorIssueCount > 0 {
+        (symbol, verbed) = (.fail, "failed")
+      } else if !test.isParameterized, let cancellationInfo = testData.cancellationInfo {
+        if let comment = cancellationInfo.comment {
+          cancellationComment = ": \"\(comment.rawValue)\""
+        }
+        (symbol, verbed) = (.skip, "was cancelled")
       } else {
+        (symbol, verbed) = (.pass(knownIssueCount: issues.knownIssueCount), "passed")
+      }
+      return [
         Message(
-          symbol: .pass(knownIssueCount: issues.knownIssueCount),
-          stringValue: "Test case passing \(arguments.count.counting("argument")) \(testCase.labeledArguments(includingQualifiedTypeNames: verbosity > 0)) to \(testName) passed after \(duration)\(issues.description)."
+          symbol: symbol,
+          stringValue: "Test case passing \(arguments.count.counting("argument")) \(testCase.labeledArguments(includingQualifiedTypeNames: verbosity > 0)) to \(testName) \(verbed) after \(duration)\(issues.description)\(cancellationComment)"
         )
-      }
-      return [message]
+      ]
+
+    case .testCancelled, .testCaseCancelled:
+      // Handled in .testEnded and .testCaseEnded
+      break
 
     case let .iterationEnded(index):
       guard let iterationStartInstant = context.iterationStartInstant else {