fast-check
TypeScript icon, indicating that this package has built-in type declarations

3.17.2 • Public • Published

fast-check logo

Property based testing framework for JavaScript/TypeScript

Build Status npm version monthly downloads

Coverage Status (unit tests) Package quality Snyk Package quality OpenSSF Scorecard OpenSSF Best Practices

PRs Welcome License Twitter

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:

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(1) ES2017 ≥4.1(2)
2.x ≥8(1) ES2017 ≥3.2(3)
1.x ≥0.12(1) ES3 ≥3.0(3)
More details...
  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.

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):

Nicolas DUBIEN
Nicolas DUBIEN

💻 📖 ⚠️ 🚇 🎨 🚧
Aaron Elligsen
Aaron Elligsen

💻 📖 ⚠️
Will Heslam
Will Heslam

📖
kazchimo
kazchimo

💻 📖
Brandon Chinn
Brandon Chinn

💻 📖
Irakli Safareli
Irakli Safareli

📖
Andrew Herron
Andrew Herron

📖 🔌
Eric Crosson
Eric Crosson

📖 💻
burrscurr
burrscurr

📖
JC (Jonathan Chen)
JC (Jonathan Chen)

📖
Larry Botha
Larry Botha

📖 💻 ⚠️
Roman Gusev
Roman Gusev

📖
Tim Wisniewski
Tim Wisniewski

📖
Brais Piñeiro
Brais Piñeiro

💻 ⚠️
Renaud-Pierre Bordes
Renaud-Pierre Bordes

🎨
Jemma Nelson
Jemma Nelson

📖
John Haugeland
John Haugeland

📖
Trey Davis
Trey Davis

🎨
Leon Si
Leon Si

📖
Gorgi Kosev
Gorgi Kosev

🚇
mayconsacht
mayconsacht

💻
Simon Friis Vindum
Simon Friis Vindum

💻 ⚠️
Richard Gibson
Richard Gibson

📖
Alan Harper
Alan Harper

📖
Makien Osman
Makien Osman

💻
David Sommerich
David Sommerich

💻 ⚠️
Diego Pedro
Diego Pedro

💻 ⚠️
Borui Gu
Borui Gu

📖
Brian Donovan
Brian Donovan

📖
volrk
volrk

💻 📖 ⚠️
tinydylan
tinydylan

💻 ⚠️
Caleb Jasik
Caleb Jasik

📖
Rulai Hu
Rulai Hu

📖
Afonso Jorge Ramos
Afonso Jorge Ramos

📖
Tom Jenkinson
Tom Jenkinson

📖
phormio
phormio

📖
Giovanni Gonzaga
Giovanni Gonzaga

💻 ⚠️
Tomas Carnecky
Tomas Carnecky

💻
Kirill Romanov
Kirill Romanov

💻 📖 ⚠️
Giovanny González
Giovanny González

📖
Mark Kulube
Mark Kulube

🚇
Peter Hamilton
Peter Hamilton

💻
Chinedu Ozodi
Chinedu Ozodi

📖
Gunar Gessner
Gunar Gessner

📖
Christian Batchelor
Christian Batchelor

⚠️
Tomer Aberbach
Tomer Aberbach

💻 📖 ⚠️
0xflotus
0xflotus

📖
Ryan Leonard
Ryan Leonard

💻 📖 ⚠️
Jason Dreyzehner
Jason Dreyzehner

💻 ⚠️
Matin Zadeh Dolatabad
Matin Zadeh Dolatabad

💻
Juan Julián Merelo Guervós
Juan Julián Merelo Guervós

📖
Simen Bekkhus
Simen Bekkhus

📖
Tarjei Skjærset
Tarjei Skjærset

📖
Denis Gorbachev
Denis Gorbachev

📖
Trevor McCauley
Trevor McCauley

📖
Grant Kiely
Grant Kiely

📖
Attila Večerek
Attila Večerek

💻 📖 ⚠️
Zach Bjornson
Zach Bjornson

💻 📖
Bennett Perkins
Bennett Perkins

📖
Alexandre Oger
Alexandre Oger

📖
ej shafran
ej shafran

📖
Niklas Gruhn
Niklas Gruhn

💻
Patrick Roza
Patrick Roza

💻

This project follows the all-contributors specification. Contributions of any kind welcome! Become one of them

Sponsors 💸

Many individuals and companies offer their financial support to the project, a huge thanks to all of them too 💓

all sponsors

You can also become one of them by contributing via GitHub Sponsors or OpenCollective.

Package Sidebar

Install

npm i fast-check

Weekly Downloads

640,803

Version

3.17.2

License

MIT

Unpacked Size

1.21 MB

Total Files

894

Last publish

Collaborators

  • ndubien