Skip to content
Back to search

raceloom

Find race conditions in async JavaScript & Python: explores every ordering of your awaits, shrinks the failure, prints the exact interleaving.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/anime5hka--raceloom/badge.svg)](/listings/anime5hka--raceloom)

HTML

<a href="/listings/anime5hka--raceloom"><img src="/api/listings/anime5hka--raceloom/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**JavaScript / TypeScript** (Node ≥ 20, any test runner):

npm install --save-dev github:Anime5hka/raceloom

**Python** (asyncio, Python ≥ 3.11, pytest or anything else) — see [python/README.md](python/README.md):

pip install "git+https://github.com/Anime5hka/raceloom#subdirectory=python"

Wrap the async boundaries of your test (your fake db, API client, cache…) with `sim.wrap` / `sim.fn`, and put the test body inside `explore`:

import { test } from 'node:test';           // or vitest, or jest (ESM mode)
import assert from 'node:assert/strict';
import { explore } from 'raceloom';

test('search box shows results for the latest query', async () => {
  await explore(async (sim) => {
    const api = sim.wrap('api', {
      async search(q) { return [`${q}ust`, `${q}ce`]; },
    });
    const box = createSearchBox(api);        // your real code

    await Promise.all([
      sim.go('keystroke 1', () => box.onInput('r')),
      sim.go('keystroke 2', () => box.onInput('ra')),
    ]);

    assert.ok(box.ui.results.every((r) => r.startsWith(box.ui.query)));
  });
});

A plain version of this test passes. With raceloom it fails with the timeline above: the response for `"ra"` overtook the response for `"r"`, so the UI shows results for the wrong query. Paste the replay token into `explore(fn, { replay: "1:1" })` and you get that exact interleaving every time — perfect for a debugger.

<details> <summary><b>The same test in Python</b></summary>

import asyncio
from raceloom import explore

def test_search_box_shows_latest_results():
    async def scenario(sim):
        api = sim.wrap("api", FakeSearchApi())
        box = SearchBox(api)                     # your real code
        async with asyncio.TaskGroup() as tg:
            tg.create_task(box.on_input("r"), name="keystroke 1")
            tg.create_task(box.on_input("ra"), name="keystroke 2")
        assert all(r.startswith(box.query) for r in box.results)

    explore(scenario)

