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.