Skip to content

Expose ABI.Version as tools SPI.#1587

Merged
grynspan merged 5 commits intomainfrom
jgrynspan/abi-version-as-spi
Feb 25, 2026
Merged

Expose ABI.Version as tools SPI.#1587
grynspan merged 5 commits intomainfrom
jgrynspan/abi-version-as-spi

Conversation

@grynspan
Copy link
Contributor

@grynspan grynspan commented Feb 24, 2026

This PR exposes the internal ABI.Version protocol as tools SPI. It includes ABI.VersionNumber (which represents a Swift toolchain version in this context) as well as the basic interfaces of ABI.Record, ABI.EncodedTest, and ABI.EncodedEvent (but not individual fields thereof; we need to audit those individually for usability/stability).

A tool can now use the exposed interfaces to handle an event stream that produces JSON records rather than instances of Event:

func handle<V: ABI.Version>(_ recordJSON: UnsafeRawBufferPointer, using _: V.Type) throws {
  let record = try JSONDecoder().decode(ABI.Record<V>.self, from: Data(recordJSON))
  switch record.kind {
  case let .test(test):
    // Test discovered!
  case let .event(event):
    // Event to handle!
  }
}

In practice, the caller probably already knows the version number here, but just in case, here's how you get it dynamically:

func handle(_ recordJSON: UnsafeRawBufferPointer) throws {
  let versionNumber = try ABI.VersionNumber(fromRecordJSON: recordJSON)
  guard let abi = ABI.version(fromVersionNumber: versionNumber) else {
    throw ...
  }
  try handle(recordJSON, using: abi)
}

There's also ABI.Version.eventHandler(forwardingTo:) that automatically handles the conversion from Event to ABI.Record for tools that want a single code path to handle a built-in copy of Swift Testing and package copies that they don't directly link against.

Checklist:

  • Code and documentation should follow the style of the Style Guide.
  • If public symbols are renamed or modified, DocC references should be updated.

This PR exposes the internal `ABI.Version` protocol as tools SPI. It includes
`ABI.VersionNumber` (which represents a Swift toolchain version in this context)
as well as the basic interfaces of `ABI.Record`, `ABI.EncodedTest`, and
`ABI.EncodedEvent` (but not individual fields thereof; we need to audit those
individually for usability/stability).

A tool can now use the exposed interfaces to handle an event stream that
produces JSON records rather than instances of `Event`:

```swift
func open<V: ABI.Version> handle(_ recordJSON: UnsafeRawBufferPointer, using _: V.Type) throws {
  let record = try JSONDecoder().decode(ABI.Record<V>.self, from: Data(recordJSON))
  switch record.kind {
  case let .test(test):
    // Test discovered!
  case let .event(event):
    // Event to handle!
  }
}
```

In practice, the caller probably already knows the version number here, but just
in case, here's how you get it dynamically:

```swift
func handle(_ recordJSON: UnsafeRawBufferPointer) throws {
  let versionNumber = try ABI.VersionNumber(fromRecordJSON: recordJSON)
  guard let abi = ABI.version(fromVersionNumber: versionNumber) else {
    throw ...
  }
  try handle(recordJSON, using: abi)
}
```

There's also `ABI.Version.eventHandler(forwardingTo:)` that automatically handles
the conversion from `Event` to `ABI.Record` for tools that want a single code
path to handle a built-in copy of Swift Testing and package copies that they
don't directly link against.
@grynspan grynspan added this to the Swift 6.4.0 (main) milestone Feb 24, 2026
@grynspan grynspan self-assigned this Feb 24, 2026
@grynspan grynspan added enhancement New feature or request tools integration 🛠️ Integration of swift-testing into tools/IDEs tech-debt 💾 reduces technical debt labels Feb 24, 2026
Copy link
Contributor

@harlanhaskins harlanhaskins left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is an excellent first step, and very thorough.

…ation on code paths that don't end up using JSON
grynspan added a commit that referenced this pull request Feb 24, 2026
Follow-up to #1587.

