fast-check

What is fast-check?

fast-check is a property-based testing library for JavaScript and TypeScript. It allows developers to define properties that should hold true for a wide range of inputs, and then automatically generates test cases to verify those properties. This helps in identifying edge cases and ensuring the robustness of the code.

What are fast-check's main functionalities?

Property-based Testing

This feature allows you to define properties that should hold true for a wide range of inputs. In this example, the property being tested is the commutativity of addition.

const fc = require('fast-check');

fc.assert(
  fc.property(fc.integer(), fc.integer(), (a, b) => {
    return a + b === b + a;
  })
);

Custom Arbitraries

Custom arbitraries allow you to define complex data structures for your tests. In this example, a custom arbitrary is created that generates objects with a number and a string.

const fc = require('fast-check');

const myArbitrary = fc.tuple(fc.integer(), fc.string()).map(([num, str]) => ({ num, str }));

fc.assert(
  fc.property(myArbitrary, ({ num, str }) => {
    return typeof num === 'number' && typeof str === 'string';
  })
);

Shrinkable Values

Shrinkable values help in minimizing the size of failing test cases to make debugging easier. In this example, if the property fails, fast-check will try to find the smallest array that causes the failure.

const fc = require('fast-check');

fc.assert(
  fc.property(fc.array(fc.integer()), (arr) => {
    return arr.length < 100;
  }),
  { verbose: true }
);

Other packages similar to fast-check

jsverify

jsverify is another property-based testing library for JavaScript. It offers similar functionality to fast-check, such as defining properties and generating test cases. However, fast-check is generally considered to have a more modern API and better TypeScript support.

testcheck

testcheck is a property-based testing library inspired by QuickCheck. It provides similar capabilities for generating test cases and defining properties. Compared to fast-check, testcheck is less actively maintained and has fewer features.

hypothesis

Hypothesis is a property-based testing library for Python, but it has inspired several JavaScript libraries, including fast-check. While not a direct competitor, it offers similar concepts and is often used as a reference for property-based testing.

README

Property based testing framework for JavaScript/TypeScript

Getting started

Hands-on tutorial and definition of Property Based Testing: 🏁 see tutorial. Or directly try it online on our pre-configured CodeSandbox.

Property based testing frameworks check the truthfulness of properties. A property is a statement like: for all (x, y, ...) such that precondition(x, y, ...) holds property(x, y, ...) is true.

Install the module with: yarn add fast-check --dev or npm install fast-check --save-dev

Example of integration in mocha:

const fc = require('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);
    }));
  });
});

In case of failure, the test raises a red flag. Its output should help you to diagnose what went wrong in your implementation. Example with a failing implementation of contain:

1) should always contain its substrings
    Error: Property failed after 1 tests (seed: 1527422598337, path: 0:0): ["","",""]
    Shrunk 1 time(s)
    Got error: Property failed by returning false

    Hint: Enable verbose mode in order to have the list of all failing values encountered during the run

Integration with other test frameworks: ava, jasmine, jest, mocha and tape.

More examples: simple examples, fuzzing and against various algorithms.

Useful documentations:

• 🏁 Introduction to Property Based & Hands On
• 🐣 Built-in arbitraries
• 🔧 Custom arbitraries
• 🏃‍♂️ Property based runners
• 💥 Tips
• 🔌 API Reference
• ⭐ Awesome fast-check
• 🤯 How fast-check works?

Why should I migrate to fast-check?

fast-check has initially been designed in an attempt to cope with limitations I encountered while using other property based testing frameworks designed for JavaScript:

• Types: strong and up-to-date types - thanks to TypeScript
• Extendable: easy map method to derive existing arbitraries while keeping shrink [more] - some frameworks ask the user to provide both a->b and b->a mappings in order to keep a shrinker
• Extendable: kind of flatMap-operation called chain [more] - able to bind the output of an arbitrary as input of another one while keeping the shrink working
• Extendable: precondition checks with fc.pre(...) [more] - filtering invalid entries can be done directly inside the check function if needed
• Smart: ability to shrink on fc.oneof [more] - surprisingly some frameworks don't
• Smart: biased by default [more] - by default it generates both small and large values, making it easier to dig into counterexamples without having to tweak a size parameter manually
• Debug: verbose mode [more] - easier troubleshooting with verbose mode enabled
• Debug: replay directly on the minimal counterexample [more] - no need to replay the whole sequence, you get directly the counterexample
• Debug: custom examples in addition of generated ones [more] - no need to duplicate the code to play the property on custom examples
• Debug: logger per predicate run [more] - simplify your troubleshoot with fc.context and its logging feature
• Unique: model based approach [more][article] - use the power of property based testing to test UI, APIs or state machines
• Unique: detect race conditions in your code [more] - shuffle the way your promises and async calls resolve using the power of property based testing to detect races

For more details, refer to the documentation in the links above.

Compatibility

Here are the minimal requirements to use fast-check properly without any polyfills:

fast-check	node	ECMAScript version	TypeScript (optional)
2.x	≥8(1)	ES2017	≥3.2
1.x	≥0.12(1)	ES3	≥3.0

(1) Except for features that cannot be polyfilled - such as bigint-related ones - all the capabilities of fast-check should be usable given you use at least the minimal recommended version of node associated to your major of fast-check.

ReScript bindings

Bindings to use fast-check in ReScript are available in package rescript-fast-check. They are maintained by @TheSpyder as an external project.

Issues found by fast-check in famous packages

fast-check has been able to find some unexpected behaviour among famous npm packages. Here are some of the errors detected using fast-check:

jest

Issue detected: toStrictEqual fails to distinguish 0 from 5e-324 [more]

Code example: expect(0).toStrictEqual(5e-324) succeeds

js-yaml

Issue detected: enabling !!int: binary style when dumping negative integers produces invalid content [more]

Code example: yaml.dump({toto: -10}, {styles:{'!!int':'binary'}}) produces toto: 0b-1010 not toto: -0b1010

query-string

Issue detected: enabling the bracket setting when exporting arrays containing null values produces an invalid output for the parser [more]

Code example:

m.stringify({bar: ['a', null, 'b']}, {arrayFormat: 'bracket'}) //=> "bar[]=a&bar&bar[]=b"
m.parse('bar[]=a&bar&bar[]=b', {arrayFormat: 'bracket'})       //=> {bar: [null, 'b']}

MORE: Issues detected thanks to fast-check

Credits

Code Contributors

This project would not be the same without them 💖 - Become one of them

Backers

Thank you to all our backers! 🙏 [Become a backer] and help us sustain our community.

Sponsors

Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]