Skip to content

Revise WASI documentation for swift test commands#1595

Open
MaxDesiatov wants to merge 4 commits intomainfrom
maxd/wasm-instructions
Open

Revise WASI documentation for swift test commands#1595
MaxDesiatov wants to merge 4 commits intomainfrom
maxd/wasm-instructions

Conversation

@MaxDesiatov
Copy link
Contributor

Updated links and commands for running WebAssembly tests with swift test, including changes from Wasmtime to WasmKit.

Updated links and commands for running WebAssembly tests with `swift test`, including changes from Wasmtime to WasmKit.
@grynspan grynspan added documentation 📚 Improvements or additions to documentation wasi/wasm 🧭 WebAssembly support labels Feb 27, 2026
@grynspan grynspan added this to the Swift 6.4.0 (main) milestone Feb 27, 2026
Co-authored-by: Jonathan Grynspan <jgrynspan@apple.com>
@MaxDesiatov MaxDesiatov assigned grynspan and unassigned MaxDesiatov Feb 27, 2026
@MaxDesiatov MaxDesiatov requested a review from grynspan February 27, 2026 13:55
swift test --swift-sdk "$(swiftc -print-target-info | jq -r '.swiftCompilerTag')_wasm"
```

## Swift 6.2
Copy link
Contributor

Choose a reason for hiding this comment

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

Our main branch only supports 6.3 onward, so we can drop documentation for 6.2 outright.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

There are still users of 6.2 out there that may stumble upon this document and find it useful.

Copy link
Contributor

Choose a reason for hiding this comment

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

Users of the 6.2 toolchain should refer to the documentation for version 6.2. Our main branch documents itself.

Copy link
Contributor Author

@MaxDesiatov MaxDesiatov Feb 27, 2026

Choose a reason for hiding this comment

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

How would users of the 6.2 toolchain know that? If I'm using Swift Testing for WASI for the first time and searching on GitHub or, if this page was indexed by some other search engine there's no context here that says "these instructions work only for main branch and none of the earlier versions". One would probably have to be a Swift Testing Swift and/or toolchain engineer to orient between branches and click through to a release branch before trying out instructions at the top. I don't think that having this 6.2 section is actively harmful at least until 6.3 or subsequent versions are released, but could be a massive time saver for users of a released version, especially in the absence of different places where this is documented.

Copy link
Member

Choose a reason for hiding this comment

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

The gist is that we generally want to avoid a decision tree where possible. Since this is a forward transition, with 6.3 or later, then it's to call out there's a different process earlier, we use that version of Swift as the marker, but avoid setting up phrasing that leads to a mental "Look up what version of Swift you're using, then following the process from the list below..." kinds of thing

Copy link
Member

@heckj heckj left a comment

Choose a reason for hiding this comment

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

Since this is a transition point to where we're getting SDK support in the swift test command, let's phrase it up as a such, using Swift 6.3 as the marker of the transition. I've made some suggestions to the section headers to re-frame it as such, particularly to avoid leading the reader into a mental "lookup model", which referencing different versions of Swift (development chains, Swift 6.2, etc) start to do.

In our ideal world, we'd have a single direct "To test, do this...", but to call out support for teams using testing with earlier versions, our docs have used the "prior to..." sort of setup as a transition flag.

Comment on lines +21 to +22
In Swift development snapshots, running `swift test --swift-sdk <wasm_swift_sdk_id>` is fully
supported. When you have `jq` installed, you can run this command to compute the Swift SDK ID automatically:
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
In Swift development snapshots, running `swift test --swift-sdk <wasm_swift_sdk_id>` is fully
supported. When you have `jq` installed, you can run this command to compute the Swift SDK ID automatically:
In Swift 6.3 and later, running `swift test --swift-sdk <wasm_swift_sdk_id>` is build and runs your tests.
Use `jq` to extract the Swift SDK ID automatically to build and test in a single command:

[these instructions](https://www.swift.org/documentation/articles/wasm-getting-started.html).

Because `swift test` doesn't know what WebAssembly environment you'd like to use
## Swift Development Snapshots
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
## Swift Development Snapshots

swift test --swift-sdk "$(swiftc -print-target-info | jq -r '.swiftCompilerTag')_wasm"
```

## Swift 6.2
Copy link
Member

Choose a reason for hiding this comment

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

The gist is that we generally want to avoid a decision tree where possible. Since this is a forward transition, with 6.3 or later, then it's to call out there's a different process earlier, we use that version of Swift as the marker, but avoid setting up phrasing that leads to a mental "Look up what version of Swift you're using, then following the process from the list below..." kinds of thing

Comment on lines +30 to 32
In Swift 6.2 `swift test` doesn't know what WebAssembly environment you'd like to use
to run your tests, building tests and running them are two separate steps. To
build tests for WebAssembly, use the following command:
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
In Swift 6.2 `swift test` doesn't know what WebAssembly environment you'd like to use
to run your tests, building tests and running them are two separate steps. To
build tests for WebAssembly, use the following command:
Prior to Swift 6.3 `swift test` doesn't support using the SDK to indicate the WebAssembly environment to use for tests.
In this case, building tests and running them are two separate steps.
To build tests for WebAssembly, use the following command:

Comment on lines +40 to 43
Starting with Swift 6.2, WasmKit is included in Swift toolchains for Linux and macOS
distributed on swift.org. For example, to run tests using
WasmKit, use the following command (replace `{YOURPACKAGE}` with your package's
name):
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
Starting with Swift 6.2, WasmKit is included in Swift toolchains for Linux and macOS
distributed on swift.org. For example, to run tests using
WasmKit, use the following command (replace `{YOURPACKAGE}` with your package's
name):
WasmKit is included in the Swift toolchain for Linux and macOS for Swift 6.2 and later.
Download and install an open-source release toolchain from swift.org to get a toolchain that includes WasmKit.
To run the rests you built previously using the WasmKit runtime, use the following command, replacing `{YOURPACKAGE}` with the name of your package:

swift test --swift-sdk "$(swiftc -print-target-info | jq -r '.swiftCompilerTag')_wasm"
```

## Swift 6.2
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
## Swift 6.2
## Build and Test WebAssembly separately

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation 📚 Improvements or additions to documentation wasi/wasm 🧭 WebAssembly support

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants