Testing your app
You can write a test suite for your SwiftWasm app or library, or run an existing test suite
written for XCTest
if you port existing code to SwiftWasm. Your project has to have a
Package.swift
package manifest for this to work. We assume that you use SwiftPM to build your
project and that you have a working package manifest. Please follow our SwiftPM guide for new projects.
A simple test case
Let's assume you have a SwiftWasmLibrary
target in your project that you'd like to test. Your
Package.swift
should also have a test suite target with a dependency on the library target. It
would probably look like this:
// swift-tools-version:5.3
// The swift-tools-version declares the minimum version of Swift required to build this package.
import PackageDescription
let package = Package(
name: "HelloSwiftWasm",
products: [
.executable(name: "SwiftWasmApp", targets: ["SwiftWasmApp"]),
],
targets: [
// Targets are the basic building blocks of a package. A target can define a module or a test
// suite. Targets can depend on other targets in this package, and on products in packages which
// this package depends on.
.target(
name: "SwiftWasmApp",
dependencies: ["SwiftWasmLibrary"],
),
.target(name: "SwiftWasmLibrary"),
.testTarget(name: "SwiftWasmTests", dependencies: ["SwiftWasmLibrary"]),
]
)
Now you should make sure there's Tests/SwiftWasmTests
subdirectory in your project.
If you don't have any files in it yet, create SwiftWasmTests.swift
in it:
import SwiftWasmLibrary
import XCTest
final class SwiftWasmTests: XCTestCase {
func testTrivial() {
XCTAssertEqual(text, "Hello, world")
}
}
This code assumes that your SwiftWasmLibrary
defines some text
with "Hello, world"
value
for this test to pass. Your test functions should all start with test
, please see XCTest
documentation
for more details.
XCTest limitations in the SwiftWasm toolchain
As was mentioned in our section about Swift Foundation, multi-threading and
file system APIs are currently not available in SwiftWasm. This means that XCTestExpectation
and test hooks related to Bundle
(such as testBundleWillStart(_:)
and testBundleDidFinish(_:)
)
are not available in test suites compiled with SwiftWasm. If you have an existing test suite you're
porting to WebAssembly, you should use #if os(WASI)
directives to exclude places where you use
these APIs from compilation.
Building and running the test suite with carton
If you use carton
to develop and build your app, as described in our guide
for browser apps, just run carton test
in the
root directory of your package. This will automatically build the test suite and run it with
Wasmer for you.
Building and running the test suite with SwiftPM
If you manage your SwiftWasm toolchain without carton
(as shown in the "Setup" section),
you can build your test suite by running this command in your terminal:
$ swift build --build-tests --triple wasm32-unknown-wasi
If you're used to running swift test
to run test suites for other Swift platforms, we have to
warn you that this won't work. swift test
doesn't know what WebAssembly environment you'd like to
use to run your tests. Because of this building tests and running them are two separate steps when
using SwiftPM
. After your tests are built, you can use a WASI-compatible host such as
Wasmer to run the test bundle:
$ wasmer .build/debug/HelloSwiftWasmPackageTests.xctest
As you can see, the produced test binary starts with the name of your package followed by
PackageTests.xctest
. It is located in the .build/debug
subdirectory, or in the .build/release
subdirectory when you build in release mode.