Repository navigation
Home
Hairspring is an open-source tool (Apache-2.0) for deterministic simulation testing. In plain words: it runs your system many times, each time with a different but repeatable order of events, looks for the rare run in which something goes wrong, and gives you a small file that makes that exact run happen again on demand.
The bugs it is aimed at are the ones that make developers say "it only fails sometimes": two threads touching the same data in an unlucky order, a message delivered twice, a timer firing at just the wrong moment. Those bugs are hard to catch with ordinary tests because the unlucky order rarely happens, and even when it does, running the test again usually does not bring it back. Hairspring's job is to make the order of events something it chooses from a number called a seed, so that a failing run can be named, kept and replayed.
It runs on your laptop or your own servers. It is experimental: the README says so, and APIs and the bundle format will change.

The web UI that hairspring serve provides, here showing runs of the built-in simulation targets. Your-First-Run walks through it page by page.
- What-is-Hairspring: the problem, the idea, and the three ways Hairspring can run your code.
- Concepts-and-Vocabulary: the dozen words you will see everywhere (target, trial, seed, bundle, and so on), each with a concrete example.
- How-Deterministic-Simulation-Works: the theory, from "why are concurrency bugs hard to reproduce?" to how the Linux backend uses Hermit to control thread scheduling.
- Installation and Your-First-Run: get it built, run a built-in demo and take a tour of the web UI.
- Running-Your-Own-Software: point Hairspring at your own program.
- Sweeps-and-Confirmation: measure how often a failure happens, and check a failure properly before you trust it.
- Limits-and-Honesty: what is and is not claimed, and the one configuration the language results were measured on.
Keep Glossary open in another tab if a word is unfamiliar.
Understanding Hairspring
- What-is-Hairspring: a plain introduction.
- Concepts-and-Vocabulary: the core vocabulary with examples.
- How-Deterministic-Simulation-Works: the theory for beginners.
- Sweeps-and-Confirmation: failure rates and the confirmation pipeline.
- Limits-and-Honesty: claims, non-claims and the support matrix.
- Glossary: short definitions.
Using Hairspring
- Installation: building the CLI, and installing Hermit for the Linux process backend.
- Your-First-Run: running a built-in demo, reading the output and a guided tour of the web UI, with screenshots.
- Running-Your-Own-Software: configuring a target for your own program.
- Is-My-Machine-Suitable: checking a machine for the Linux process backend.
- Build-a-Linux-Executable: building what a process target runs, per language.
- Testing-a-Service: the driver-command pattern for servers.
- Test-Logic-with-Wasm: testing your own logic on a Mac, without Hermit.
- Guest-SDKs-by-Language: the SDKs that let a program report named properties.
- Examples-Overview: the examples in the repository, with links to a page for each.
- Hairspring-in-CI: running Hairspring in continuous integration, with the GitHub Action and without it.
-
Operate-a-Server: tokens, remote workers, PostgreSQL, systemd and backups, for whoever runs
hairspring servefor a team. - Upgrading-and-Versions: which build you have, the schema-version error, upgrading safely, uninstalling.
- Troubleshooting: common errors and what they usually mean.
This wiki is a guide. The repository's own documents are the reference, and where the two differ, the repository wins:
- README
- docs/determinism.md: what was measured about determinism, and the confirmation pipeline.
- docs/support-matrix.md: which languages passed the acceptance test, and on what.
- docs/architecture.md, docs/guest-protocol.md, docs/quickstart.md, docs/ci.md, docs/api.md (the HTTP API).
Hairspring's Linux process backend runs programs under
Hermit, a deterministic-execution tool from Meta (BSD-3-Clause,
Copyright Meta Platforms, Inc. and affiliates), using the maintained fork at
rrnewton/hermit. Hermit is a separate program that you install; none of its code
is in Hairspring. Hairspring is also inspired by the simulation testing of FoundationDB, TigerBeetle's VOPR, Antithesis,
and the record/replay work of rr and Hermit. It is an independent project and is not affiliated with any of them.
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