Getting Started

FlakeMonster is an async fuzzer for JavaScript. It injects deterministic timing delays into your code to surface the flaky tests that hide in fast environments.

Why FlakeMonster?

In your development environment, async operations resolve instantly, calls happen in sync, and race conditions hide. Your tests pass locally but flake in CI because the timing is different.

FlakeMonster fuzzes your async timing with deterministic await delays. Same seed, same delays, every run. When a test fails, you get the exact seed to reproduce it.

Installation

FlakeMonster requires Node.js 18 or later.

$ npm install flake-monster

Or run directly with npx (no install needed):

$ npx flake-monster test --cmd "npm test"

Quick Start

Run FlakeMonster against your test suite in one command:

$ npx flake-monster test --cmd "npm test"

This will:

  1. Inject deterministic async delays into your source files
  2. Run your test command 10 times, each with a different seed
  3. Analyze results to find tests that pass sometimes and fail sometimes
  4. Restore your source files to their original state
  5. Report which tests are flaky and which seeds triggered failures

Reading the Output

After running, FlakeMonster prints a summary like this:

FlakeMonster v0.4.6  seed=3221704130  mode=medium  runs=10

Run  1/10 PASS (seed=3221704130)
Run  2/10 PASS (seed=1847293651)
Run  3/10 FAIL (seed=948271536)
Run  4/10 PASS (seed=2736481920)
...
Run 10/10 PASS (seed=1029384756)

── Results ──

2 flaky tests detected:

  checkout > applies discount
    Failed seeds: 948271536, 1573920846
    Flaky rate: 20%

  auth > refresh expired token
    Failed seed: 948271536
    Flaky rate: 10%

13 tests stable across all runs.

Each failing run shows its seed. Use that seed to reproduce the exact failure:

$ npx flake-monster test --runs 1 --seed 948271536 --cmd "npm test"

Next Steps