wasi-testsuite

This repository contains tests for WebAssembly System Interface (WASI) and a test executor for running WASI tests against a selected WebAssembly runtime.

WASI is a modular collection of standardized APIs. Currently, WASI has not reached version 1.0 stability; this repository contains tests for WASI preview 1 and the forthcoming WASI preview 3.

This repository does not include tests for other in-progress proposals or other experimental APIs, though the test executor can run tests from other repositories (e.g., see the wasi-threads tests).

Getting started

1. Clone the repository; use the prod/testsuite-base branch as it already includes precompiled test binaries (see branch structure):

   git clone --branch prod/testsuite-base https://github.com/WebAssembly/wasi-testsuite

2. Make sure there is already an adapter for the runtime in the adapters directory; if not, create one (see the doc for details).

3. Install python3 (e.g., on Ubuntu):

   sudo apt install python3 python3-pip

4. Install the test runner dependencies:

   python3 -m pip install -r test-runner/requirements.txt

5. Execute the test suites from this repository:

   ./run-tests

By default, the test runner will detect available WASI runtimes from those available in adapters/, and will run tests on all available runtimes. Pass --runtime to instead use a specific runtime.

./run-tests --runtime adapters/wasmtime.py

Running tests will invoke the WASI runtime's binary in a subprocess: wasmtime for adapters/wasmtime.py, iwasm for adapters/wasm-micro-runtime.py, and so on. These binaries can be overridden by setting corresponding environment variables (WASMTIME, IWASM, etc):

WASMTIME="wasmtime --wasm-features all" ./run-tests

Optionally you can specify test cases to skip with the --exclude-filter option.

./run-tests --exclude-filter examples/skip.json

Experimental Buck2 workflow

This repository also has an experimental Buck2 setup for building tests from source and running them through the existing test runner. The first slice covers C, Rust, and AssemblyScript WASI Preview 1 tests with Wasmtime:

Install Dotslash once before using the checked-in ./buck2 launcher, for example with cargo install dotslash.

./buck2 test //tests/...

Build the Buck produced test data archive with:

./buck2 build --show-output //tests:dist

The archive includes the test runner, adapters, Python requirements, and Buck built test data. It can be run like this:

# extract:
mkdir -p dist
tar -xzf buck-out/.../wasi-testsuite.tar.gz -C dist
# setup Python:
python3 -m venv dist/venv
dist/venv/bin/python -m pip install -r dist/wasi-testsuite/test-runner/requirements.txt
# run:
cd dist/wasi-testsuite
WASMTIME=/path/to/wasmtime ../venv/bin/python ./run-tests --runtime-adapter adapters/wasmtime.py

or if you prefer using just

just build
just test
just dist

The Buck2 lint helpers mirror the CI checks:

just lint-starlark
just lint-cxx
just lint-rust

Buck2 fetches the WASI SDK, Node/AssemblyScript, and Wasmtime through the Buck toolchain graph, then uses a generic wasi_test rule to invoke wasi_test_runner for each Buck test target.

Contributing

Want to add a new test? There's a doc for that!

Trying to run these tests using some external test harness? It's possible!

Want to add support for a new WASI runtime? Yes please!

Just want to have a look at the tests? Over here!

Otherwise, suggestions and bugs are very welcome, over on the issue tracker.

Developer guide

Here is some additional information for developers who need to manage the test runner itself.

Directory structure

• test-runner - test executor scripts.
• tests - source code of WASI tests and build scripts. The folder contains subfolders for all supported languages.
• .github - CI workflow definitions.
• doc - additional documentation.

Branch structure

Apart from development branches for various features, we identify the following branches as critical (i.e. they won't be removed or force-updated):

• main - main branch of the repository. Use this branch for development (e.g. updating test cases, modifying test runner)
• prod/testsuite-base - the branch is an up-to-date fork of the main branch but it also includes precompiled binaries. Use this branch for simply running tests and validating WASM runtimes (see doc for details).
• prod/daily-test-results - the branch contains daily test results for supported WASM runtimes. In the future we intend to publish those results to the website to provide users with additional input for selecting the runtime.