ST-0030: Attachments in the Swift Testing JSON event stream [tooling enablement]

Hello Swift Community!

The review of ST-0030: Attachments in the Swift Testing JSON event stream begins now and runs through Sunday November 29, 2026. The proposal is available here: swift-evolution/proposals/testing/0030-attachment-json-enhancements.md at main · swiftlang/swift-evolution · GitHub

The Swift Testing workgroup expects this proposal to be of particular interest to developers of (test) tooling and/or developers that rely on the Swift testing (JSON) event stream. Though all feedback is welcome.

Reviews are an important part of the Swift evolution process. All review feedback should be either on this forum thread or, if you would like to keep your feedback private, directly to the review manager. When messaging the review manager directly, please keep the proposal link at the top of the message.

Trying it out

To try this feature out add a dependency to thejgrynspan/attachment-json-enhancements branch of the swift-testing repo to your project:

...
dependencies: [
  ...
  .package(
    url: "https://github.com/swiftlang/swift-testing.git",
    branch: "jgrynspan/attachment-json-enhancements"
  ),
]

Then, add a target dependency to your test target:

...
.testTarget(
  ...
  dependencies: [
    ...
    .product(name: "Testing", package: "swift-testing"),
  ]
)

What goes into a review?

The goal of the review process is to improve the proposal under review through constructive criticism and, eventually, determine the direction of Swift and. When writing your review, here are some questions you might want to answer in your review:

  • What is your evaluation of the proposal?
  • Is the problem being addressed significant enough to warrant a change to Swift?
  • Does this proposal fit well with the feel and direction of Swift?
  • If you have used other languages or libraries with a similar feature, how do you feel that this proposal compares to those?
  • How much effort did you put into your review? A glance, a quick reading, or an in-depth study?

More information about the Swift evolution process is available at swift-evolution/process.md at main · swiftlang/swift-evolution · GitHub

Thank you for contributing to Swift!

Maarten Engels
Review Manager

Hello Swift Testing workgroup, and thank you for shepherding this through review — the motivation section is genuinely convincing.

One practical point from running a JSON event-stream consumer ourselves: the Base64-vs-array choice matters more than it first appears for consumers that stream rather than parse-and-discard. A byte array inflates payloads roughly 4× versus Base64 (and far more against compact Base64 with no separators), and on constrained producers — exactly the embedded-device case the motivation calls out — that inflation can dominate everything else in the event stream. So we'd gently encourage implementations to default to the Base64 form, and perhaps to say explicitly in the proposal which representation tools are expected to emit when both are legal, so consumers don't have to branch on it.

Relatedly: with "path" now optional and "bytes" inline, a consumer can no longer tell whether an attachment was ever written to disk at all. That's fine for the stream itself, but tool authors who persist transcripts may want a hint about whether re-saving is even possible — preferredName helps, and we're glad it's included; we just want to make sure consumers won't read "path": null as "the file is gone" when in fact it was never written.

Finally, the new error semantics look right: an attachment that fails to serialize now reports its own failure instead of poisoning the whole test run. We've hit exactly this class of bug with external attachments on flaky filesystems, and having the error travel with the attachment (rather than as a separate event keyed by id) is the more robust design.

Overall: +1 from us, motivated by real consumer pain rather than speculation. Effort for this review: a careful read of the schema diff plus checking it against our own event-stream tooling.

1 Like