Skip to content
Tom Barber edited this page Nov 5, 2026 · 6 revisions

Welcome to the Hairspring wiki

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's Overview page, which hairspring serve provides: failed runs and the newest failures under "Needs attention", recent runs with status badges, and a count of workers, beside a side navigation.

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.

If you are new, read in this order

  1. What-is-Hairspring: the problem, the idea, and the three ways Hairspring can run your code.
  2. Concepts-and-Vocabulary: the dozen words you will see everywhere (target, trial, seed, bundle, and so on), each with a concrete example.
  3. 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.
  4. Installation and Your-First-Run: get it built, run a built-in demo and take a tour of the web UI.
  5. Running-Your-Own-Software: point Hairspring at your own program.
  6. Sweeps-and-Confirmation: measure how often a failure happens, and check a failure properly before you trust it.
  7. 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.

All pages

Understanding Hairspring

Using Hairspring

Where the source of truth lives

This wiki is a guide. The repository's own documents are the reference, and where the two differ, the repository wins:

Credit

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.

Clone this wiki locally