Free guide

fast-check: Property-Based Testing for JavaScript and TypeScript, Explained

A free, MIT-licensed testing library that tests a rule instead of a few examples. What it does, how it works, how we caught a one-cent bug we planted in a test app, and how to set it up on your own code.

By Beau Johnson·
The Short this guide goes with: fast-check: Property-Based Testing for JavaScript and TypeScript, Explained

Quick answer

fast-check is a free, open-source (MIT) property-based testing library for JavaScript and TypeScript. Instead of writing a few example inputs, you write a rule that should always hold, and fast-check tries up to 100 random inputs by default. When one breaks the rule, it shrinks it to a simpler input that still fails and prints a seed and path so you can replay that exact failure.

The short version

  • fast-check tests a rule (a property) against random inputs instead of the few examples you thought of. It has over 5,000 GitHub stars and is MIT licensed.
  • We planted a money bug in a small test app. Its five example tests passed. One fast-check rule, format a price and read it back, failed on the first try and shrank the failure 7 times to $4,096.86, which came back one cent short.
  • Install it with npm, write one property, run your tests, and when it fails, paste the printed seed and path back in to replay the same failure.

How it actually works

Example tests only check the prices you thought of

A normal unit test checks inputs you picked: $12.50, $1,000, zero. If the bug lives somewhere you didn't think to look, every test passes. That's how a planted bug in our test app got past all five of its example tests: parsePrice read the price as a decimal number, multiplied by 100 and rounded down.

A property is a rule that should always be true

fast-check's README describes a property as a statement like: for all inputs that meet a precondition, this predicate is true. Ours was a round trip, the same check a cashier makes reading a receipt back: format any price as text, read it back, and you get the same number of cents. You describe the kind of input (here, dollars from 0 to 10,000 and cents from 0 to 99) and fast-check generates them, biased toward both small and large values.

It tries random inputs, then shrinks the one that fails

By default fast-check tries up to 100 random inputs per property, and it stops at the first one that breaks the rule. Then it shrinks it: it keeps trying simpler versions of that input and keeps the ones that still fail. In our run the very first input failed, and it shrank it 7 times to $4,096.86, which our buggy code read back as 409,685 cents instead of 409,686. In JavaScript, 4096.86 times 100 is 409,685.99999999994, and rounding down drops a cent. Shrinking gives you a simpler failing case, not always the smallest one: the smallest failing price in our app was 29 cents, and other seeds landed on other prices.

The seed and path replay the exact failure

Every run starts from a random seed, so different runs can find different failures. When a property fails, fast-check prints the seed and a path. We pasted both back into the test and it failed again straight away on the same $4,096.86 counterexample. That makes it easy to fix the bug and prove the fix, then keep that case as a normal example test.

How to set it up

  1. 1.Install fast-check

    Add it as a dev dependency. It installed 2 packages in our sandbox (fast-check and pure-rand) and works inside the test runner you already use: Node's built-in test runner, Jest, Vitest, Mocha and others. fc.assert throws when a property fails, so any runner reports it.

    npm install --save-dev fast-check
  2. 2.Write one rule for code that must always hold

    Pick a function with a rule you can state in one sentence: a round trip (format then parse gives the input back), a total that can never go negative, a sort that keeps every item. This is the property we used on our test app's price formatter, with Node's built-in test runner.

    import { test } from "node:test";
    import fc from "fast-check";
    import { formatPrice, parsePrice } from "../src/format.js";
    
    // The rule: format any price, read it back, get the same cents.
    const price = fc.record({
      dollars: fc.integer({ min: 0, max: 10_000 }),
      cents: fc.integer({ min: 0, max: 99 }),
    });
    
    test("parsePrice(formatPrice(x)) gives back x", () => {
      fc.assert(
        fc.property(price, ({ dollars, cents }) => {
          const x = dollars * 100 + cents;
          return parsePrice(formatPrice(x)) === x;
        })
      );
    });
  3. 3.Run your tests and read the report

    When a property fails you get four useful lines: how many tries it took, the seed and path, the counterexample, and how many times it shrank. Ours said: Property failed after 1 tests, seed -791927754, Counterexample [{"dollars":4096,"cents":86}], Shrunk 7 time(s).

    npm test
  4. 4.Replay the exact failure with the seed and path

    Paste the printed seed and path into fc.assert as a second argument. The test jumps straight to the same counterexample, so you can fix the code and watch it pass. Use your own printed values; these are from our run.

    fc.assert(
      fc.property(price, ({ dollars, cents }) => {
        const x = dollars * 100 + cents;
        return parsePrice(formatPrice(x)) === x;
      }),
      { seed: -791927754, path: "0:3:2:1:0:1:0:4" }
    );
  5. 5.Have your coding agent write the rules

    If you use Claude Code or another agent, ask it for properties instead of more examples, and read the rules it writes: a weak rule passes weak code. A prompt you can copy: "Write fast-check property tests for src/format.js. First list the rules that must always hold for these functions, then write one property per rule. Don't change the source code."

The fine print

  • MIT license (Copyright 2017 Nicolas Dubien), so it's free, including for companies. Keep the license notice.
  • It only checks the rules you write. A property is only as good as the rule behind it, so someone still has to know what should always be true.
  • Runs are random by design. Different seeds find different failures, so keep the printed seed and path when one fails.
  • Up to 100 runs per property by default (you can change numRuns), so a property takes longer than one example test. Fine for logic, slower for tests that hit a network or a database.
  • JavaScript and TypeScript only. Anthropic's verification post names Hypothesis for Python and proptest for Rust as the same kind of library.
  • In our sandbox it's a plain library: no install scripts, and our tests passed with all outbound network traffic blocked.

FAQ

What is fast-check?

A property-based testing framework for JavaScript and TypeScript, by Nicolas Dubien (GitHub: dubzzz). You write rules that should always hold, and it generates inputs to try to break them. It has been around since 2017 and has over 5,000 GitHub stars.

What is property-based testing?

Instead of checking a few hand-picked examples, you state a property, a rule that should be true for every valid input, and a library generates many inputs to try to prove it wrong. When it finds one, it shrinks it to a simpler failing input you can read.

Is fast-check free?

Yes. It's MIT licensed, which allows commercial use. Install it from npm; there's no account or API key.

How do I replay a failing fast-check test?

Copy the seed and path from the failure report and pass them to fc.assert as options: { seed: ..., path: "..." }. It replays the same counterexample directly.

Does fast-check work with Jest or Vitest?

Yes. fc.assert works inside any test runner because it throws on failure. There are also optional helper packages, @fast-check/jest and @fast-check/vitest.

Can Claude Code write fast-check tests?

You can ask it to, and Anthropic's post on how the Claude Code team thinks about verification names fast-check as the JavaScript and TypeScript library for property tests. Review the rules it writes yourself; the post names the library, it doesn't say the team uses it.

Sources

Facts checked 2026-11-20 against the fast-check README, LICENSE, the GitHub API (5,294 stars, MIT, v4.10.3 released Nov 18), the fast-check.dev parameter docs, Anthropic's Nov 16 verification post, and our own sandbox run of fast-check 4.10.3 on 2026-11-19 against a test app with a bug we planted.

Want help building with tools like this?

Join the Shipping Skool community free. Paid members get live bootcamp calls every week and weekly-updated courses.

Join Shipping Skool

More free guides