Repository navigation
Test Logic with Wasm
The wasm backend is the way to explore your own logic on a Mac, with no Hermit, no Linux and no hardware counters. You write the part you want tested as a WebAssembly module that asks Hairspring to make every decision that could differ between runs (which thread goes next, whether a message is lost). Hairspring picks the answers from a seed, records them, replays them, and shrinks a failing run. This is the short version of docs/guides/test-logic-with-wasm.md.
It is not your real program under real threads. To test an unmodified Linux program use the process backend (Is-My-Machine-Suitable).
Everything here was run on an Apple silicon Mac with the released v0.1-RC1 binary and with a build of main.
A guest imports from the module hairspring: choose(n: i32) -> i32 (a recorded decision in 0..n), rand_u64() -> i64, now_ms() -> i64, sleep_ms(ms: i64), log(ptr, len) and fail(ptr, len) (a violated property; stops the run). It exports run() -> i32 (0 is success; a non-zero return is a failure) and a memory. A module with no run export is refused before any run: ERROR norun: module must export a function named `run` , exit 2. WebAssembly has no threads: your "threads" are steps your own code interleaves, with choose deciding the order.
guest.wat (Hairspring reads .wat text directly):
(module
(import "hairspring" "choose" (func $choose (param i32) (result i32)))
(import "hairspring" "fail" (func $fail (param i32 i32)))
(memory (export "memory") 1)
(data (i32.const 0) "lost update")
;; Two "threads", each doing: read the counter, then write read+1.
;; pa and pb are each thread's progress: 0 = not started, 1 = has read, 2 = has written.
;; Every time both threads can still move, choose(2) decides which one takes the next half-step.
(func (export "run") (result i32)
(local $counter i32) (local $a i32) (local $b i32) (local $pa i32) (local $pb i32)
(block $done
(loop $step
(br_if $done (i32.and (i32.eq (local.get $pa) (i32.const 2)) (i32.eq (local.get $pb) (i32.const 2))))
(if (i32.and (i32.lt_u (local.get $pa) (i32.const 2))
(i32.or (i32.eq (local.get $pb) (i32.const 2)) (i32.eqz (call $choose (i32.const 2)))))
(then
(if (i32.eqz (local.get $pa))
(then (local.set $a (local.get $counter)))
(else (local.set $counter (i32.add (local.get $a) (i32.const 1)))))
(local.set $pa (i32.add (local.get $pa) (i32.const 1))))
(else
(if (i32.eqz (local.get $pb))
(then (local.set $b (local.get $counter)))
(else (local.set $counter (i32.add (local.get $b) (i32.const 1)))))
(local.set $pb (i32.add (local.get $pb) (i32.const 1)))))
(br $step)))
;; The property: no update was lost. If it does not hold, report it (this stops the run).
(if (i32.ne (local.get $counter) (i32.const 2))
(then (call $fail (i32.const 0) (i32.const 11))))
(i32.const 0)))hairspring.toml:
[target.counter]
kind = "wasm"
module = "guest.wat"$ hairspring test counter --seed 1
hairspring: exploring counter (seed 1)
FAILED counter (wasm)
lost update; shrunk from 4 to 1 choices
steps (5):
1. choose(2) -> 1
2. choose(2) -> 0
3. choose(2) -> 0
4. choose(2) -> 0
5. result: lost update
...
bundle written: .hairspring/bundles/counter-2727de2a.hairspring (replay with `hairspring replay .hairspring/bundles/counter-2727de2a.hairspring`)
$ hairspring replay .hairspring/bundles/counter-2727de2a.hairspring
replaying 5 steps on target `counter` (backend wasm)
...
reproduced: the property is still violated
$ hairspring doctor counter
counter: deterministic over 8 seeds
test and replay exit 1, doctor exits 0. The released binary printed the same, except that doctor ended x 0 steps, wording that main dropped. A sweep, hairspring test counter --sweep --seeds 1..21, printed sweep: 20 trials: 9 pass, 11 violation, 0 inconclusive, 0 unusable, 0 infra, then failing seeds: 1, 4, 10, 12, 13, 14, 15, 16, 18, 19 (first 10 of 11 violations), then hits: 11/20 rated trials (55.00%), Wilson 95% interval [34.20%, 74.19%].
The same guest written in C (clang --target=wasm32 -O2 -nostdlib -Wl,--no-entry -Wl,--allow-undefined -o guest-c.wasm guest.c, with __attribute__((import_module("hairspring"), import_name("choose"))) on the imports and export_name("run") on run) and in Rust (a cdylib for wasm32-unknown-unknown with #[link(wasm_import_module = "hairspring")]) were built in an Ubuntu 24.04 container, copied to the Mac and run: both failed with lost update and doctor said deterministic over 8 seeds. The source of both is in the full page. Apple's clang on the Mac knows the target but has no wasm-ld, and Homebrew's Rust has no rustup, so the builds were not run on the Mac. Other languages were not tried.
- It is a model you write, not your real program: real threads, sockets, libc and the kernel are not in it.
- It has no threads; concurrency is whatever your guest interleaves with
choose. - Only the imports control time, randomness and decisions.
- Limits: the default step budget is 200,000 instructions (an infinite loop reports
did not finish within 200000 instructions (possible infinite loop)), the module may be at most 16 MiB and its memory 64 MiB.
Understand
- What-is-Hairspring
- Concepts-and-Vocabulary
- How-Deterministic-Simulation-Works
- Sweeps-and-Confirmation
- Limits-and-Honesty
Use
- Installation
- Your-First-Run
- Running-Your-Own-Software
- Guest-SDKs-by-Language
- Examples-Overview
- Hairspring-in-CI
- Operate-a-Server
- Upgrading-and-Versions
- Troubleshooting
Reference