fast-check

<h1 align="center"> <img align="center" src="https://media.githubusercontent.com/media/dubzzz/fast-check/main/website/static/img/logo.png" alt="fast-check logo" /> </h1> <p align="center"> Property based testing framework for JavaScript/TypeScript </p> <p align="center"> <a href="https://github.com/dubzzz/fast-check/actions?query=branch%3Amain+workflow%3A%22Build+Status%22"><img src="https://github.com/dubzzz/fast-check/workflows/Build%20Status/badge.svg?branch=main" alt="Build Status" /></a> <a href="https://badge.fury.io/js/fast-check"><img src="https://badge.fury.io/js/fast-check.svg" alt="npm version" /></a> <a href="https://www.npmjs.com/package/fast-check"><img src="https://img.shields.io/npm/dm/fast-check" alt="monthly downloads" /></a> <a href="https://fast-check.dev/"><img src="https://img.shields.io/badge/-Documentation-%23282ea9.svg" title="Documentation" /></a> </p> <p align="center"> <a href="https://app.codecov.io/gh/dubzzz/fast-check/branch/main"><img src="https://codecov.io/gh/dubzzz/fast-check/branch/main/graph/badge.svg" alt="Coverage Status (unit tests)" /></a> <a href="https://packagequality.com/#?package=fast-check"><img src="https://packagequality.com/shield/fast-check.svg" alt="Package quality" /></a> <a href="https://snyk.io/advisor/npm-package/fast-check"><img src="https://snyk.io/advisor/npm-package/fast-check/badge.svg" alt="Snyk Package quality" /></a> <a href="https://securityscorecards.dev/viewer/?platform=github.com&org=dubzzz&repo=fast-check"><img src="https://api.securityscorecards.dev/projects/github.com/dubzzz/fast-check/badge" alt="OpenSSF Scorecard" /></a> <a href="https://bestpractices.coreinfrastructure.org/projects/7450"><img src="https://bestpractices.coreinfrastructure.org/projects/7450/badge" alt="OpenSSF Best Practices" /></a> </p> <p align="center"> <a href="https://github.com/dubzzz/fast-check/labels/good%20first%20issue"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome" /></a> <a href="https://github.com/dubzzz/fast-check/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/fast-check.svg" alt="License" /></a> <a href="https://twitter.com/intent/tweet?text=Check%20out%20fast-check%20by%20%40ndubien%20https%3A%2F%2Fgithub.com%2Fdubzzz%2Ffast-check%20%F0%9F%91%8D"><img src="https://img.shields.io/twitter/url/https/github.com/dubzzz/fast-check.svg?style=social" alt="Twitter" /></a> </p>

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 predicate(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:

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);
      }),
    );
  });
});

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

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
• Extendable: easily switch from fake data in tests to property based with fc.gen() [more] - generate random values within your predicates
• Smart: ability to shrink on fc.oneof [more] - surprisingly some frameworks don't
• Smart: biased by default - 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][tutorial] - easier troubleshooting with verbose mode enabled
• Debug: replay directly on the minimal counterexample [tutorial] - 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][tutorial] - shuffle the way your promises and async calls resolve using the power of property based testing to detect races
• Unique: simplify user definable corner cases [more] - simplify bug resolution by asking fast-check if it can find an even simpler corner case

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

Trusted

fast-check has been trusted for years by big projects like: jest, jasmine, fp-ts, io-ts, ramda, js-yaml, query-string...

Powerful

It also proved useful in finding bugs among major open source projects such as jest, query-string... and many others.

Compatibility

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

fast-check	node	ECMAScript version	TypeScript (optional)
3.x	≥8<sup>(1)</sup>	ES2017	≥4.1<sup>(2)</sup>
2.x	≥8<sup>(1)</sup>	ES2017	≥3.2<sup>(3)</sup>
1.x	≥0.12<sup>(1)</sup>	ES3	≥3.0<sup>(3)</sup>

<details> <summary>More details...</summary>

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.
2. Require either lib or target ≥ ES2020 or @types/node to be installed.
3. Require either lib or target ≥ ES2015 or @types/node to be installed.

</details>

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.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --> <!-- prettier-ignore-start --> <!-- markdownlint-disable --> <table> <tbody> <tr> <td align="center" valign="top" width="14.28%"><a href="https://github.com/dubzzz"><img src="https://avatars.githubusercontent.com/u/5300235?v=4?s=100" width="100px;" alt="Nicolas DUBIEN"/><br />_{<b>Nicolas DUBIEN</b>}</a><br /><a href="https://github.com/dubzzz/fast-check/commits?author=dubzzz" title="Code">💻</a> <a href="https://github.com/dubzzz/fast-check/commits?author=dubzzz" title="Documentation">📖</a> <a href="https://github.com/dubzzz/fast-check/commits?author=dubzzz" title="Tests">⚠️</a> <a href="#infra-dubzzz" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="#design-dubzzz" title="Design">🎨</a> <a href="#maintenance-dubzzz" title="Maintenance">🚧</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/hath995"><img src="https://avatars.githubusercontent.com/u/381037?v=4?s=100" width="100px;" alt="Aaron Elligsen"/><br />_{<b>Aaron Elligsen</b>}</a><br /><a href="https://github.com/dubzzz/fast-check/commits?author=hath995" title="Code">💻</a> <a href="https://github.com/dubzzz/fast-check/commits?author=hath995" title="Documentation">📖</a> <a href="https://github.com/dubzzz/fast-check/commits?author=hath995" title="Tests">⚠️</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/willheslam"><img src="https://avatars.githubusercontent.com/u/5377213?v=4?s=100" width="100px;" alt="Will Heslam"/><br />_{<b>Will Heslam</b>}</a><br /><a href="https://github.com/dubzzz/fast-check/commits?author=willheslam" title="Documentation">📖</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/kazchimo"><img src="https://avatars.githubusercontent.com/u/31263328?v=4?s=100" width="100px;" alt="kazchimo"/><br />_{<b>kazchimo</b>}</a><br /><a href="https://github.com/dubzzz/fast-check/commits?author=kazchimo" title="Code">💻</a> <a href="https://github.com/dubzzz/fast-check/commits?author=kazchimo" title="Documentation">📖</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/brandon-leapyear"><img src="https://avatars.githubusercontent.com/u/27799541?v=4?s=100" width="100px;" alt="Brandon Chinn"/><br />_{<b>Brandon Chinn</b>}</a><br /><a href="https://github.com/dubzzz/fast-check/commits?author=brandon-leapyear" title="Code">💻</a> <a href="https://github.com/dubzzz/fast-check/commits?author=brandon-leapyear" title="Documentation">📖</a></td> <td align="center" valign="top" width="14.28%"><a href="http://safareli.github.io/resume/"><img src="https://avatars.githubusercontent.com/u/1932383?v=4?s=100" width="100px;" alt="Irakli Safareli"/><br />_{<b>Irakli Safareli</b>}</a><br /><a href="https://github.com/dubzzz/fast-check/commits?author=safareli" title="Documentation">📖</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/TheSpyder"><img src="https://avatars.githubusercontent.com/u/298292?v=4?s=100" width="100px;" alt="Andrew Herron"/><br />_{<b>Andrew Herron</b>}</a><br /><a href="https://github.com/dubzzz/fast-check/commits?author=TheSpyder" title="Documentation">📖</a> <a href="#plugin-TheSpyder" title="Plugin/utility libraries">🔌</a></td>