A contract to review
Write down the real atomic operations and what must stay true. For the counter: every completed increment contributes exactly one to the total.
Explore how your application behaves under retries, failures and unexpected event orderings. Check the design before you build, then use the same specs in your application tests.
Two clients each add one to a shared counter. Each reads the current value, then writes back that value plus one. What happens if both read before either writes?
This is P: state machines exchange messages with send and handle them with on. The test starts two clients and checks that the final counter is 2. Run the model to explore message orderings, then try making the increment atomic.
machine Counter {
var value: int;
start state Serving {
on eRead do (c: Client) { send c, eValue, value; }
on eWrite do (v: int) { value = v; }
on eGet do (m: Main) { send m, eValue, value; }
}
}
machine Client {
start state Run {
entry (input: (counter: Counter, owner: Main)) {
var v: int;
send input.counter, eRead, this;
receive { case eValue: (x: int) { v = x; } }
send input.counter, eWrite, v + 1;
send input.owner, eDone;
}
}
}assert final == 2;Each client runs independently. The checker chooses which message is delivered next.
Read then write leaves a gap for the other client to run. Atomic increment updates the value in a single handler.
Run the model, inspect the result, then try the other design or edit the P code.
The real checker runs locally in your browser. No installation, and no code leaves this page.
A spec is a state machine that observes events and checks rules about them. Check the model's events while designing, then check your application's events from ordinary tests.
You, or an agent, write a model of the design. snappea check runs it thousands of times, each with a different ordering of messages, and the spec flags any run that breaks a rule. None of your service code is involved.
Illustration of the shared-spec workflow; the animation is not a live check.
Write down the real atomic operations and what must stay true. For the counter: every completed increment contributes exactly one to the total.
Express that contract independently of the algorithm. Check events from both the P model and real application calls against it.
Force both calls to read before either writes. Use the counterexample to test the implementation, rather than hoping a stress test hits it.
When a check fails, review the design, model and implementation together. Turn counterexamples into regression tests that force the troublesome ordering on real code.
Model checks cover the behavior and assumptions you modeled. Application checks validate the events your tests produce; they do not explore every execution of your code or establish full equivalence.
A model that passes without testing the important behavior gives false confidence. Snap Pea helps you find weak checks.
Coverage shows which branches, handlers and scenarios your checks reached, and where the model needs a better workload.
Understand coverage →Mutation testing changes the model and asks whether your specs notice. A passing run is more useful when the checks can reject mistakes.
Mutation testing →Lints catch unselected specs, assertions that are always true, and monitors that accept everything, before exploration starts.
Model lints →Passing checks report limits observed in the test driver: fixed client counts, input values and event orders. Extend the driver when real clients can do more.
Driver limits →Ask your agent to model a feature before implementing it. The built-in guide teaches the workflow, modeling boundaries and implementation tests. Structured CLI results and actionable diagnostics help it inspect failures and revise the model. You review the contract, assumptions and specs.
snappea guide # workflow, built into the binary
snappea guide examples # runnable examples
snappea check # lint, explore, report coverage and mutations
snappea check --json # structured results for agentsOne binary, no compile step or runtime toolchain. Automatic exploration combines exhaustive search, coverage-guided random search, deliberate delays and priority scheduling. It adapts the mix as it discovers new behavior, so you can set a CI time budget without choosing a scheduler.
Install the prebuilt checker on Linux or macOS, then read the built-in guide:
$ curl -fsSL https://raw.githubusercontent.com/crowecawcaw/snappea/main/scripts/install.sh | sh
$ export PATH="$HOME/.local/bin:$PATH"
$ snappea guideSee the installation guide for PATH setup, Windows, pinned versions, Cargo and PyPI options. GitHub releases include binaries for Linux, macOS and Windows. Add a helper to check events from your application tests:
$ pip install pysnappea # Python
$ cargo add --dev snappea # Rust
$ go get github.com/crowecawcaw/snappea # GoJava: io.github.crowecawcaw:snappea on Maven Central, plus a natives jar with the checker (Maven and Gradle snippets). Each language has a guide: Python, Rust, Go, Java.
Keep your P models. snappea-compat is a drop-in replacement for the p CLI in existing checking scripts, preserving upstream options, output and replayable schedules, with no compile step. Use the native snappea CLI for automatic scheduling and model quality checks. See compatibility and migration for supported behavior and differences.
Run more schedules per second and direct the search toward new behavior. On our synthetic search benchmarks, Snap Pea's guided feedback search finds bugs in fewer schedules than the original feedback strategy. Native checking combines several search strategies automatically; results vary by model and seed. Search measurements and methodology.
Checking the Raft tutorial, 120 schedules:
Warmed up, snappea checks 290 schedules per second, and P checks 4. Results vary by model. Benchmark setup and results