Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/dubzzz/fast-check

Property based testing framework for JavaScript (like QuickCheck) written in TypeScript
https://github.com/dubzzz/fast-check

faker fuzzing generative-testing property-based-testing quickcheck tdd testing typescript unit-testing

Last synced: 5 days ago
JSON representation

Property based testing framework for JavaScript (like QuickCheck) written in TypeScript

Host: GitHub
URL: https://github.com/dubzzz/fast-check
Owner: dubzzz
License: mit
Created: 2017-10-30T23:41:11.000Z (about 7 years ago)
Default Branch: main
Last Pushed: 2024-10-29T08:33:49.000Z (3 months ago)
Last Synced: 2024-10-29T09:23:42.852Z (3 months ago)
Topics: faker, fuzzing, generative-testing, property-based-testing, quickcheck, tdd, testing, typescript, unit-testing
Language: TypeScript
Homepage: https://fast-check.dev/
Size: 40 MB
Stars: 4,327
Watchers: 19
Forks: 180
Open Issues: 69
Metadata Files:
- Readme: .github/README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md

Awesome Lists containing this project

awesome-list - fast-check
awesome-javascript - @fast-check/monorepo
awesome-javascript - @fast-check/monorepo

README

        


  





Property based testing framework for JavaScript/TypeScript





  

  

  

  





  

  

  

  

  





  

  



## Getting started

