Skip to content

Revise WASI documentation for swift test commands #1595

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
MaxDesiatov merged 8 commits into from
Mar 18, 2026
+37 −16
Merged

Revise WASI documentation for swift test commands #1595

Changes from 4 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
36f9cbf
Revise WASI documentation for `swift test` commands
MaxDesiatov Feb 26, 2026
23749d5
Apply suggestions from code review
MaxDesiatov Feb 26, 2026
a7e800a
Fix Swift SDK ID extraction in WASI documentation
MaxDesiatov Feb 26, 2026
fb8611a
Update Documentation/WASI.md
MaxDesiatov Feb 27, 2026
e3a13c1
Apply suggestions from code review
MaxDesiatov Mar 17, 2026
445f7c7
Update Documentation/WASI.md
MaxDesiatov Mar 17, 2026
f2d7005
Apply suggestions from code review
MaxDesiatov Mar 18, 2026
b822825
Clean up formatting
MaxDesiatov Mar 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 21 additions & 9 deletions Documentation/WASI.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,31 +14,43 @@ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
because it provides instructions the reader must follow directly. -->

To run tests for WebAssembly, install a Swift SDK for WebAssembly by following
[these instructions](https://book.swiftwasm.org/getting-started/setup.html).
[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

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:

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

## Swift 6.2
Copy link
Contributor

@grynspan grynspan Feb 27, 2026

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

@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.

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

Copy link
Contributor

@grynspan grynspan Feb 27, 2026

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 •
edited
Loading

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

@heckj heckj Feb 28, 2026

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


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:

```sh
swift build --swift-sdk wasm32-unknown-wasi --build-tests
swift build --swift-sdk "$(swiftc -print-target-info | jq -r '.swiftCompilerTag')_wasm" --build-tests
```

After building tests, you can run them using a [WASI](https://wasi.dev/)-compliant
WebAssembly runtime such as [Wasmtime](https://wasmtime.dev/) or
[WasmKit](https://github.com/swiftwasm/WasmKit). For example, to run tests using
Wasmtime, use the following command (replace `{YOURPACKAGE}` with your package's
WebAssembly runtime such as [WasmKit](https://github.com/swiftwasm/WasmKit).
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):

```sh
wasmtime .build/debug/{YOURPACKAGE}PackageTests.wasm --testing-library swift-testing
wasmkit run .build/debug/{YOURPACKAGE}PackageTests.wasm --testing-library swift-testing
```

Most WebAssembly runtimes forward trailing arguments to the WebAssembly program,
so you can pass command-line options of the testing library. For example, to list
all tests and filter them by name, use the following commands:

```sh
wasmtime .build/debug/{YOURPACKAGE}PackageTests.wasm list --testing-library swift-testing
wasmtime .build/debug/{YOURPACKAGE}PackageTests.wasm --testing-library swift-testing --filter "FoodTruckTests.foodTruckExists"
wasmkit run .build/debug/{YOURPACKAGE}PackageTests.wasm list --testing-library swift-testing
wasmkit run .build/debug/{YOURPACKAGE}PackageTests.wasm --testing-library swift-testing --filter "FoodTruckTests.foodTruckExists"
```