Exposes `ABI.EncodedInstant` as SPI along with some conversion helpers to get
a Foundation `Date` or suspending clock instant from an instance thereof. A
value of this type is associated with each event in the event stream.
grynspan added a commit that referenced this pull request Feb 25, 2026
Follow-up to #1587.

Exposes `ABI.EncodedSourceLocation` as SPI along with some conversion helpers to
go to/from a `SourceLocation` instance. A value of this type is associated with
many events in the event stream.
@grynspan grynspan added the interoperability ↔️ Work related to Swift Testing and XCTest interoperability label Feb 25, 2026
…serialization on code paths that don't end up using JSON"

This reverts commit 6949686.
grynspan added a commit that referenced this pull request Feb 25, 2026
Follow-up to #1587.

Exposes `ABI.EncodedAttachment` as SPI. A value of this type is associated with
the `valueAttached` event kind. The type already conforms to `Attachable` so it
can be directly plumbed back into Swift Testing, and XCTest internally knows how
to convert an `Attachable` value to an `XCTAttachment`.
grynspan added a commit that referenced this pull request Feb 25, 2026
Follow-up to #1587.

Exposes `ABI.EncodedAttachment` as SPI. A value of this type is associated with
the `valueAttached` event kind. The type already conforms to `Attachable` so it
can be directly plumbed back into Swift Testing, and XCTest internally knows how
to convert an `Attachable` value to an `XCTAttachment`.
@grynspan grynspan merged commit ed1972c into main Feb 25, 2026
51 of 52 checks passed
@grynspan grynspan deleted the jgrynspan/abi-version-as-spi branch February 25, 2026 19:33
grynspan added a commit that referenced this pull request Feb 25, 2026
Follow-up to #1587.

Exposes `ABI.EncodedSourceLocation` as SPI along with some conversion helpers to
go to/from a `SourceLocation` instance. A value of this type is associated with
many events in the event stream.
grynspan added a commit that referenced this pull request Feb 25, 2026
Follow-up to #1587.

Exposes `ABI.EncodedAttachment` as SPI. A value of this type is associated with
the `valueAttached` event kind. The type already conforms to `Attachable` so it
can be directly plumbed back into Swift Testing, and XCTest internally knows how
to convert an `Attachable` value to an `XCTAttachment`.
grynspan added a commit that referenced this pull request Feb 25, 2026
Follow-up to #1587.

Exposes `ABI.EncodedInstant` as SPI along with some conversion helpers to get
a Foundation `Date` or suspending clock instant from an instance thereof. A
value of this type is associated with each event in the event stream.
grynspan added a commit that referenced this pull request Feb 25, 2026
Follow-up to #1587.

Exposes `ABI.EncodedAttachment` as SPI. A value of this type is associated with
the `valueAttached` event kind. The type already conforms to `Attachable` so it
can be directly plumbed back into Swift Testing, and XCTest internally knows how
to convert an `Attachable` value to an `XCTAttachment`.
grynspan added a commit that referenced this pull request Mar 5, 2026
Follow-up to #1587.

Exposes `ABI.EncodedSourceLocation` as SPI along with some conversion
helpers to go to/from a `SourceLocation` instance. A value of this type
is associated with many events in the event stream.

### Checklist:

- [x] Code and documentation should follow the style of the [Style
Guide](https://github.com/apple/swift-testing/blob/main/Documentation/StyleGuide.md).
- [x] If public symbols are renamed or modified, DocC references should
be updated.
grynspan added a commit that referenced this pull request Mar 5, 2026
Follow-up to #1587.

Exposes `ABI.EncodedInstant` as SPI along with some conversion helpers
to get a Foundation `Date` or suspending clock instant from an instance
thereof. A value of this type is associated with each event in the event
stream.

### Checklist:

- [x] Code and documentation should follow the style of the [Style
Guide](https://github.com/apple/swift-testing/blob/main/Documentation/StyleGuide.md).
- [x] If public symbols are renamed or modified, DocC references should
be updated.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request interoperability ↔️ Work related to Swift Testing and XCTest interoperability tech-debt 💾 reduces technical debt tools integration 🛠️ Integration of swift-testing into tools/IDEs

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants