fast-check

Use this symbol to define a custom serializer for your instances. Serializer must be a function returning a promise of string (see WithAsyncToStringMethod).

Please note that: 1. It will only be useful for asynchronous properties. 2. It has to return barely instantly.

Remarks

Since 2.17.0

Generated instances having a method [cloneMethod] will be automatically cloned whenever necessary

This is pretty useful for statefull generated values. For instance, whenever you use a Stream you directly impact it. Implementing [cloneMethod] on the generated Stream would force the framework to clone it whenever it has to re-use it (mainly required for chrinking process)

Remarks

Since 1.8.0

Use this symbol to define a custom serializer for your instances. Serializer must be a function returning a string (see WithToStringMethod).

Remarks

Since 2.17.0

For any type of values

You may use sample to preview the values that will be generated

Remarks

Since 0.0.7

Example 1

null, undefined, 42, 6.5, 'Hello', {}, {k: [{}, 1, 2]}

For any type of values following the constraints defined by settings

You may use sample to preview the values that will be generated

Parameter constraints

Constraints to apply when building instances

Remarks

Since 0.0.7

Example 1

null, undefined, 42, 6.5, 'Hello', {}, {k: [{}, 1, 2]}

Example 2

// Using custom settings
fc.anything({
    key: fc.char(),
    values: [fc.integer(10,20), fc.constant(42)],
    maxDepth: 2
});
// Can build entries such as:
// - 19
// - [{"2":12,"k":15,"A":42}]
// - {"4":[19,13,14,14,42,11,20,11],"6":42,"7":16,"L":10,"'":[20,11],"e":[42,20,42,14,13,17]}
// - [42,42,42]...

For arrays of values coming from arb

Parameter arb

Arbitrary used to generate the values inside the array

Parameter constraints

Constraints to apply when building instances (since 2.4.0)

Remarks

Since 0.0.1

For single ascii characters - char code between 0x00 (included) and 0x7f (included)

Remarks

Since 0.0.1

For strings of ascii

Parameter constraints

Constraints to apply when building instances (since 2.4.0)

Remarks

Since 0.0.1

Run the property, throw in case of failure

It can be called directly from describe/it blocks of Mocha. No meaningful results are produced in case of success.

WARNING: Has to be awaited

Parameter property

Asynchronous property to be checked

Parameter params

Optional parameters to customize the execution

Remarks

Since 0.0.7

Run the property, throw in case of failure

It can be called directly from describe/it blocks of Mocha. No meaningful results are produced in case of success.

Parameter property

Synchronous property to be checked

Parameter params

Optional parameters to customize the execution

Remarks

Since 0.0.1

Run the property, throw in case of failure

It can be called directly from describe/it blocks of Mocha. No meaningful results are produced in case of success.

WARNING: Returns a promise to be awaited if the property is asynchronous

Parameter property

Synchronous or asynchronous property to be checked

Parameter params

Optional parameters to customize the execution

Remarks

Since 0.0.7

Format output of check using the default error reporting of assert

Produce a string containing the formated error in case of failed run, undefined otherwise.

Remarks

Since 2.17.0

Run asynchronous commands over a Model and the Real system

Throw in case of inconsistency

Parameter s

Initial state provider

Parameter cmds

Asynchronous commands to be executed

Remarks

Since 1.5.0

Instantiate a new fast-check#IAsyncProperty

Parameter predicate

Assess the success of the property. Would be considered falsy if it throws or if its output evaluates to false

Remarks

Since 0.0.7

Convert any value to its fast-check string representation

This asynchronous version is also able to dig into the status of Promise

Parameter value

Value to be converted into a string

Remarks

Since 2.17.0

For single base64 characters - A-Z, a-z, 0-9, + or /

Remarks

Since 0.0.1

For base64 strings

A base64 string will always have a length multiple of 4 (padded with =)

Parameter constraints

Constraints to apply when building instances (since 2.4.0)

Remarks

Since 0.0.1

For bigint

Remarks

Since 1.9.0

For bigint between min (included) and max (included)

Parameter min

Lower bound for the generated bigints (eg.: -5n, 0n, BigInt(Number.MIN_SAFE_INTEGER))

Parameter max

Upper bound for the generated bigints (eg.: -2n, 2147483647n, BigInt(Number.MAX_SAFE_INTEGER))

Remarks

Since 1.9.0

For bigint between min (included) and max (included)

Parameter constraints

Constraints to apply when building instances

Remarks

Since 2.6.0

For BigInt64Array

Remarks

Since 3.0.0

For signed bigint of n bits

Generated values will be between -2^(n-1) (included) and 2^(n-1) (excluded)

Parameter n

Maximal number of bits of the generated bigint

Remarks

Since 1.9.0

For positive bigint

Remarks

Since 1.9.0

For positive bigint between 0 (included) and max (included)

Parameter max

Upper bound for the generated bigint

Remarks

Since 1.9.0

For positive bigint between 0 (included) and max (included)

Parameter constraints

Constraints to apply when building instances

Remarks

Since 2.6.0

For BigUint64Array

Remarks

Since 3.0.0

For unsigned bigint of n bits

Generated values will be between 0 (included) and 2^n (excluded)

Parameter n

Maximal number of bits of the generated bigint

Remarks

Since 1.9.0

For boolean values - true or false

Remarks

Since 0.0.6

For single printable ascii characters - char code between 0x20 (included) and 0x7e (included)

https://www.ascii-code.com/

Remarks

Since 0.0.1

For single characters - all values in 0x0000-0xffff can be generated

WARNING:

Some generated characters might appear invalid regarding UCS-2 and UTF-16 encoding. Indeed values within 0xd800 and 0xdfff constitute surrogate pair characters and are illegal without their paired character.

Remarks

Since 0.0.11

Run the property, do not throw contrary to assert

WARNING: Has to be awaited

Parameter property

Asynchronous property to be checked

Parameter params

Optional parameters to customize the execution

Returns

Test status and other useful details

Remarks

Since 0.0.7

Run the property, do not throw contrary to assert

Parameter property

Synchronous property to be checked

Parameter params

Optional parameters to customize the execution

Returns

Test status and other useful details

Remarks

Since 0.0.1

Run the property, do not throw contrary to assert

WARNING: Has to be awaited if the property is asynchronous

Parameter property

Property to be checked

Parameter params

Optional parameters to customize the execution

Returns

Test status and other useful details

Remarks

Since 0.0.7

Clone the values generated by arb in order to produce fully equal values (might not be equal in terms of === or ==)

Parameter arb

Source arbitrary

Parameter numValues

Number of values to produce

Remarks

Since 2.5.0

Clone an instance if needed

Remarks

Since 2.15.0

For arrays of AsyncCommand to be executed by asyncModelRun

This implementation comes with a shrinker adapted for commands. It should shrink more efficiently than array for AsyncCommand arrays.

Parameter commandArbs

Arbitraries responsible to build commands

Parameter constraints

Constraints to be applied when generating the commands (since 1.11.0)

Remarks

Since 1.5.0

For arrays of Command to be executed by modelRun

This implementation comes with a shrinker adapted for commands. It should shrink more efficiently than array for Command arrays.

Parameter commandArbs

Arbitraries responsible to build commands

Parameter constraints

Constraints to be applied when generating the commands (since 1.11.0)

Remarks

Since 1.5.0

For comparison boolean functions

A comparison boolean function returns: - true whenever a < b - false otherwise (ie. a = b or a > b)

Remarks

Since 1.6.0

For comparison functions

A comparison function returns: - negative value whenever a < b - positive value whenever a > b - zero whenever a and b are equivalent

Comparison functions are transitive: a < b and b < c => a < c

They also satisfy: a < b <=> b > a and a = b <=> b = a

Remarks

Since 1.6.0

Define global parameters that will be used by all the runners

Parameter parameters

Global parameters

Remarks

Since 1.18.0

Example 1

fc.configureGlobal({ numRuns: 10 });
//...
fc.assert(
  fc.property(
    fc.nat(), fc.nat(),
    (a, b) => a + b === b + a
  ), { seed: 42 }
) // equivalent to { numRuns: 10, seed: 42 }

For value

Parameter value

The value to produce

Remarks

Since 0.0.1

For one ...values values - all equiprobable

**WARNING**: It expects at least one value, otherwise it should throw

Parameter values

Constant values to be produced (all values shrink to the first one)

Remarks

Since 0.0.12

Produce a ContextValue instance

Remarks

Since 1.8.0

Create a new and unique instance of DepthIdentifier that can be shared across multiple arbitraries if needed

For date between constraints.min or new Date(-8640000000000000) (included) and constraints.max or new Date(8640000000000000) (included)

Parameter constraints

Constraints to apply when building instances

Remarks

Since 1.17.0

Format output of check using the default error reporting of assert

Produce a string containing the formated error in case of failed run, undefined otherwise.

Remarks

Since 1.25.0

For dictionaries with keys produced by keyArb and values from valueArb

Parameter keyArb

Arbitrary used to generate the keys of the object

Parameter valueArb

Arbitrary used to generate the values of the object

Remarks

Since 1.0.0

For domains having an extension with at least two lowercase characters

According to RFC 1034, RFC 1035, RFC 1123 and WHATWG URL Standard

Parameter constraints

Constraints to apply when building instances (since 2.22.0)

Remarks

Since 1.14.0

For 64-bit floating point numbers: - sign: 1 bit - significand: 52 bits - exponent: 11 bits

Parameter constraints

Constraints to apply when building instances (since 2.8.0)

Remarks

Since 0.0.6

For email address

According to RFC 2821, RFC 3696 and RFC 5322

Parameter constraints

Constraints to apply when building instances (since 2.22.0)

Remarks

Since 1.14.0

For falsy values: - '' - 0 - NaN - false - null - undefined - 0n (whenever withBigInt: true)

Parameter constraints

Constraints to apply when building instances

Remarks

Since 1.26.0

For 32-bit floating point numbers: - sign: 1 bit - significand: 23 bits - exponent: 8 bits

The smallest non-zero value (in absolute value) that can be represented by such float is: 2 ** -126 * 2 ** -23. And the largest one is: 2 ** 127 * (1 + (2 ** 23 - 1) / 2 ** 23).

Parameter constraints

Constraints to apply when building instances (since 2.8.0)

Remarks

Since 0.0.6

For Float32Array

Remarks

Since 2.9.0

For Float64Array

Remarks

Since 2.9.0

For single unicode characters - any of the code points defined in the unicode standard

WARNING: Generated values can have a length greater than 1.

https://tc39.github.io/ecma262/#sec-utf16encoding

Remarks

Since 0.0.11

For strings of fullUnicode

Parameter constraints

Constraints to apply when building instances (since 2.4.0)

Remarks

Since 0.0.11

For pure functions

Parameter arb

Arbitrary responsible to produce the values

Remarks

Since 1.6.0

Generate values within the test execution itself by leveraging the strength of gen

Remarks

Since 3.8.0

Example 1

fc.assert(
  fc.property(fc.gen(), gen => {
    const size = gen(fc.nat, {max: 10});
    const array = [];
    for (let index = 0 ; index !== size ; ++index) {
      array.push(gen(fc.integer));
    }
    // Here is an array!
    // Note: Prefer fc.array(fc.integer(), {maxLength: 10}) if you want to produce such array
  })
)

⚠️ WARNING: While gen is easy to use, it may not shrink as well as tailored arbitraries based on filter or map.

⚠️ WARNING: Additionally it cannot run back the test properly when attempting to replay based on a seed and a path. You'll need to limit yourself to the seed and drop the path from the options if you attempt to replay something implying it. More precisely, you may keep the very first part of the path but have to drop anything after the first ":".

⚠️ WARNING: It also does not support custom examples.

Get back the requested DepthContext

Remarks

Since 2.25.0

Check if an instance implements WithAsyncToStringMethod

Remarks

Since 2.17.0

Check if an instance has to be clone

Remarks

Since 2.15.0

CRC-32 based hash function

Used internally by fast-check in func, compareFunc or even compareBooleanFunc.

Parameter repr

String value to be hashed

Remarks

Since 2.1.0

Check if an instance implements WithToStringMethod

Remarks

Since 2.17.0

For single hexadecimal characters - 0-9 or a-f

Remarks

Since 0.0.1

For strings of hexa

Parameter constraints

Constraints to apply when building instances (since 2.4.0)

Remarks

Since 0.0.1

Produce an infinite stream of values

WARNING: Requires Object.assign

Parameter arb

Arbitrary used to generate the values

Remarks

Since 1.8.0

For Int16Array

Remarks

Since 2.9.0

For Int32Array

Remarks

Since 2.9.0

For Int8Array

Remarks

Since 2.9.0

For integers between min (included) and max (included)

Parameter constraints

Constraints to apply when building instances (since 2.6.0)

Remarks

Since 0.0.1

For valid IP v4

Following RFC 3986

Remarks

Since 1.14.0

For valid IP v4 according to WhatWG

Following WhatWG, the specification for web-browsers

There is no equivalent for IP v6 according to the IP v6 parser

Remarks

Since 1.17.0

For valid IP v6

Following RFC 3986

Remarks

Since 1.14.0

For any JSON strings

Keys and string values rely on string

Parameter constraints

Constraints to be applied onto the generated instance (since 2.5.0)

Remarks

Since 0.0.7

For any JSON compliant values

Keys and string values rely on string

As JSON.parse preserves -0, jsonValue can also have -0 as a value. jsonValue must be seen as: any value that could have been built by doing a JSON.parse on a given string.

Parameter constraints

Constraints to be applied onto the generated instance

Remarks

Since 2.20.0

For mutually recursive types

Parameter builder

Arbitraries builder based on themselves (through tie)

Remarks

Since 1.16.0

Example 1

type Leaf = number;
type Node = [Tree, Tree];
type Tree = Node | Leaf;
const { tree } = fc.letrec<{ tree: Tree, node: Node, leaf: Leaf }>(tie => ({
  tree: fc.oneof({depthSize: 'small'}, tie('leaf'), tie('node')),
  node: fc.tuple(tie('tree'), tie('tree')),
  leaf: fc.nat()
}));
// tree is 50% of node, 50% of leaf
// the ratio goes in favor of leaves as we go deeper in the tree (thanks to depthSize)

For mutually recursive types

Parameter builder

Arbitraries builder based on themselves (through tie)

Remarks

Since 1.16.0

Example 1

const { tree } = fc.letrec(tie => ({
  tree: fc.oneof({depthSize: 'small'}, tie('leaf'), tie('node')),
  node: fc.tuple(tie('tree'), tie('tree')),
  leaf: fc.nat()
}));
// tree is 50% of node, 50% of leaf
// the ratio goes in favor of leaves as we go deeper in the tree (thanks to depthSize)

For lorem ipsum string of words or sentences with maximal number of words or sentences

Parameter constraints

Constraints to be applied onto the generated value (since 2.5.0)

Remarks

Since 0.0.1

Generate non-contiguous ranges of values by mapping integer values to constant

Parameter options

Builders to be called to generate the values

Remarks

Since 1.14.0

Example 1

// generate alphanumeric values (a-z0-9)
mapToConstant(
  { num: 26, build: v => String.fromCharCode(v + 0x61) },
  { num: 10, build: v => String.fromCharCode(v + 0x30) },
)

For integers between Number.MIN_SAFE_INTEGER (included) and Number.MAX_SAFE_INTEGER (included)

Remarks

Since 1.11.0

For positive integers between 0 (included) and Number.MAX_SAFE_INTEGER (included)

Remarks

Since 1.11.0

For mutually recursive types

Parameter builder

Arbitrary builder taken the maximal depth allowed as input (parameter n)

Remarks

Since 1.16.0

Example 1

// tree is 1 / 3 of node, 2 / 3 of leaf
const tree: fc.Memo<Tree> = fc.memo(n => fc.oneof(node(n), leaf(), leaf()));
const node: fc.Memo<Tree> = fc.memo(n => {
  if (n <= 1) return fc.record({ left: leaf(), right: leaf() });
  return fc.record({ left: tree(), right: tree() }); // tree() is equivalent to tree(n-1)
});
const leaf = fc.nat;

Randomly switch the case of characters generated by stringArb (upper/lower)

WARNING: Require bigint support. Under-the-hood the arbitrary relies on bigint to compute the flags that should be toggled or not.

Parameter stringArb

Arbitrary able to build string values

Parameter constraints

Constraints to be applied when computing upper/lower case version

Remarks

Since 1.17.0

Run synchronous commands over a Model and the Real system

Throw in case of inconsistency

Parameter s

Initial state provider

Parameter cmds

Synchronous commands to be executed

Remarks

Since 1.5.0

For positive integers between 0 (included) and 2147483647 (included)

Remarks

Since 0.0.1

For positive integers between 0 (included) and max (included)

Parameter max

Upper bound for the generated integers

Remarks

Since 0.0.1

For positive integers between 0 (included) and max (included)

Parameter constraints

Constraints to apply when building instances

Remarks

Since 2.6.0

For any objects

You may use sample to preview the values that will be generated

Remarks

Since 0.0.7

Example 1

{}, {k: [{}, 1, 2]}

For any objects following the constraints defined by settings

You may use sample to preview the values that will be generated

Parameter constraints

Constraints to apply when building instances

Remarks

Since 0.0.7

Example 1

{}, {k: [{}, 1, 2]}

For one of the values generated by ...arbs - with all ...arbs equiprobable

**WARNING**: It expects at least one arbitrary

Parameter arbs

Arbitraries that might be called to produce a value

Remarks

Since 0.0.1

For one of the values generated by ...arbs - with all ...arbs equiprobable

**WARNING**: It expects at least one arbitrary

Parameter constraints

Constraints to be applied when generating the values

Parameter arbs

Arbitraries that might be called to produce a value

Remarks

Since 2.14.0

For either nil or a value coming from arb with custom frequency

Parameter arb

Arbitrary that will be called to generate a non nil value

Parameter constraints

Constraints on the option(since 1.17.0)

Remarks

Since 0.0.6

Add pre-condition checks inside a property execution

Parameter expectTruthy

cancel the run whenever this value is falsy

Remarks

Since 1.3.0

Instantiate a new fast-check#IProperty

Parameter predicate

Assess the success of the property. Would be considered falsy if it throws or if its output evaluates to false

Remarks

Since 0.0.1

Read global parameters that will be used by runners

Remarks

Since 1.18.0

For records following the recordModel schema

Parameter recordModel

Schema of the record

Remarks

Since 0.0.12

Example 1

record({ x: someArbitraryInt, y: someArbitraryInt }): Arbitrary<{x:number,y:number}>
// merge two integer arbitraries to produce a {x, y} record

For records following the recordModel schema

Parameter recordModel

Schema of the record

Parameter constraints

Contraints on the generated record

Remarks

Since 0.0.12

Example 1

record({ x: someArbitraryInt, y: someArbitraryInt }, {withDeletedKeys: true}): Arbitrary<{x?:number,y?:number}>
// merge two integer arbitraries to produce a {x, y}, {x}, {y} or {} record

Reset global parameters

Remarks

Since 1.18.0