Property-Based Testing for JavaScript/TypeScript

4.7.0 · active · verified Sun Apr 19

fast-check is a property-based testing framework for JavaScript and TypeScript, inspired by Haskell's QuickCheck. It enables developers to define properties about their code and automatically generates diverse inputs to test these properties, identifying edge cases that traditional example-based testing might miss. The current stable version is 4.7.0. The project maintains an active release cadence, with continuous development across its core library and various test runner integrations. Key differentiators include its robust shrinking capabilities, which minimize counterexamples to help pinpoint bugs, an extensive set of built-in arbitrary data generators, and comprehensive TypeScript support. It integrates seamlessly with popular testing frameworks like Mocha, Jest, Vitest, and Ava via dedicated adapter packages, though users should be aware of recent changes in module support for these adapters.

Common errors

```
Error: Property failed by returning false
```
cause A property's predicate function returned `false` for a generated input, indicating a bug in the code under test or the property definition.

fix Review the counterexample provided in the test output (the shrunken inputs) to debug your implementation or refine your property's preconditions.
```
SyntaxError: Cannot use import statement outside a module
```
cause Attempting to use ES module `import` syntax in a CommonJS context, especially common when using ESM-only adapter packages like `@fast-check/vitest`.

fix Ensure your file is treated as an ES module (e.g., by using `.mjs` extension, or setting `"type": "module"` in `package.json`) or migrate to using `require()` if the package still supports CJS and you must use CJS.

Warnings

breaking Several adapter packages (e.g., `@fast-check/worker`, `@fast-check/vitest`, `@fast-check/poisoning`, `@fast-check/packaged`, `@fast-check/ava`) have dropped CommonJS support and are now ESM-only. If you are using these integrations, you must update your project to use ES modules (`import`/`export`).
Fix: Migrate your project to use ES module syntax (e.g., `import { test } from '@fast-check/vitest';`) and ensure your Node.js environment is configured for ESM.
deprecated The methods `Random::next(n)` and `Random::nextInt()` have been deprecated. Users should migrate to newer alternatives for random number generation.
Fix: Consult the fast-check documentation for the recommended alternatives to `Random::next(n)` and `Random::nextInt()`.
gotcha While the core `fast-check` package in the 4.x series still supports CommonJS (`require()`), many of its ecosystem adapter packages (e.g., for Vitest, Ava, Workers) have moved to ESM-only. This can lead to module resolution issues if mixing CommonJS for `fast-check` and ESM-only adapters.
Fix: For consistency and to avoid module conflicts, it is recommended to use ESM throughout your project when integrating with the latest versions of fast-check adapter packages.

Install

npm install fast-check npm
yarn add fast-check yarn
pnpm add fast-check pnpm

Imports

fc
wrong:
```
const fc = require('fast-check').default;
```
correct:
```
import fc from 'fast-check';
```
The primary way to import the main library. While fast-check itself supports both ESM and CJS in v4, many of its adapter packages are ESM-only.
assert
wrong:
```
import fc, { assert, property } from 'fast-check';
```
correct:
```
import { assert, property, string } from 'fast-check';
```
`assert` and `property` are named exports for core testing logic, typically used alongside `fc`'s default export.
test
wrong:
```
const { test } = require('@fast-check/vitest');
```
correct:
```
import { test } from '@fast-check/vitest';
```
Adapter packages like `@fast-check/vitest` (and `@fast-check/worker`, etc.) are ESM-only since their v0.3.0+ (or equivalent) releases.

Quickstart

Demonstrates a basic integration of fast-check with Mocha, defining and asserting properties using arbitrary string generation.

import fc from 'fast-check';

// Code under test
const contains = (text, pattern) => text.indexOf(pattern) >= 0;

// Properties
describe('properties', () => {
  // string text always contains itself
  it('should always contain itself', () => {
    fc.assert(fc.property(fc.string(), (text) => contains(text, text)));
  });
  // string a + b + c always contains b, whatever the values of a, b and c
  it('should always contain its substrings', () => {
    fc.assert(
      fc.property(fc.string(), fc.string(), fc.string(), (a, b, c) => {
        // Alternatively: no return statement and direct usage of expect or assert
        return contains(a + b + c, b);
      }),
    );
  });
});

view raw JSON →