Skip to content

dubzzz/fast-check

Repository files navigation

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.