Extend existing Snapshot types and introduce new ones for Event.Context (#321)

This PR extends some of the existing Snapshot types (mostly introduces
new computed properties from their "original" types) and introduces a
new one for `Event.Context`

### Motivation:

Components outside the test process itself sometimes need access to (a
serialized form) of the event context (ie. the test and test case
information).

### Modifications:

I added a new Snapshot type for `Event.Context`, extended various other
existing snapshot types to have more properties (to be more in line with
their "original" types), and changed the initializers of existing
Snapshot types to `borrow` their argument (where possible).

### Result:

`Event.Context` has a serializable variant, and snapshot types are
generally a bit more similar to the types they represent.

### Checklist:

- [x] Code and documentation should follow the style of the [Style
Guide](https://github.com/apple/swift-testing/blob/main/Documentation/StyleGuide.md).
- [ ] If public symbols are renamed or modified, DocC references should
be updated.

Author: dennisweissmann

Sources/Testing/Events/Event.swift

@@ -278,6 +278,7 @@ extension Event {
 
 extension Event {
   /// A serializable event that occurred during testing.
+  @_spi(ForToolsIntegrationOnly)
   public struct Snapshot: Sendable, Codable {
 
     /// The kind of event.
@@ -447,3 +448,36 @@ extension Event.Kind {
     }
   }
 }
+
+extension Event.Context {
+
+  /// A serializable type which provides context about a posted ``Event``.
+  ///
+  @_spi(ForToolsIntegrationOnly)
+  public struct Snapshot: Sendable, Codable {
+    /// A snapshot of the test for which this instance's associated ``Event``
+    /// occurred, if any.
+    ///
+    /// If an event occurred independently of any test, or if the running test
+    /// cannot be determined, the value of this property is `nil`.
+    public var test: Test.Snapshot?
+
+    /// A snapshot of the test case for which this instance's associated
+    /// ``Event`` occurred, if any.
+    ///
+    /// The test case indicates which element in the iterated sequence is
+    /// associated with this event. For non-parameterized tests, a single test
+    /// case is synthesized. For test suite types (as opposed to test
+    /// functions), the value of this property is `nil`.
+    public var testCase: Test.Case.Snapshot?
+
+    /// Initialize a new instance of this type.
+    ///
+    /// - Parameters:
+    ///   - context: The context to snapshot.
+    public init(snapshotting context: borrowing Event.Context) {
+      test = context.test.map { Test.Snapshot(snapshotting: $0) }
+      testCase = context.testCase.map { Test.Case.Snapshot(snapshotting: $0) }
+    }
+  }
+}

Sources/Testing/Expectations/Expectation.swift

@@ -91,7 +91,7 @@ extension Expectation {
 
     /// Creates a snapshot expectation from a real ``Expectation``.
     /// - Parameter expectation: The real expectation.
-    public init(snapshotting expectation: Expectation) {
+    public init(snapshotting expectation: borrowing Expectation) {
       self.evaluatedExpression = expectation.evaluatedExpression
       self.mismatchedErrorDescription = expectation.mismatchedErrorDescription
       self.differenceDescription = expectation.differenceDescription

Sources/Testing/Issues/Issue.swift

@@ -200,7 +200,7 @@ extension Issue {
     /// Initialize an issue instance with the specified details.
     ///
     /// - Parameter issue: The original issue that gets snapshotted.
-    public init(snapshotting issue: Issue) {
+    public init(snapshotting issue: borrowing Issue) {
       self.kind = Issue.Kind.Snapshot(snapshotting: issue.kind)
       self.comments = issue.comments
       self.sourceContext = issue.sourceContext
@@ -217,6 +217,16 @@ extension Issue {
       }
       return nil
     }
+
+    /// The location in source where this issue occurred, if available.
+    public var sourceLocation: SourceLocation? {
+      get {
+        sourceContext.sourceLocation
+      }
+      set {
+        sourceContext.sourceLocation = newValue
+      }
+    }
   }
 }
 

Sources/Testing/Parameterization/Test.Case.swift

@@ -172,12 +172,17 @@ extension Test.Case {
     /// The arguments passed to this test case.
     public var arguments: [Argument.Snapshot]
 
+    /// Whether or not this test case is from a parameterized test.
+    public var isParameterized: Bool {
+      !arguments.isEmpty
+    }
+
     /// Initialize an instance of this type by snapshotting the specified test
     /// case.
     ///
     /// - Parameters:
     ///   - testCase: The original test case to snapshot.
-    init(snapshotting testCase: Test.Case) {
+    public init(snapshotting testCase: borrowing Test.Case) {
       id = testCase.id
       arguments = testCase.arguments.map(Test.Case.Argument.Snapshot.init)
     }
@@ -204,7 +209,7 @@ extension Test.Case.Argument {
     ///
     /// - Parameters:
     ///   - argument: The original test case argument to snapshot.
-    init(snapshotting argument: Test.Case.Argument) {
+    public init(snapshotting argument: Test.Case.Argument) {
       id = argument.id
       value = Expression.Value(reflecting: argument.value)
       parameter = argument.parameter

Sources/Testing/Running/EntryPoint.swift

@@ -282,11 +282,8 @@ struct EventAndContextSnapshot {
   /// A snapshot of the event.
   var event: Event.Snapshot
 
-  /// A snapshot of the test associated with the event, if any.
-  var test: Test.Snapshot?
-
-  /// A snapshot of the test case associated with the event, if any.
-  var testCase: Test.Case.Snapshot?
+  /// A snapshot of the event context.
+  var eventContext: Event.Context.Snapshot
 }
 
 extension EventAndContextSnapshot: Codable {}
@@ -323,8 +320,7 @@ private func _eventHandlerForStreamingEvents(toFileAtPath path: String) throws -
   return { event, context in
     let snapshot = EventAndContextSnapshot(
       event: Event.Snapshot(snapshotting: event),
-      test: context.test.map { Test.Snapshot(snapshotting: $0) },
-      testCase: context.testCase.map { Test.Case.Snapshot(snapshotting: $0) }
+      eventContext: Event.Context.Snapshot(snapshotting: context)
     )
     if var snapshotJSON = try? JSONEncoder().encode(snapshot) {
       func isASCIINewline(_ byte: UInt8) -> Bool {

Sources/Testing/Running/Runner.Plan.swift

@@ -329,7 +329,7 @@ extension Runner.Plan {
     ///
     /// - Parameters:
     ///   - plan: The original plan to snapshot.
-    public init(snapshotting plan: Runner.Plan) {
+    public init(snapshotting plan: borrowing Runner.Plan) {
       plan.stepGraph.forEach { keyPath, step in
         let step = step.map(Step.Snapshot.init(snapshotting:))
         _stepGraph.insertValue(step, at: keyPath)
@@ -394,7 +394,7 @@ extension Runner.Plan.Step {
     ///
     /// - Parameters:
     ///   - step: The original step to snapshot.
-    init(snapshotting step: Runner.Plan.Step) {
+    public init(snapshotting step: borrowing Runner.Plan.Step) {
       test = Test.Snapshot(snapshotting: step.test)
       action = Runner.Plan.Action.Snapshot(snapshotting: step.action)
     }
@@ -431,7 +431,7 @@ extension Runner.Plan.Action {
     ///
     /// - Parameters:
     ///   - action: The original action to snapshot.
-    init(snapshotting action: Runner.Plan.Action) {
+    public init(snapshotting action: Runner.Plan.Action) {
       self = switch action {
       case let .run(options):
         .run(options: options)

Sources/Testing/Test.swift

@@ -177,6 +177,20 @@ extension Test {
   /// A serializable snapshot of a ``Test`` instance.
   @_spi(ForToolsIntegrationOnly)
   public struct Snapshot: Sendable, Codable, Identifiable {
+
+    private enum CodingKeys: String, CodingKey {
+      case id
+      case name
+      case displayName
+      case sourceLocation
+      case testCases
+      case parameters
+      case comments
+      case tags
+      case associatedBugs
+      case _timeLimit = "timeLimit"
+    }
+
     /// The ID of this test.
     public var id: Test.ID
 
@@ -190,8 +204,6 @@ extension Test {
     /// The customized display name of this test, if any.
     public var displayName: String?
 
-    // FIXME: Include traits as well.
-
     /// The source location of this test.
     public var sourceLocation: SourceLocation
 
@@ -210,17 +222,44 @@ extension Test {
     /// - ``Test/parameters``
     public var parameters: [Parameter]?
 
+    /// The complete set of comments about this test from all of its traits.
+    public var comments: [Comment]
+
+    /// The complete, unique set of tags associated with this test.
+    public var tags: Set<Tag>
+
+    /// The set of bugs associated with this test.
+    ///
+    /// For information on how to associate a bug with a test, see the
+    /// documentation for ``Bug``.
+    public var associatedBugs: [Bug]
+
+    // Backing storage for ``Test/Snapshot/timeLimit``.
+    private var _timeLimit: TimeValue?
+
+    /// The maximum amount of time a test may run for before timing out.
+    @available(_clockAPI, *)
+    public var timeLimit: Duration? {
+      _timeLimit.map(Duration.init)
+    }
+
     /// Initialize an instance of this type by snapshotting the specified test.
     ///
     /// - Parameters:
     ///   - test: The original test to snapshot.
-    public init(snapshotting test: Test) {
+    public init(snapshotting test: borrowing Test) {
       id = test.id
       name = test.name
       displayName = test.displayName
       sourceLocation = test.sourceLocation
       testCases = test.testCases?.map(Test.Case.Snapshot.init)
       parameters = test.parameters
+      comments = test.comments
+      tags = test.tags
+      associatedBugs = test.associatedBugs
+      if #available(_clockAPI, *) {
+        _timeLimit = test.timeLimit.map(TimeValue.init)
+      }
     }
 
     /// Whether or not this test is parameterized.

Tests/TestingTests/EventTests.swift

@@ -67,5 +67,17 @@ struct EventTests {
 
     #expect(String(describing: decoded) == String(describing: eventSnapshot))
   }
+
+  @Test("Event.Contexts's Codable Conformances")
+  func codable() async throws {
+    let eventContext = Event.Context()
+    let snapshot = Event.Context.Snapshot(snapshotting: eventContext)
+
+    let encoded = try JSONEncoder().encode(snapshot)
+    let decoded = try JSONDecoder().decode(Event.Context.Snapshot.self, from: encoded)
+
+    #expect(String(describing: decoded.test) == String(describing: eventContext.test.map(Test.Snapshot.init(snapshotting:))))
+    #expect(String(describing: decoded.testCase) == String(describing: eventContext.testCase.map(Test.Case.Snapshot.init(snapshotting:))))
+  }
 #endif
 }

Tests/TestingTests/IssueTests.swift

@@ -1422,4 +1422,63 @@ struct IssueCodingTests {
     let errorSnapshot = try #require(issueSnapshot.error)
     #expect(String(describing: errorSnapshot) == String(describing: underlyingError))
   }
+
+  @Test func sourceLocationPropertyGetter() throws {
+    let sourceLocation = SourceLocation(
+      fileID: "fileID",
+      filePath: "filePath",
+      line: 13,
+      column: 42
+    )
+
+    let sourceContext = SourceContext(
+      backtrace: Backtrace(addresses: [13, 42]),
+      sourceLocation: sourceLocation
+    )
+
+    let issue = Issue(
+      kind: .apiMisused,
+      comments: [],
+      sourceContext: sourceContext
+    )
+
+    let issueSnapshot = Issue.Snapshot(snapshotting: issue)
+    #expect(issueSnapshot.sourceContext == sourceContext)
+    #expect(issueSnapshot.sourceLocation == sourceLocation)
+  }
+
+  @Test func sourceLocationPropertySetter() throws {
+    let initialSourceLocation = SourceLocation(
+      fileID: "fileID",
+      filePath: "filePath",
+      line: 13,
+      column: 42
+    )
+
+    let sourceContext = SourceContext(
+      backtrace: Backtrace(addresses: [13, 42]),
+      sourceLocation: initialSourceLocation
+    )
+
+    let issue = Issue(
+      kind: .apiMisused,
+      comments: [],
+      sourceContext: sourceContext
+    )
+
+    let updatedSourceLocation = SourceLocation(
+      fileID: "fileID2",
+      filePath: "filePath2",
+      line: 14,
+      column: 43
+    )
+
+    var issueSnapshot = Issue.Snapshot(snapshotting: issue)
+    issueSnapshot.sourceLocation = updatedSourceLocation
+
+    #expect(issueSnapshot.sourceContext != sourceContext)
+    #expect(issueSnapshot.sourceLocation != initialSourceLocation)
+    #expect(issueSnapshot.sourceLocation == updatedSourceLocation)
+    #expect(issueSnapshot.sourceContext.sourceLocation == updatedSourceLocation)
+  }
 }

Tests/TestingTests/Test.SnapshotTests.swift

@@ -69,4 +69,52 @@ struct Test_SnapshotTests {
       #expect(snapshot.isSuite)
     }
   }
+
+  /// This is a comment that should show up in the test's `comments` property.
+  @Test("comments property")
+  func comments() async throws {
+    let test = try #require(Test.current)
+    let snapshot = Test.Snapshot(snapshotting: test)
+
+    #expect(!snapshot.comments.isEmpty)
+    #expect(snapshot.comments == test.comments)
+  }
+
+  @Test("tags property", .tags(Tag.testTag))
+  func tags() async throws {
+    let test = try #require(Test.current)
+    let snapshot = Test.Snapshot(snapshotting: test)
+
+    #expect(snapshot.tags.count == 1)
+    #expect(snapshot.tags.first == Tag.testTag)
+  }
+
+  @Test("associatedBugs property", bug)
+  func associatedBugs() async throws {
+    let test = try #require(Test.current)
+    let snapshot = Test.Snapshot(snapshotting: test)
+
+    #expect(snapshot.associatedBugs.count == 1)
+    #expect(snapshot.associatedBugs.first == Self.bug)
+  }
+
+  private static let bug: Bug = Bug.bug(12345, relationship: .failingBecauseOfBug, "Lorem ipsum")
+
+  @available(_clockAPI, *)
+  @Test("timeLimit property", .timeLimit(duration))
+  func timeLimit() async throws {
+    let test = try #require(Test.current)
+    let snapshot = Test.Snapshot(snapshotting: test)
+
+    #expect(snapshot.timeLimit == Self.duration)
+  }
+
+  @available(_clockAPI, *)
+  private static var duration: Duration {
+    .seconds(999_999_999)
+  }
+}
+
+extension Tag {
+  @Tag fileprivate static let testTag: Self
 }