In Python every asyncio timer (`sleep`, `wait_for`, `asyncio.timeout`) runs on the virtual clock automatically. </details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 215 lines
  1. <h1 align="center">raceloom 🧶</h1>
  2. <p align="center">
  3. <b>Find race conditions in async JavaScript and Python before your users do.</b><br>
  4. raceloom re-runs your test under every ordering of its <code>await</code>s, shrinks the failure<br>
  5. to the one reordering that matters, and prints exactly what happened.
  6. </p>
  7. <p align="center">
  8. <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="zero dependencies">
  9. <img src="https://img.shields.io/badge/node-%3E%3D20-339933" alt="node >= 20">
  10. <img src="https://img.shields.io/badge/python-%3E%3D3.11-3776ab" alt="python >= 3.11">
  11. <img src="https://img.shields.io/badge/types-included-3178c6" alt="TypeScript types included">
  12. <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT"></a>
  13. </p>
  14. <p align="center">
  15. <img src="assets/demo.svg" alt="raceloom finding a stale-response race in a search box" width="820">
  16. </p>
  17. Your tests pass because fake promises resolve in the order you wrote them. Production doesn't care about that order: the second request comes back first, the cache invalidation lands before the stale write, the 30-second timeout fires while the payment call is still in flight.
  18. raceloom is a tiny, zero-dependency library that makes those orderings **testable, exhaustive and reproducible** — like [loom](https://github.com/tokio-rs/loom) for Rust or deterministic simulation testing, but as a 5-line change to a test you already have.
  19. <p align="center">
  20. <a href="#quick-start">Quick start</a> ·
  21. <a href="#what-it-catches">What it catches</a> ·
  22. <a href="#how-it-compares">How it compares</a> ·
  23. <a href="#how-it-works">How it works</a> ·
  24. <a href="#api">API</a> ·
  25. <a href="#use-it-from-ai-coding-agents">AI agents</a> ·
  26. <a href="#faq">FAQ</a>
  27. </p>
  28. ## Quick start
  29. **JavaScript / TypeScript** (Node ≥ 20, any test runner):
  30. ```sh
  31. npm install --save-dev github:Anime5hka/raceloom
  32. ```
  33. **Python** (asyncio, Python ≥ 3.11, pytest or anything else) — see [python/README.md](python/README.md):
  34. ```sh
  35. pip install "git+https://github.com/Anime5hka/raceloom#subdirectory=python"
  36. ```
  37. Wrap the async boundaries of your test (your fake db, API client, cache…) with `sim.wrap` / `sim.fn`, and put the test body inside `explore`:
  38. ```js
  39. import { test } from 'node:test'; // or vitest, or jest (ESM mode)
  40. import assert from 'node:assert/strict';
  41. import { explore } from 'raceloom';
  42. test('search box shows results for the latest query', async () => {
  43. await explore(async (sim) => {
  44. const api = sim.wrap('api', {
  45. async search(q) { return [`${q}ust`, `${q}ce`]; },
  46. });
  47. const box = createSearchBox(api); // your real code
  48. await Promise.all([
  49. sim.go('keystroke 1', () => box.onInput('r')),
  50. sim.go('keystroke 2', () => box.onInput('ra')),
  51. ]);
  52. assert.ok(box.ui.results.every((r) => r.startsWith(box.ui.query)));
  53. });
  54. });
  55. ```
  56. A plain version of this test passes. With raceloom it fails with the timeline above: the response for `"ra"` overtook the response for `"r"`, so the UI shows results for the wrong query. Paste the replay token into `explore(fn, { replay: "1:1" })` and you get that exact interleaving every time — perfect for a debugger.
  57. <details>
  58. <summary><b>The same test in Python</b></summary>
  59. ```python
  60. import asyncio
  61. from raceloom import explore
  62. def test_search_box_shows_latest_results():
  63. async def scenario(sim):
  64. api = sim.wrap("api", FakeSearchApi())
  65. box = SearchBox(api) # your real code
  66. async with asyncio.TaskGroup() as tg:
  67. tg.create_task(box.on_input("r"), name="keystroke 1")
  68. tg.create_task(box.on_input("ra"), name="keystroke 2")
  69. assert all(r.startswith(box.query) for r in box.results)
  70. explore(scenario)
  71. ```
  72. In Python every asyncio timer (`sleep`, `wait_for`, `asyncio.timeout`) runs on the virtual clock automatically.
  73. </details>
  74. ## What it catches
  75. Every example in [`examples/`](examples) (and its Python twin in [`python/examples/`](python/examples)) is a real bug that a normal unit test misses:
  76. | Example | Bug | Found in |
  77. |---|---|---|
  78. | [search-box](examples/search-box.test.js) | Stale response overwrites newer results | 2 schedules |
  79. | [cache-invalidation](examples/cache-invalidation.test.js) | Reader re-populates the cache with stale data after a writer invalidated it | 5 schedules |
  80. | [job-queue](examples/job-queue.test.js) | Visibility timeout fires during a slow payment → customer charged twice (plain `setTimeout` code, virtual clock) | 4 schedules |
  81. ```sh
  82. git clone https://github.com/Anime5hka/raceloom && cd raceloom && npm run examples
  83. # Python: cd python && pip install -e . pytest && pytest examples/
  84. ```
  85. **Against real libraries:** [`case-studies/`](case-studies) runs raceloom on unmodified `lru-cache`, `async-lru`, `aiolimiter` and `aiocache`. It *proves* lru-cache's fetch-vs-delete handling safe in all 15 orderings — and finds in 2 schedules that aiocache's `@cached` writes a stale row back into the cache when an invalidation lands while a read is in flight.
  86. ## Use it from AI coding agents
  87. [`skills/raceloom/SKILL.md`](skills/raceloom/SKILL.md) is an agent skill that teaches Claude Code (and other agents that read `SKILL.md`) when to reach for raceloom, how to pick the racing actors, which invariant to assert, and how to explain the timeline. Install it for your user:
  88. ```sh
  89. mkdir -p ~/.claude/skills/raceloom && curl -fsSL https://raw.githubusercontent.com/Anime5hka/raceloom/main/skills/raceloom/SKILL.md -o ~/.claude/skills/raceloom/SKILL.md
  90. ```
  91. Then ask: *"is there a race between `getUser` and `renameUser`?"*
  92. ## How it compares
  93. | | Explores every ordering | Shrinks to the minimal failure | Readable timeline | Replay | Python too |
  94. |---|:-:|:-:|:-:|:-:|:-:|
  95. | Re-running the test many times | ❌ one ordering, the same every time | ❌ | ❌ | ❌ | – |
  96. | Hand-written orderings (resolve fake promise B before A) | only the ones you think of | – | ❌ | ✅ | – |
  97. | [fast-check](https://fast-check.dev/) scheduler | random sampling inside property tests | ✅ | partial | ✅ seed | ❌ |
  98. | [loom](https://github.com/tokio-rs/loom) | ✅ | – | ❌ | ✅ | ❌ Rust only |
  99. | **raceloom** | ✅ exhaustive, or PCT for big searches | ✅ | ✅ per task | ✅ `err.replay` | ✅ asyncio |
  100. ## How it works
  101. 1. **Every wrapped call becomes a pending operation.** `sim.wrap('db', fakeDb)` returns a proxy; calling `db.get('alice')` doesn't run the fake yet — it parks the call.
  102. 2. **raceloom decides what runs next.** Whenever your code is idle (all microtasks drained), it picks one pending operation or timer to complete. In the default order, operations complete in the order they were called — that's the schedule your plain test already covers.
  103. 3. **It explores the others.** First it enumerates every ordering depth-first. If the space is too large for the budget, it switches to seeded sampling: uniform random choices alternating with [PCT](https://www.microsoft.com/en-us/research/publication/a-randomized-scheduler-with-probabilistic-guarantees-of-finding-bugs/) (probabilistic concurrency testing), which finds bugs where one task has to stall for a long time — the ones uniform random almost never hits. When enumeration finishes without a failure, `explore` tells you so (`{ complete: true }`) — that's a proof, not a sample.
  104. 4. **It shrinks failures.** The failing schedule is minimized to the fewest out-of-order steps, so the timeline shows the cause, not noise. Steps marked `⚡ overtook N earlier pending ops` are where reality diverged from the happy path.
  105. 5. **It replays.** The `replay` token (`seed:choices`) re-runs exactly that schedule, deterministically.
  106. **Network round trips.** By default an operation runs and returns in one step. With `{ network: true }` it becomes two: the implementation *executes* (`⚙ db.load(1) executed`) and, at a later point, the *response arrives*. That exposes a whole extra class of bugs — e.g. a read that executes before a write but whose response lands after the cache was invalidated. `sim.mockFetch` uses this mode by default.
  107. Time is virtual. `sim.sleep(30_000)` takes microseconds, timers fire in deadline order, and an operation may complete before *or after* any timer — which is exactly how timeouts race in production. With `patchGlobals: true`, unmodified code that uses `setTimeout`, `setInterval`, `setImmediate`, `Date` and `Math.random` runs on the virtual clock too.
  108. ## API
  109. ### `explore(body, options?) → Promise<{ schedules, complete, strategy }>`
  110. Runs `body(sim)` once per schedule. **Create your fakes inside `body`** — every schedule gets a fresh world. Rejects with a `RaceError` on the first failing schedule (an assertion, a thrown error, an unhandled rejection, a deadlock, or a runaway loop).
  111. | Option | Default | |
  112. |---|---|---|
  113. | `runs` | `1000` | Maximum schedules to try |
  114. | `strategy` | `'auto'` | `'exhaustive'`, `'random'`, `'pct'`, or `'auto'` (exhaustive for half the budget, then alternating random and PCT) |
  115. | `pctDepth` | `3` | Max bug depth (number of ordering constraints) PCT targets |
  116. | `seed` | `1` | Base seed (`RACELOOM_SEED` env var overrides the default) |
  117. | `replay` | — | Re-run one schedule from a `RaceError`'s token |
  118. | `patchGlobals` | `false` | Virtualize `setTimeout`/`setInterval`/`setImmediate`/`Date`/`Math.random` |
  119. | `unhandledRejections` | `true` | Fail when a wrapped operation rejects and nothing ever handles it (e.g. a fire-and-forget `send()` that only fails in some orderings) |
  120. | `shrink` | `true` | Minimize failing schedules (`shrinkRuns`: budget, default 500) |
  121. | `maxSteps` | `10000` | Fail a schedule that takes more scheduling steps than this |
  122. | `timeLimit` | — | Stop exploring after N ms of real time |
  123. ### The `sim` object
  124. | | |
  125. |---|---|
  126. | `sim.wrap(name, obj, { network? })` | Proxy every method of `obj`; each call is a schedulable op labelled `name.method(args)` |
  127. | `sim.fn(name, impl, { network? })` | Same for a single function |
  128. | `sim.mockFetch(handler, { global? })` | A `fetch` whose requests are schedulable ops (`fetch GET /search?q=r`). `handler(request)` returns a `Response`, string or JSON value. `global: true` swaps `globalThis.fetch` for the schedule |
  129. | `sim.go(name, fn)` | Run `fn` as a named task — the name appears in the timeline |
  130. | `sim.sleep(ms)` / `sim.setTimeout` / `sim.setInterval` / `sim.clear*` | Virtual timers |
  131. | `sim.yield(label?)` | An explicit preemption point inside synchronous-looking code |
  132. | `sim.now()` / `sim.random()` | Virtual clock and seeded randomness |
  133. | `sim.log(...)` | Add a note to the timeline |
  134. ### `RaceError`
  135. `err.cause` is your original error. Also: `err.replay`, `err.trace` (structured timeline events), `err.decisions`, `err.seed`, `err.schedule`.
  136. ## FAQ
  137. **Which async operations get reordered?** Only the ones you route through `sim` (wrapped fakes, virtual timers, `sim.yield`). Ordinary `await`s of already-resolved promises stay where they are — those can't race. This keeps the search space small and the timelines readable.
  138. **Can my fakes do real I/O?** They can, but the result depends on real timing, so a schedule is no longer perfectly reproducible. Prefer in-memory fakes — that's what makes `replay` exact.
  139. **How is this different from fast-check's scheduler?** Same family of idea. raceloom is a focused tool for one job: zero-config exhaustive enumeration (with a completeness answer), automatic shrinking, task-labelled timelines, virtual time for timeouts, and drop-in use in any test runner.
  140. **Is it fast?** Roughly 10,000 schedules per second for small tests: all 5,040 orderings of 7 concurrent operations are explored (and proven race-free) in about 0.4 s on a single core. The examples above find, shrink and report their bug in 10–20 ms.
  141. **Which test runners?** Tested with `node:test`, vitest and jest. raceloom is ESM-only, so jest needs its ESM mode (`NODE_OPTIONS=--experimental-vm-modules jest`).
  142. **Caveats.** `patchGlobals` swaps process-wide globals, so don't run those tests concurrently in the same worker. Exhaustive search grows factorially with the number of *concurrently* pending operations — keep each test focused on 2–4 racing actors, which is where real bugs live.
  143. ## Roadmap
  144. - [ ] Partial-order reduction (skip orderings of independent operations) for much larger exhaustive searches
  145. - [x] PCT strategy (probabilistic concurrency testing) for deep bugs in big state spaces
  146. - [x] Two-phase operations (`{ network: true }`: request executes, response arrives later)
  147. - [x] `sim.mockFetch` so code that calls `fetch` can be tested with zero glue
  148. - [x] Unhandled-rejection detection inside schedules
  149. - [ ] Browser build
  150. - [x] Python / asyncio port
  151. - [ ] Trio and AnyIO support for the Python port
  152. Ideas and bug reports welcome — especially real-world races that raceloom should (or can't yet) catch.
  153. ## See also
  154. [sqlloom](https://github.com/Anime5hka/sqlloom) runs every interleaving of your SQL transactions on a real Postgres. [shakeout](https://github.com/Anime5hka/shakeout) finds flaky tests in a whole existing suite with seeded timing jitter, no test changes.
  155. ## License
  156. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.