Hands-on tutorial and definition of Property Based Testing: [🏁 see tutorial](https://fast-check.dev/docs/tutorials/quick-start/). Or directly try it online on our pre-configured [CodeSandbox](https://codesandbox.io/s/github/dubzzz/fast-check/tree/main/examples?previewwindow=tests).

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](http://mochajs.org/):

```js

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](https://github.com/dubzzz/fast-check-examples/blob/main/test-ava/example.spec.js), [jasmine](https://github.com/dubzzz/fast-check-examples/blob/main/test-jasmine/example.spec.js), [jest](https://github.com/dubzzz/fast-check-examples/blob/main/test-jest/example.spec.js), [mocha](https://github.com/dubzzz/fast-check-examples/blob/main/test/longest%20common%20substr/test.js) and [tape](https://github.com/dubzzz/fast-check-examples/blob/main/test-tape/example.spec.js).

More examples: [simple examples](https://github.com/dubzzz/fast-check/tree/main/examples), [fuzzing](https://github.com/dubzzz/fuzz-rest-api) and [against various algorithms](https://github.com/dubzzz/fast-check-examples).

Useful documentations:

- [🏁 Introduction to Property Based & Hands On](https://fast-check.dev/docs/tutorials/quick-start/)

- [🐣 Built-in arbitraries](https://fast-check.dev/docs/core-blocks/arbitraries/)

- [🔧 Custom arbitraries](https://fast-check.dev/docs/core-blocks/arbitraries/combiners/)

- [🏃‍♂️ Property based runners](https://fast-check.dev/docs/core-blocks/runners/)

- [💥 Tips](https://fast-check.dev/docs/configuration/)

- [🔌 API Reference](https://fast-check.dev/api-reference/index.html)

- [⭐ Awesome fast-check](https://fast-check.dev/docs/ecosystem/)

## 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](https://fast-check.dev/docs/core-blocks/arbitraries/combiners/any/#map)\] - _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](https://fast-check.dev/docs/core-blocks/arbitraries/combiners/any/#chain)\] - _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](https://fast-check.dev/docs/core-blocks/properties/#example)\] - _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](https://fast-check.dev/docs/core-blocks/arbitraries/others/#gen)\] - _generate random values within your predicates_

- **Smart:** ability to shrink on `fc.oneof` \[[more](https://fast-check.dev/docs/core-blocks/arbitraries/combiners/any/#oneof)\] - _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](https://fast-check.dev/docs/configuration/custom-reports/#verbosity)\]\[[tutorial](https://fast-check.dev/docs/tutorials/quick-start/read-test-reports/#how-to-increase-verbosity)\] - _easier troubleshooting with verbose mode enabled_

- **Debug:** replay directly on the minimal counterexample \[[tutorial](https://fast-check.dev/docs/tutorials/quick-start/read-test-reports/#how-to-re-run)\] - _no need to replay the whole sequence, you get directly the counterexample_

- **Debug:** custom examples in addition of generated ones \[[more](https://fast-check.dev/docs/configuration/user-definable-values/#run-against-custom-values)\] - _no need to duplicate the code to play the property on custom examples_

- **Debug:** logger per predicate run \[[more](https://fast-check.dev/docs/core-blocks/arbitraries/others/#context)\] - _simplify your troubleshoot with fc.context and its logging feature_

- **Unique:** model based approach \[[more](https://fast-check.dev/docs/advanced/model-based-testing/)\]\[[article](https://medium.com/criteo-labs/detecting-the-unexpected-in-web-ui-fuzzing-1f3822c8a3a5)\] - _use the power of property based testing to test UI, APIs or state machines_

- **Unique:** detect race conditions in your code \[[more](https://fast-check.dev/docs/advanced/race-conditions/)\]\[[tutorial](https://fast-check.dev/docs/tutorials/detect-race-conditions/)\] - _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](https://fast-check.dev/docs/configuration/user-definable-values/#shrink-custom-values)\] - _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](https://github.com/jestjs/jest), [jasmine](https://github.com/jasmine/jasmine), [fp-ts](https://github.com/gcanti/fp-ts), [io-ts](https://github.com/gcanti/io-ts), [ramda](https://github.com/ramda/ramda), [js-yaml](https://github.com/nodeca/js-yaml), [query-string](https://github.com/sindresorhus/query-string)...

### Powerful

It also proved useful in finding bugs among major open source projects such as [jest](https://github.com/jestjs/jest), [query-string](https://github.com/sindresorhus/query-string)... and [many others](https://fast-check.dev/docs/introduction/track-record/).

## Compatibility

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

| fast-check | node                | ECMAScript version | _TypeScript (optional)_ |

| ---------- | ------------------- | ------------------ | ----------------------- |

| **4.x**    | ≥10.5.0             | ES2020             | ≥5.0                    |

| **3.x**    | ≥8⁽¹⁾    | ES2017             | ≥4.1⁽²⁾      |

| **2.x**    | ≥8⁽¹⁾    | ES2017             | ≥3.2⁽³⁾      |

| **1.x**    | ≥0.12⁽¹⁾ | ES3                | ≥3.0⁽³⁾      |

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](https://rescript-lang.org) are available in package [rescript-fast-check](https://www.npmjs.com/rescript-fast-check). They are maintained by [@TheSpyder](https://github.com/TheSpyder) as an external project.

## Contributors ✨

Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

  

    

      
_{Nicolas DUBIEN}
💻 📖 ⚠️ 🚇 🎨 🚧

      
_{Aaron Elligsen}
💻 📖 ⚠️

      
_{Will Heslam}
📖

      
_kazchimo
💻 📖

      
_{Brandon Chinn}
💻 📖

      
_{Irakli Safareli}
📖

      
_{Andrew Herron}
📖 🔌

    

    

      
_{Eric Crosson}
📖 💻

      
_burrscurr
📖

      
_{JC (Jonathan Chen)}
📖

      
_{Larry Botha}
📖 💻 ⚠️

      
_{Roman Gusev}
📖

      
_{Tim Wisniewski}
📖

      
_{Brais Piñeiro}
💻 ⚠️

    

    

      
_{Renaud-Pierre Bordes}
🎨

      
_{Jemma Nelson}
📖

      
_{John Haugeland}
📖

      
_{Trey Davis}
🎨

      
_{Leon Si}
📖

      
_{Gorgi Kosev}
🚇

      
_mayconsacht
💻

    

    

      
_{Simon Friis Vindum}
💻 ⚠️

      
_{Richard Gibson}
📖

      
_{Alan Harper}
📖

      
_{Makien Osman}
💻

      
_{David Sommerich}
💻 ⚠️

      
_{Diego Pedro}
💻 ⚠️

      
_{Borui Gu}
📖

    

    

      
_{Brian Donovan}
📖

      
_volrk
💻 📖 ⚠️

      
_tinydylan
💻 ⚠️

      
_{Caleb Jasik}
📖

      
_{Rulai Hu}
📖

      
_{Afonso Jorge Ramos}
📖

      
_{Tom Jenkinson}
📖

    

    

      
_phormio
📖

      
_{Giovanni Gonzaga}
💻 ⚠️

      
_{Tomas Carnecky}
💻

      
_{Kirill Romanov}
💻 📖 ⚠️

      
_{Giovanny González}
📖

      
_{Mark Kulube}
🚇

      
_{Peter Hamilton}
💻

    

    

      
_{Chinedu Ozodi}
📖

      
_{Gunar Gessner}
📖

      
_{Christian Batchelor}
⚠️

      
_{Tomer Aberbach}
💻 📖 ⚠️

      
_0xflotus
📖

      
_{Ryan Leonard}
💻 📖 ⚠️

      
_{Jason Dreyzehner}
💻 ⚠️

    

    

      
_{Matin Zadeh Dolatabad}
💻

      
_{Juan Julián Merelo Guervós}
📖

      
_{Simen Bekkhus}
📖

      
_{Tarjei Skjærset}
📖

      
_{Denis Gorbachev}
📖

      
_{Trevor McCauley}
📖

      
_{Grant Kiely}
📖

    

    

      
_{Attila Večerek}
💻 📖 ⚠️

      
_{Zach Bjornson}
💻 📖

      
_{Bennett Perkins}
📖

      
_{Alexandre Oger}
📖

      
_{ej shafran}
📖

      
_{Niklas Gruhn}
💻

      
_{Patrick Roza}
💻

    

    

      
_{Cindy Wu}
📖

      
_Noah
📖

      
_{James Vaughan}
📖

    

  

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! [Become one of them](CONTRIBUTING.md)

## Sponsors 💸

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



You can also become one of them by contributing via [GitHub Sponsors](https://github.com/sponsors/dubzzz) or [OpenCollective](https://opencollective.com/fast-check/contribute).