fast-check

fast-check

Version 4.6.0
Published 11 days ago
1.38 MB
1 dependency
MIT license

Install

npm i fast-check

yarn add fast-check

pnpm add fast-check

Overview

Property based testing framework for JavaScript (like QuickCheck)

Index

Namespaces

Variables

variable Arbitrary

const Arbitrary: any;

variable asyncToStringMethod

const asyncToStringMethod: Symbol;

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
Modifiers
- @public

variable cloneMethod

const cloneMethod: Symbol;

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
Modifiers
- @public

variable T

const T: any;

variable T

const T: boolean;

variable toStringMethod

const toStringMethod: Symbol;

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
Modifiers
- @public

variable values

const values: T[];

Functions

function anything

anything: {
    (): Arbitrary<unknown>;
    (constraints: ObjectConstraints): Arbitrary<unknown>;
};

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]}
Modifiers
- @public

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.string(),
    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]...

Modifiers

@public

function array

array: <T>(arb: Arbitrary<T>, constraints?: ArrayConstraints) => Arbitrary<T[]>;

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
Modifiers
- @public

function assert

assert: {
    <Ts>(property: IAsyncProperty<Ts>, params?: Parameters<Ts>): Promise<void>;
    <Ts>(property: IProperty<Ts>, params?: Parameters<Ts>): void;
    <Ts>(
        property: IRawProperty<Ts, boolean>,
        params?: Parameters<Ts>
    ): void | Promise<void>;
};

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
Modifiers
- @public
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
Modifiers
- @public
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
Modifiers
- @public

function asyncDefaultReportMessage

asyncDefaultReportMessage: {
    <Ts>(out: RunDetails<Ts> & { failed: false }): Promise<undefined>;
    <Ts>(
        out:
            | (RunDetailsFailureProperty<Ts> & { failed: true })
            | (RunDetailsFailureTooManySkips<Ts> & { failed: true })
            | (RunDetailsFailureInterrupted<Ts> & { failed: true })
    ): Promise<string>;
    <Ts>(out: RunDetails<Ts>): Promise<string>;
};

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
Modifiers
- @public

function asyncModelRun

asyncModelRun: <
    Model extends object,
    Real,
    CheckAsync extends boolean,
    InitialModel extends Model
>(
    s: ModelRunSetup<InitialModel, Real> | ModelRunAsyncSetup<InitialModel, Real>,
    cmds: Iterable<AsyncCommand<Model, Real, CheckAsync>>
) => Promise<void>;

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
Modifiers
- @public

function asyncProperty

asyncProperty: <Ts extends [unknown, ...unknown[]]>(
    ...args: [
        ...arbitraries: { [K in keyof Ts]: Arbitrary<Ts[K]> },
        predicate: (...args: Ts) => Promise<boolean | void>
    ]
) => IAsyncPropertyWithHooks<Ts>;

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
Modifiers
- @public

function asyncStringify

asyncStringify: <Ts>(value: Ts) => Promise<string>;

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
Modifiers
- @public

function base64String

base64String: (constraints?: StringSharedConstraints) => Arbitrary<string>;

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
Modifiers
- @public

function bigInt

bigInt: {
    (): Arbitrary<bigint>;
    (min: bigint, max: bigint): Arbitrary<bigint>;
    (constraints: BigIntConstraints): Arbitrary<bigint>;
    (...args: [] | [bigint, bigint] | [BigIntConstraints]): Arbitrary<bigint>;
};

For bigint
Remarks
Since 1.9.0
Modifiers
- @public
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
Modifiers
- @public
For bigint between min (included) and max (included)
Parameter constraints
Constraints to apply when building instances
Remarks
Since 2.6.0
Modifiers
- @public
For bigint between min (included) and max (included)
Parameter args
Either min/max bounds as an object or constraints to apply when building instances
Remarks
Since 2.6.0
Modifiers
- @public

function bigInt64Array

bigInt64Array: (
    constraints?: BigIntArrayConstraints
) => Arbitrary<BigInt64Array<ArrayBuffer>>;

For BigInt64Array
Remarks
Since 3.0.0
Modifiers
- @public

function bigUint64Array

bigUint64Array: (
    constraints?: BigIntArrayConstraints
) => Arbitrary<BigUint64Array<ArrayBuffer>>;

For BigUint64Array
Remarks
Since 3.0.0
Modifiers
- @public

function boolean

boolean: () => Arbitrary<boolean>;

For boolean values - true or false
Remarks
Since 0.0.6
Modifiers
- @public

function check

check: {
    <Ts>(property: IAsyncProperty<Ts>, params?: Parameters<Ts>): Promise<
        RunDetails<Ts>
    >;
    <Ts>(property: IProperty<Ts>, params?: Parameters<Ts>): RunDetails<Ts>;
    <Ts>(property: IRawProperty<Ts, boolean>, params?: Parameters<Ts>):
        | RunDetails<Ts>
        | Promise<RunDetails<Ts>>;
};

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
Modifiers
- @public
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
Modifiers
- @public
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
Modifiers
- @public

function clone

clone: <T, N extends number>(
    arb: Arbitrary<T>,
    numValues: N
) => Arbitrary<CloneValue<T, N>>;

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
Modifiers
- @public

function cloneIfNeeded

cloneIfNeeded: <T>(instance: T) => T;

Clone an instance if needed
Remarks
Since 2.15.0
Modifiers
- @public

function commands

commands: {
    <Model extends object, Real, CheckAsync extends boolean>(
        commandArbs: Arbitrary<AsyncCommand<Model, Real, CheckAsync>>[],
        constraints?: CommandsContraints
    ): Arbitrary<Iterable<AsyncCommand<Model, Real, CheckAsync>>>;
    <Model extends object, Real>(
        commandArbs: Arbitrary<Command<Model, Real>>[],
        constraints?: CommandsContraints
    ): Arbitrary<Iterable<Command<Model, Real>>>;
};

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
Modifiers
- @public
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
Modifiers
- @public

function compareBooleanFunc

compareBooleanFunc: <T>() => Arbitrary<(a: T, b: T) => boolean>;

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
Modifiers
- @public

function compareFunc

compareFunc: <T>() => Arbitrary<(a: T, b: T) => number>;

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
Modifiers
- @public

function configureGlobal

configureGlobal: (parameters: GlobalParameters) => void;

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 }

Modifiers

@public

function constant

constant: () => any;

For value
Parameter value
The value to produce
Remarks
Since 0.0.1
Modifiers
- @public

function constantFrom

constantFrom: {
    (): any;
    <TArgs extends any[] | [any]>(...values: TArgs): Arbitrary<TArgs[number]>;
};

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
Modifiers
- @public

function context

context: () => Arbitrary<ContextValue>;

Produce a ContextValue instance
Remarks
Since 1.8.0
Modifiers
- @public

function createDepthIdentifier

createDepthIdentifier: () => DepthIdentifier;

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

function date

date: (constraints?: DateConstraints) => Arbitrary<Date>;

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
Modifiers
- @public

function defaultReportMessage

defaultReportMessage: {
    <Ts>(out: RunDetails<Ts> & { failed: false }): undefined;
    <Ts>(
        out:
            | (RunDetailsFailureProperty<Ts> & { failed: true })
            | (RunDetailsFailureTooManySkips<Ts> & { failed: true })
            | (RunDetailsFailureInterrupted<Ts> & { failed: true })
    ): string;
    <Ts>(out: RunDetails<Ts>): string;
};

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
Modifiers
- @public

function dictionary

dictionary: {
    <T>(
        keyArb: Arbitrary<string>,
        valueArb: Arbitrary<T>,
        constraints?: DictionaryConstraints
    ): Arbitrary<Record<string, T>>;
    <K extends PropertyKey, V>(
        keyArb: Arbitrary<K>,
        valueArb: Arbitrary<V>,
        constraints?: DictionaryConstraints
    ): Arbitrary<Record<K, V>>;
};

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
Modifiers
- @public
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 4.4.0
Modifiers
- @public

function domain

domain: (constraints?: DomainConstraints) => Arbitrary<string>;

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
Modifiers
- @public

function double

double: (constraints?: DoubleConstraints) => Arbitrary<number>;

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
Modifiers
- @public

function emailAddress

emailAddress: (constraints?: EmailAddressConstraints) => Arbitrary<string>;

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
Modifiers
- @public

function entityGraph

entityGraph: <
    TEntityFields,
    TEntityRelations extends EntityRelations<TEntityFields>
>(
    arbitraries: Arbitraries<TEntityFields>,
    relations: TEntityRelations,
    constraints?: EntityGraphContraints<TEntityFields>
) => Arbitrary<EntityGraphValue<TEntityFields, TEntityRelations>>;

Generates interconnected entities with relationships based on a schema definition.
This arbitrary creates structured data where entities can reference each other through defined relationships. The generated values automatically include links between entities, making it ideal for testing graph structures, relational data, or interconnected object models.
The output is an object where each key corresponds to an entity type and the value is an array of entities of that type. Entities contain both their data fields and relationship links.
Parameter arbitraries
Defines the data fields for each entity type (non-relational properties)
Parameter relations
Defines how entities reference each other (relational properties)
Parameter constraints
Optional configuration to customize generation behavior
Remarks
Since 4.5.0
Example 1
// Generate a simple directed graph where nodes link to other nodes fc.entityGraph( { node: { id: fc.stringMatching(/^[A-Z][a-z]*$/) } }, { node: { linkTo: { arity: 'many', type: 'node' } } }, ) // Produces: { node: [{ id: "Abc", linkTo: [<node#1>, <node#0>] }, ...] }
Example 2
// Generate employees with managers and teams fc.entityGraph( { employee: { name: fc.string() }, team: { name: fc.string() } }, { employee: { manager: { arity: '0-1', type: 'employee' }, // Optional manager team: { arity: '1', type: 'team' } // Required team }, team: {} } )
Modifiers
- @public

function falsy

falsy: <TConstraints extends FalsyContraints>(
    constraints?: TConstraints
) => Arbitrary<FalsyValue<TConstraints>>;

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
Modifiers
- @public

function float

float: (constraints?: FloatConstraints) => Arbitrary<number>;

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
Modifiers
- @public

function float32Array

float32Array: (
    constraints?: Float32ArrayConstraints
) => Arbitrary<Float32Array<ArrayBuffer>>;

For Float32Array
Remarks
Since 2.9.0
Modifiers
- @public

function float64Array

float64Array: (
    constraints?: Float64ArrayConstraints
) => Arbitrary<Float64Array<ArrayBuffer>>;

For Float64Array
Remarks
Since 2.9.0
Modifiers
- @public

function func

func: <TArgs extends any[], TOut>(
    arb: Arbitrary<TOut>
) => Arbitrary<(...args: TArgs) => TOut>;

For pure functions
Parameter arb
Arbitrary responsible to produce the values
Remarks
Since 1.6.0
Modifiers
- @public

function gen

gen: () => Arbitrary<GeneratorValue>;

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.
Modifiers
- @public

function getDepthContextFor

getDepthContextFor: (
    contextMeta: DepthContext | DepthIdentifier | string | undefined
) => DepthContext;

Get back the requested DepthContext
Remarks
Since 2.25.0
Modifiers
- @public

function hasAsyncToStringMethod

hasAsyncToStringMethod: <T>(
    instance: T
) => instance is T & WithAsyncToStringMethod;

Check if an instance implements WithAsyncToStringMethod
Remarks
Since 2.17.0
Modifiers
- @public

function hasCloneMethod

hasCloneMethod: <T>(
    instance: T | WithCloneMethod<T>
) => instance is WithCloneMethod<T>;

Check if an instance has to be clone
Remarks
Since 2.15.0
Modifiers
- @public

function hash

hash: (repr: string) => number;

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
Modifiers
- @public

function hasToStringMethod

hasToStringMethod: <T>(instance: T) => instance is T & WithToStringMethod;

Check if an instance implements WithToStringMethod
Remarks
Since 2.17.0
Modifiers
- @public

function infiniteStream

infiniteStream: <T>(
    arb: Arbitrary<T>,
    constraints?: InfiniteStreamConstraints
) => Arbitrary<Stream<T>>;

Produce an infinite stream of values
WARNING: By default, infiniteStream remembers all values it has ever generated. This causes unbounded memory growth during large tests. Set noHistory to disable.
WARNING: Requires Object.assign
Parameter arb
Arbitrary used to generate the values
Parameter constraints
Constraints to apply when building instances (since 4.3.0)
Remarks
Since 1.8.0
Modifiers
- @public

function int16Array

int16Array: (
    constraints?: IntArrayConstraints
) => Arbitrary<Int16Array<ArrayBuffer>>;

For Int16Array
Remarks
Since 2.9.0
Modifiers
- @public

function int32Array

int32Array: (
    constraints?: IntArrayConstraints
) => Arbitrary<Int32Array<ArrayBuffer>>;

For Int32Array
Remarks
Since 2.9.0
Modifiers
- @public

function int8Array

int8Array: (
    constraints?: IntArrayConstraints
) => Arbitrary<Int8Array<ArrayBuffer>>;

For Int8Array
Remarks
Since 2.9.0
Modifiers
- @public

function integer

integer: (constraints?: IntegerConstraints) => Arbitrary<number>;

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
Modifiers
- @public

function ipV4

ipV4: () => Arbitrary<string>;

For valid IP v4
Following RFC 3986
Remarks
Since 1.14.0
Modifiers
- @public

function ipV4Extended

ipV4Extended: () => Arbitrary<string>;

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
Modifiers
- @public

function ipV6

ipV6: () => Arbitrary<string>;

For valid IP v6
Following RFC 3986
Remarks
Since 1.14.0
Modifiers
- @public

function json

json: (constraints?: JsonSharedConstraints) => Arbitrary<string>;

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
Modifiers
- @public

function jsonValue

jsonValue: (constraints?: JsonSharedConstraints) => Arbitrary<JsonValue>;

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
Modifiers
- @public

function letrec

letrec: {
    <T>(
        builder: T extends Record<string, unknown> ? LetrecTypedBuilder<T> : never
    ): LetrecValue<T>;
    <T>(builder: LetrecLooselyTypedBuilder<T>): LetrecValue<T>;
};

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)

Modifiers

@public

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)

Modifiers

@public

function limitShrink

limitShrink: <T>(arbitrary: Arbitrary<T>, maxShrinks: number) => Arbitrary<T>;

Create another Arbitrary with a limited (or capped) number of shrink values
Parameter arbitrary
Instance of arbitrary responsible to generate and shrink values
Parameter maxShrinks
Maximal number of shrunk values that can be pulled from the resulting arbitrary
Returns
Create another arbitrary with limited number of shrink values
Remarks
Since 3.20.0
Example 1
const dataGenerator: Arbitrary<string> = ...; const limitedShrinkableDataGenerator: Arbitrary<string> = fc.limitShrink(dataGenerator, 10); // up to 10 shrunk values could be extracted from the resulting arbitrary
NOTE: Although limiting the shrinking capabilities can speed up your CI when failures occur, we do not recommend this approach. Instead, if you want to reduce the shrinking time for automated jobs or local runs, consider using endOnFailure or interruptAfterTimeLimit.
Modifiers
- @public

function lorem

lorem: (constraints?: LoremConstraints) => Arbitrary<string>;

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
Modifiers
- @public

function map

map: <K, V>(
    keyArb: Arbitrary<K>,
    valueArb: Arbitrary<V>,
    constraints?: MapConstraints
) => Arbitrary<Map<K, V>>;

For Maps with keys produced by keyArb and values from valueArb
Parameter keyArb
Arbitrary used to generate the keys of the Map
Parameter valueArb
Arbitrary used to generate the values of the Map
Parameter constraints
Constraints to apply when building instances
Remarks
Since 4.4.0
Modifiers
- @public

function mapToConstant

mapToConstant: <T>(
    ...entries: { num: number; build: (idInGroup: number) => T }[]
) => Arbitrary<T>;

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) }, )
Modifiers
- @public

function maxSafeInteger

maxSafeInteger: () => Arbitrary<number>;

For integers between Number.MIN_SAFE_INTEGER (included) and Number.MAX_SAFE_INTEGER (included)
Remarks
Since 1.11.0
Modifiers
- @public

function maxSafeNat

maxSafeNat: () => Arbitrary<number>;

For positive integers between 0 (included) and Number.MAX_SAFE_INTEGER (included)
Remarks
Since 1.11.0
Modifiers
- @public

function memo

memo: <T>(builder: (maxDepth: number) => Arbitrary<T>) => Memo<T>;

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;

Modifiers

@public

function mixedCase

mixedCase: (
    stringArb: Arbitrary<string>,
    constraints?: MixedCaseConstraints
) => Arbitrary<string>;

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
Modifiers
- @public

function modelRun

modelRun: <Model extends object, Real, InitialModel extends Model>(
    s: ModelRunSetup<InitialModel, Real>,
    cmds: Iterable<Command<Model, Real>>
) => void;

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
Modifiers
- @public

function nat

nat: {
    (): Arbitrary<number>;
    (max: number): Arbitrary<number>;
    (constraints: NatConstraints): Arbitrary<number>;
    (arg?: number | NatConstraints): Arbitrary<number>;
};

For positive integers between 0 (included) and 2147483647 (included)
Remarks
Since 0.0.1
Modifiers
- @public
For positive integers between 0 (included) and max (included)
Parameter max
Upper bound for the generated integers
Remarks
Since 0.0.1
Modifiers
- @public
For positive integers between 0 (included) and max (included)
Parameter constraints
Constraints to apply when building instances
Remarks
Since 2.6.0
Modifiers
- @public
For positive integers between 0 (included) and max (included)
Parameter arg
Either a maximum number or constraints to apply when building instances
Remarks
Since 2.6.0
Modifiers
- @public

function noBias

noBias: <T>(arb: Arbitrary<T>) => Arbitrary<T>;

Build an arbitrary without any bias.
The produced instance wraps the source one and ensures the bias factor will always be passed to undefined meaning bias will be deactivated. All the rest stays unchanged.
Parameter arb
The original arbitrary used for generating values. This arbitrary remains unchanged.
Remarks
Since 3.20.0
Modifiers
- @public

function noShrink

noShrink: <T>(arb: Arbitrary<T>) => Arbitrary<T>;

Build an arbitrary without shrinking capabilities.
NOTE: In most cases, users should avoid disabling shrinking capabilities. If the concern is the shrinking process taking too long or being unnecessary in CI environments, consider using alternatives like endOnFailure or interruptAfterTimeLimit instead.
Parameter arb
The original arbitrary used for generating values. This arbitrary remains unchanged, but its shrinking capabilities will not be included in the new arbitrary.
Remarks
Since 3.20.0
Modifiers
- @public

function object

object: {
    (): Arbitrary<Record<string, unknown>>;
    (constraints: ObjectConstraints): Arbitrary<Record<string, unknown>>;
};

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]}
Modifiers
- @public
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]}
Modifiers
- @public

function oneof

oneof: {
    <Ts extends MaybeWeightedArbitrary<unknown>[]>(...arbs: Ts): Arbitrary<
        OneOfValue<Ts>
    >;
    <Ts extends MaybeWeightedArbitrary<unknown>[]>(
        constraints: OneOfConstraints,
        ...arbs: Ts
    ): Arbitrary<OneOfValue<Ts>>;
};

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
Modifiers
- @public
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
Modifiers
- @public

function option

option: <T, TNil = null>(
    arb: Arbitrary<T>,
    constraints?: OptionConstraints<TNil>
) => Arbitrary<T | TNil>;

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
Modifiers
- @public

function pre

pre: (expectTruthy: boolean) => asserts expectTruthy;

Add pre-condition checks inside a property execution
Parameter expectTruthy
cancel the run whenever this value is falsy
Remarks
Since 1.3.0
Modifiers
- @public

function property

property: <Ts extends [unknown, ...unknown[]]>(
    ...args: [
        ...arbitraries: { [K in keyof Ts]: Arbitrary<Ts[K]> },
        predicate: (...args: Ts) => boolean | void
    ]
) => IPropertyWithHooks<Ts>;

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
Modifiers
- @public

function readConfigureGlobal

readConfigureGlobal: () => GlobalParameters;

Read global parameters that will be used by runners
Remarks
Since 1.18.0
Modifiers
- @public

function record

record: <T, K extends keyof T = keyof T>(
    model: { [K in keyof T]: Arbitrary<T[K]> },
    constraints?: RecordConstraints<K>
) => Arbitrary<RecordValue<T, K>>;

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 }, {requiredKeys: []}): Arbitrary<{x?:number,y?:number}>
// merge two integer arbitraries to produce a {x, y}, {x}, {y} or {} record

Modifiers

@public

function resetConfigureGlobal

resetConfigureGlobal: () => void;

Reset global parameters
Remarks
Since 1.18.0
Modifiers
- @public

function sample

sample: <Ts>(
    generator: IRawProperty<Ts> | Arbitrary<Ts>,
    params?: Parameters<Ts> | number
) => Ts[];

Generate an array containing all the values that would have been generated during assert or check
Parameter generator
IProperty or Arbitrary to extract the values from
Parameter params
Integer representing the number of values to generate or Parameters as in assert
Remarks
Since 0.0.6
Example 1
fc.sample(fc.nat(), 10); // extract 10 values from fc.nat() Arbitrary fc.sample(fc.nat(), {seed: 42}); // extract values from fc.nat() as if we were running fc.assert with seed=42
Modifiers
- @public

function scheduledModelRun

scheduledModelRun: <
    Model extends object,
    Real,
    CheckAsync extends boolean,
    InitialModel extends Model
>(
    scheduler: Scheduler,
    s: ModelRunSetup<InitialModel, Real> | ModelRunAsyncSetup<InitialModel, Real>,
    cmds: Iterable<AsyncCommand<Model, Real, CheckAsync>>
) => Promise<void>;

Run asynchronous and scheduled commands over a Model and the Real system
Throw in case of inconsistency
Parameter scheduler
Scheduler
Parameter s
Initial state provider
Parameter cmds
Asynchronous commands to be executed
Remarks
Since 1.24.0
Modifiers
- @public

function scheduler

scheduler: <TMetaData = unknown>(
    constraints?: SchedulerConstraints
) => Arbitrary<Scheduler<TMetaData>>;

For scheduler of promises
Remarks
Since 1.20.0
Modifiers
- @public

function schedulerFor

schedulerFor: {
    <TMetaData = unknown>(constraints?: SchedulerConstraints): (
        _strs: TemplateStringsArray,
        ...ordering: number[]
    ) => Scheduler<TMetaData>;
    <TMetaData = unknown>(
        customOrdering: number[],
        constraints?: SchedulerConstraints
    ): Scheduler<TMetaData>;
};

For custom scheduler with predefined resolution order
Ordering is defined by using a template string like the one generated in case of failure of a scheduler
It may be something like:
Remarks
Since 1.25.0
Example 1
fc.schedulerFor()` -> [task\${2}] promise pending -> [task\${3}] promise pending -> [task\${1}] promise pending `
Or more generally:
fc.schedulerFor()` This scheduler will resolve task ${2} first followed by ${3} and only then task ${1} `
WARNING: Custom scheduler will neither check that all the referred promises have been scheduled nor that they resolved with the same status and value.
WARNING: If one the promises is wrongly defined it will fail - for instance asking to resolve 5 while 5 does not exist.
Modifiers
- @public
For custom scheduler with predefined resolution order
WARNING: Custom scheduler will not check that all the referred promises have been scheduled.
WARNING: If one the promises is wrongly defined it will fail - for instance asking to resolve 5 while 5 does not exist.
Parameter customOrdering
Array defining in which order the promises will be resolved. Id of the promises start at 1. 1 means first scheduled promise, 2 second scheduled promise and so on.
Remarks
Since 1.25.0
Modifiers
- @public

function set

set: <T>(arb: Arbitrary<T>, constraints?: SetConstraints) => Arbitrary<Set<T>>;

For sets of values coming from arb
All the values in the set are unique. Comparison of values relies on SameValueZero which is the same comparison algorithm used by Set.
Parameter arb
Arbitrary used to generate the values inside the set
Parameter constraints
Constraints to apply when building instances
Remarks
Since 4.4.0
Modifiers
- @public

function shuffledSubarray

shuffledSubarray: <T>(
    originalArray: T[],
    constraints?: ShuffledSubarrayConstraints
) => Arbitrary<T[]>;

For subarrays of originalArray
Parameter originalArray
Original array
Parameter constraints
Constraints to apply when building instances (since 2.4.0)
Remarks
Since 1.5.0
Modifiers
- @public

function sparseArray

sparseArray: <T>(
    arb: Arbitrary<T>,
    constraints?: SparseArrayConstraints
) => Arbitrary<T[]>;

For sparse arrays of values coming from arb
Parameter arb
Arbitrary used to generate the values inside the sparse array
Parameter constraints
Constraints to apply when building instances
Remarks
Since 2.13.0
Modifiers
- @public

function statistics

statistics: <Ts>(
    generator: IRawProperty<Ts> | Arbitrary<Ts>,
    classify: (v: Ts) => string | string[],
    params?: Parameters<Ts> | number
) => void;

Gather useful statistics concerning generated values
Print the result in console.log or params.logger (if defined)
Parameter generator
IProperty or Arbitrary to extract the values from
Parameter classify
Classifier function that can classify the generated value in zero, one or more categories (with free labels)
Parameter params
Integer representing the number of values to generate or Parameters as in assert
Remarks
Since 0.0.6
Example 1
fc.statistics( fc.nat(999), v => v < 100 ? 'Less than 100' : 'More or equal to 100', {numRuns: 1000, logger: console.log}); // Classify 1000 values generated by fc.nat(999) into two categories: // - Less than 100 // - More or equal to 100 // The output will be sent line by line to the logger
Modifiers
- @public

function stream

stream: <T>(g: IterableIterator<T>) => Stream<T>;

Create a Stream based on g
Parameter g
Underlying data of the Stream
Remarks
Since 0.0.7
Modifiers
- @public

function string

string: (constraints?: StringConstraints) => Arbitrary<string>;

For strings of char
Parameter constraints
Constraints to apply when building instances (since 2.4.0)
Remarks
Since 0.0.1
Modifiers
- @public

function stringify

stringify: <Ts>(value: Ts) => string;

Convert any value to its fast-check string representation
Parameter value
Value to be converted into a string
Remarks
Since 1.15.0
Modifiers
- @public

function stringMatching

stringMatching: (
    regex: RegExp,
    constraints?: StringMatchingConstraints
) => Arbitrary<string>;

For strings matching the provided regex
Parameter regex
Arbitrary able to generate random strings (possibly multiple characters)
Parameter constraints
Constraints to apply when building instances
Remarks
Since 3.10.0
Modifiers
- @public

function subarray

subarray: <T>(
    originalArray: T[],
    constraints?: SubarrayConstraints
) => Arbitrary<T[]>;

For subarrays of originalArray (keeps ordering)
Parameter originalArray
Original array
Parameter constraints
Constraints to apply when building instances (since 2.4.0)
Remarks
Since 1.5.0
Modifiers
- @public

function tuple

tuple: <Ts extends unknown[]>(
    ...arbs: { [K in keyof Ts]: Arbitrary<Ts[K]> }
) => Arbitrary<Ts>;

For tuples produced using the provided arbs
Parameter arbs
Ordered list of arbitraries
Remarks
Since 0.0.1
Modifiers
- @public

function uint16Array

uint16Array: (
    constraints?: IntArrayConstraints
) => Arbitrary<Uint16Array<ArrayBuffer>>;

For Uint16Array
Remarks
Since 2.9.0
Modifiers
- @public

function uint32Array

uint32Array: (
    constraints?: IntArrayConstraints
) => Arbitrary<Uint32Array<ArrayBuffer>>;

For Uint32Array
Remarks
Since 2.9.0
Modifiers
- @public

function uint8Array

uint8Array: (
    constraints?: IntArrayConstraints
) => Arbitrary<Uint8Array<ArrayBuffer>>;

For Uint8Array
Remarks
Since 2.9.0
Modifiers
- @public

function uint8ClampedArray

uint8ClampedArray: (
    constraints?: IntArrayConstraints
) => Arbitrary<Uint8ClampedArray<ArrayBuffer>>;

For Uint8ClampedArray
Remarks
Since 2.9.0
Modifiers
- @public

function ulid

ulid: () => Arbitrary<string>;

For ulid
According to ulid spec
No mixed case, only upper case digits (0-9A-Z except for: I,L,O,U)
Remarks
Since 3.11.0
Modifiers
- @public

function uniqueArray

uniqueArray: {
    <T, U>(
        arb: Arbitrary<T>,
        constraints?: UniqueArrayConstraintsRecommended<T, U>
    ): Arbitrary<T[]>;
    <T>(
        arb: Arbitrary<T>,
        constraints: UniqueArrayConstraintsCustomCompare<T>
    ): Arbitrary<T[]>;
    <T, U>(
        arb: Arbitrary<T>,
        constraints: UniqueArrayConstraintsCustomCompareSelect<T, U>
    ): Arbitrary<T[]>;
    <T, U>(arb: Arbitrary<T>, constraints: UniqueArrayConstraints<T, U>): Arbitrary<
        T[]
    >;
};

For arrays of unique values coming from arb
Parameter arb
Arbitrary used to generate the values inside the array
Parameter constraints
Constraints to apply when building instances
Remarks
Since 2.23.0
Modifiers
- @public

function uuid

uuid: (constraints?: UuidConstraints) => Arbitrary<string>;

For UUID from v1 to v5
According to RFC 4122
No mixed case, only lower case digits (0-9a-f)
Remarks
Since 1.17.0
Modifiers
- @public

function webAuthority

webAuthority: (constraints?: WebAuthorityConstraints) => Arbitrary<string>;

For web authority
According to RFC 3986 - authority = [ userinfo "@" ] host [ ":" port ]
Parameter constraints
Constraints to apply when building instances
Remarks
Since 1.14.0
Modifiers
- @public

function webFragments

webFragments: (constraints?: WebFragmentsConstraints) => Arbitrary<string>;

For fragments of an URI (web included)
According to RFC 3986
eg.: In the url https://domain/plop?page=1#hello=1&world=2, ?hello=1&world=2 are query parameters
Parameter constraints
Constraints to apply when building instances (since 2.22.0)
Remarks
Since 1.14.0
Modifiers
- @public

function webPath

webPath: (constraints?: WebPathConstraints) => Arbitrary<string>;

For web path
According to RFC 3986 and WHATWG URL Standard
Parameter constraints
Constraints to apply when building instances
Remarks
Since 3.3.0
Modifiers
- @public

function webQueryParameters

webQueryParameters: (
    constraints?: WebQueryParametersConstraints
) => Arbitrary<string>;

For query parameters of an URI (web included)
According to RFC 3986
eg.: In the url https://domain/plop/?hello=1&world=2, ?hello=1&world=2 are query parameters
Parameter constraints
Constraints to apply when building instances (since 2.22.0)
Remarks
Since 1.14.0
Modifiers
- @public

function webSegment

webSegment: (constraints?: WebSegmentConstraints) => Arbitrary<string>;

For internal segment of an URI (web included)
According to RFC 3986
eg.: In the url https://github.com/dubzzz/fast-check/, dubzzz and fast-check are segments
Parameter constraints
Constraints to apply when building instances (since 2.22.0)
Remarks
Since 1.14.0
Modifiers
- @public

function webUrl

webUrl: (constraints?: WebUrlConstraints) => Arbitrary<string>;

For web url
According to RFC 3986 and WHATWG URL Standard
Parameter constraints
Constraints to apply when building instances
Remarks
Since 1.14.0
Modifiers
- @public

Classes

class Arbitrary

abstract class Arbitrary<T> {}

Abstract class able to generate values on type T
The values generated by an instance of Arbitrary can be previewed - with sample - or classified - with statistics.
Remarks
Since 0.0.7
Modifiers
- @public

method canShrinkWithoutContext

abstract canShrinkWithoutContext: (value: unknown) => value is T;

Check if a given value could be pass to shrink without providing any context.
In general, canShrinkWithoutContext is not designed to be called for each shrink but rather on very special cases. Its usage must be restricted to canShrinkWithoutContext or in the rare* contexts of a shrink method being called without any context. In this ill-formed case of shrink, canShrinkWithoutContext could be used or called if needed.
*we fall in that case when fast-check is asked to shrink a value that has been provided manually by the user, in other words: a value not coming from a call to generate or a normal shrink with context.
Parameter value
Value to be assessed
Returns
true if and only if the value could have been generated by this instance
Remarks
Since 3.0.0

method chain

chain: <U>(chainer: (t: T) => Arbitrary<U>) => Arbitrary<U>;

Create another arbitrary by mapping a value from a base Arbirary using the provided fmapper Values produced by the new arbitrary are the result of the arbitrary generated by applying fmapper to a value
Parameter chainer
Chain function, to produce a new Arbitrary using a value from another Arbitrary
Returns
New arbitrary of new type
Remarks
Since 1.2.0
Example 1
const arrayAndLimitArbitrary = fc.nat().chain((c: number) => fc.tuple( fc.array(fc.nat(c)), fc.constant(c)));

method filter

filter: {
    <U extends T>(refinement: (t: T) => t is U): Arbitrary<U>;
    (predicate: (t: T) => boolean): Arbitrary<T>;
};

Create another arbitrary by filtering values against predicate
All the values produced by the resulting arbitrary satisfy predicate(value) == true
Be aware that using filter may highly impact the time required to generate a valid entry
Parameter refinement
Predicate, to test each produced element. Return true to keep the element, false otherwise
Returns
New arbitrary filtered using predicate
Remarks
Since 1.23.0
Example 1
const integerGenerator: Arbitrary<number> = ...; const evenIntegerGenerator: Arbitrary<number> = integerGenerator.filter(e => e % 2 === 0); // new Arbitrary only keeps even values
Create another arbitrary by filtering values against predicate
All the values produced by the resulting arbitrary satisfy predicate(value) == true
Be aware that using filter may highly impact the time required to generate a valid entry
Parameter predicate
Predicate, to test each produced element. Return true to keep the element, false otherwise
Returns
New arbitrary filtered using predicate
Remarks
Since 0.0.1
Example 1
const integerGenerator: Arbitrary<number> = ...; const evenIntegerGenerator: Arbitrary<number> = integerGenerator.filter(e => e % 2 === 0); // new Arbitrary only keeps even values

method generate

abstract generate: (mrng: Random, biasFactor: number | undefined) => Value<T>;

Generate a value of type T along with its context (if any) based on the provided random number generator
Parameter mrng
Random number generator
Parameter biasFactor
If taken into account 1 value over biasFactor must be biased. Either integer value greater or equal to 2 (bias) or undefined (no bias)
Returns
Random value of type T and its context
Remarks
Since 0.0.1 (return type changed in 3.0.0)

method map

map: <U>(
    mapper: (t: T) => U,
    unmapper?: (possiblyU: unknown) => T
) => Arbitrary<U>;

Create another arbitrary by mapping all produced values using the provided mapper Values produced by the new arbitrary are the result of applying mapper value by value
Parameter mapper
Map function, to produce a new element based on an old one
Parameter unmapper
Optional unmap function, it will never be used except when shrinking user defined values. Must throw if value is not compatible (since 3.0.0)
Returns
New arbitrary with mapped elements
Remarks
Since 0.0.1
Example 1
const rgbChannels: Arbitrary<{r:number,g:number,b:number}> = ...; const color: Arbitrary<string> = rgbChannels.map(ch => `#${(ch.r*65536 + ch.g*256 + ch.b).toString(16).padStart(6, '0')}`); // transform an Arbitrary producing {r,g,b} integers into an Arbitrary of '#rrggbb'

method shrink

abstract shrink: (value: T, context: unknown | undefined) => Stream<Value<T>>;

Shrink a value of type T, may rely on the context previously provided to shrink efficiently
Must never be called with possibly invalid values and no context without ensuring that such call is legal by calling canShrinkWithoutContext first on the value.
Parameter value
The value to shrink
Parameter context
Its associated context (the one returned by generate) or undefined if no context but canShrinkWithoutContext(value) === true
Returns
Stream of shrinks for value based on context (if provided)
Remarks
Since 3.0.0

class PreconditionFailure

class PreconditionFailure extends Error {}

Error type produced whenever a precondition fails
Remarks
Since 2.2.0
Modifiers
- @public

constructor

constructor(interruptExecution?: boolean);

property interruptExecution

readonly interruptExecution: boolean;

method isFailure

static isFailure: (err: unknown) => err is PreconditionFailure;

class Random

class Random {}

Wrapper around an instance of a pure-rand's random number generator offering a simpler interface to deal with random with impure patterns
Modifiers
- @public

constructor

constructor(sourceRng: any);

Create a mutable random number generator by cloning the passed one and mutate it
Parameter sourceRng
Immutable random generator from pure-rand library, will not be altered (a clone will be)

method clone

clone: () => Random;

Clone the random number generator

method getState

getState: () => readonly number[] | undefined;

Extract the internal state of the internal RandomGenerator backing the current instance of Random

method next

next: (bits: number) => number;

Generate an integer having bits random bits
Parameter bits
Number of bits to generate
Deprecated
Prefer nextInt with explicit bounds: nextInt(0, (1 << bits) - 1)

method nextBigInt

nextBigInt: (min: bigint, max: bigint) => bigint;

Generate a random bigint between min (included) and max (included)
Parameter min
Minimal bigint value
Parameter max
Maximal bigint value

method nextBoolean

nextBoolean: () => boolean;

Generate a random boolean

method nextDouble

nextDouble: () => number;

Generate a random floating point number between 0.0 (included) and 1.0 (excluded)

method nextInt

nextInt: { (): number; (min: number, max: number): number };

Generate a random integer (32 bits)
Deprecated
Prefer nextInt with explicit bounds: nextInt(-2147483648, 2147483647)
Generate a random integer between min (included) and max (included)
Parameter min
Minimal integer value
Parameter max
Maximal integer value

class Stream

class Stream<T> implements IterableIterator<T> {}

Wrapper around IterableIterator interface offering a set of helpers to deal with iterations in a simple way
Remarks
Since 0.0.7
Modifiers
- @public

constructor

constructor(g: IterableIterator<T>);

Create a Stream based on g
Parameter g
Underlying data of the Stream

method [Symbol.iterator]

[Symbol.iterator]: () => IterableIterator<T>;

method drop

drop: (n: number) => Stream<T>;

Drop n first elements of the Stream
WARNING: It closes the current stream
Parameter n
Number of elements to drop
Remarks
Since 0.0.1

method dropWhile

dropWhile: (f: (v: T) => boolean) => Stream<T>;

Drop elements from the Stream while f(element) === true
WARNING: It closes the current stream
Parameter f
Drop condition
Remarks
Since 0.0.1

method every

every: (f: (v: T) => boolean) => boolean;

Check whether all elements of the Stream are successful for f
WARNING: It closes the current stream
Parameter f
Condition to check
Remarks
Since 0.0.1

method filter

filter: {
    <U extends T>(f: (v: T) => v is U): Stream<U>;
    (f: (v: T) => boolean): Stream<T>;
};

Filter elements of the Stream
WARNING: It closes the current stream
Parameter f
Elements to keep
Remarks
Since 1.23.0
Filter elements of the Stream
WARNING: It closes the current stream
Parameter f
Elements to keep
Remarks
Since 0.0.1

method flatMap

flatMap: <U>(f: (v: T) => IterableIterator<U>) => Stream<U>;

Flat map all elements of the Stream using f
WARNING: It closes the current stream
Parameter f
Mapper function
Remarks
Since 0.0.1

method getNthOrLast

getNthOrLast: (nth: number) => T | null;

Take the nth element of the Stream of the last (if it does not exist)
WARNING: It closes the current stream
Parameter nth
Position of the element to extract
Remarks
Since 0.0.12

method has

has: (f: (v: T) => boolean) => [boolean, T | null];

Check whether one of the elements of the Stream is successful for f
WARNING: It closes the current stream
Parameter f
Condition to check
Remarks
Since 0.0.1

method join

join: (...others: IterableIterator<T>[]) => Stream<T>;

Join others Stream to the current Stream
WARNING: It closes the current stream and the other ones (as soon as it iterates over them)
Parameter others
Streams to join to the current Stream
Remarks
Since 0.0.1

method map

map: <U>(f: (v: T) => U) => Stream<U>;

Map all elements of the Stream using f
WARNING: It closes the current stream
Parameter f
Mapper function
Remarks
Since 0.0.1

method next

next: () => IteratorResult<T>;

method nil

static nil: <T>() => Stream<T>;

Create an empty stream of T
Remarks
Since 0.0.1

method of

static of: <T>(...elements: T[]) => Stream<T>;

Create a stream of T from a variable number of elements
Parameter elements
Elements used to create the Stream
Remarks
Since 2.12.0

method take

take: (n: number) => Stream<T>;

Take n first elements of the Stream
WARNING: It closes the current stream
Parameter n
Number of elements to take
Remarks
Since 0.0.1

method takeWhile

takeWhile: (f: (v: T) => boolean) => Stream<T>;

Take elements from the Stream while f(element) === true
WARNING: It closes the current stream
Parameter f
Take condition
Remarks
Since 0.0.1

class Value

class Value<T> {}

A Value<T, TShrink = T> holds an internal value of type T and its associated context
Remarks
Since 3.0.0 (previously called NextValue in 2.15.0)
Modifiers
- @public

constructor

constructor(value_: {}, context: {}, customGetValue?: () => T);

Parameter value_
Internal value of the shrinkable
Parameter context
Context associated to the generated value (useful for shrink)
Parameter customGetValue
Limited to internal usages (to ease migration to next), it will be removed on next major

property context

readonly context: {};

Context for the generated value TODO - Do we want to clone it too?
Remarks
2.15.0

property hasToBeCloned

readonly hasToBeCloned: boolean;

State storing the result of hasCloneMethod If true the value will be cloned each time it gets accessed
Remarks
Since 2.15.0

property value

readonly value: {};

Safe value of the shrinkable Depending on hasToBeCloned it will either be value_ or a clone of it
Remarks
Since 2.15.0

property value_

readonly value_: {};

Internal value of the shrinkable
Remarks
Since 2.15.0

Interfaces

interface ArrayConstraints

interface ArrayConstraints {}

Constraints to be applied on array
Remarks
Since 2.4.0
Modifiers
- @public

property depthIdentifier

depthIdentifier?: DepthIdentifier | string;

When receiving a depth identifier, the arbitrary will impact the depth attached to it to avoid going too deep if it already generated lots of items.
In other words, if the number of generated values within the collection is large then the generated items will tend to be less deep to avoid creating structures a lot larger than expected.
For the moment, the depth is not taken into account to compute the number of items to define for a precise generate call of the array. Just applied onto eligible items.
Remarks
Since 2.25.0

property maxLength

maxLength?: number;

Upper bound of the generated array size
Remarks
Since 2.4.0

property minLength

minLength?: number;

Lower bound of the generated array size
Remarks
Since 2.4.0

property size

size?: SizeForArbitrary;

Define how large the generated values should be (at max)
When used in conjonction with maxLength, size will be used to define the upper bound of the generated array size while maxLength will be used to define and document the general maximal length allowed for this case.
Remarks
Since 2.22.0

interface AsyncCommand

interface AsyncCommand<
    Model extends object,
    Real,
    CheckAsync extends boolean = false
> extends ICommand<Model, Real, Promise<void>, CheckAsync> {}

Interface that should be implemented in order to define an asynchronous command
Remarks
Since 1.5.0
Modifiers
- @public

interface BigIntConstraints

interface BigIntConstraints {}

Constraints to be applied on bigInt
Remarks
Since 2.6.0
Modifiers
- @public

property max

max?: bigint;

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

property min

min?: bigint;

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

interface Command

interface Command<Model extends object, Real> extends ICommand<Model, Real, void> {}

Interface that should be implemented in order to define a synchronous command
Remarks
Since 1.5.0
Modifiers
- @public

interface CommandsContraints

interface CommandsContraints {}

Parameters for commands
Remarks
Since 2.2.0
Modifiers
- @public

property disableReplayLog

disableReplayLog?: boolean;

Do not show replayPath in the output
Remarks
Since 1.11.0

property maxCommands

maxCommands?: number;

Maximal number of commands to generate per run
You probably want to use size instead.
Remarks
Since 1.11.0

property replayPath

replayPath?: string;

Hint for replay purposes only
Should be used in conjonction with { seed, path } of assert
Remarks
Since 1.11.0

property size

size?: SizeForArbitrary;

Define how large the generated values (number of commands) should be (at max)
Remarks
Since 2.22.0

interface ContextValue

interface ContextValue {}

Execution context attached to one predicate run
Remarks
Since 2.2.0
Modifiers
- @public

method log

log: (data: string) => void;

Log execution details during a test. Very helpful when troubleshooting failures
Parameter data
Data to be logged into the current context
Remarks
Since 1.8.0

method size

size: () => number;

Number of logs already logged into current context
Remarks
Since 1.8.0

interface DateConstraints

interface DateConstraints {}

Constraints to be applied on date
Remarks
Since 3.3.0
Modifiers
- @public

property max

max?: Date;

Upper bound of the range (included)
Remarks
Since 1.17.0

property min

min?: Date;

Lower bound of the range (included)
Remarks
Since 1.17.0

property noInvalidDate

noInvalidDate?: boolean;

When set to true, no more "Invalid Date" can be generated.
Remarks
Since 3.13.0

interface DictionaryConstraints

interface DictionaryConstraints {}

Constraints to be applied on dictionary
Remarks
Since 2.22.0
Modifiers
- @public

property depthIdentifier

depthIdentifier?: DepthIdentifier | string;

Depth identifier can be used to share the current depth between several instances.
By default, if not specified, each instance of dictionary will have its own depth. In other words: you can have depth=1 in one while you have depth=100 in another one.
Remarks
Since 3.15.0

property maxKeys

maxKeys?: number;

Upper bound for the number of keys defined into the generated instance
Remarks
Since 2.22.0

property minKeys

minKeys?: number;

Lower bound for the number of keys defined into the generated instance
Remarks
Since 2.22.0

property noNullPrototype

noNullPrototype?: boolean;

Do not generate objects with null prototype
Remarks
Since 3.13.0

property size

size?: SizeForArbitrary;

Define how large the generated values should be (at max)
Remarks
Since 2.22.0

interface DomainConstraints

interface DomainConstraints {}

Constraints to be applied on domain
Remarks
Since 2.22.0
Modifiers
- @public

property size

size?: Exclude<SizeForArbitrary, 'max'>;

Define how large the generated values should be (at max)
Remarks
Since 2.22.0

interface DoubleConstraints

interface DoubleConstraints {}

Constraints to be applied on double
Remarks
Since 2.6.0
Modifiers
- @public

property max

max?: number;

Upper bound for the generated 64-bit floats (included, see maxExcluded to exclude it)
Remarks
Since 2.8.0

property maxExcluded

maxExcluded?: boolean;

Should the upper bound (aka max) be excluded? Note: Excluding max=Number.POSITIVE_INFINITY would result into having max set to Number.MAX_VALUE.
Remarks
Since 3.12.0

property min

min?: number;

Lower bound for the generated 64-bit floats (included, see minExcluded to exclude it)
Remarks
Since 2.8.0

property minExcluded

minExcluded?: boolean;

Should the lower bound (aka min) be excluded? Note: Excluding min=Number.NEGATIVE_INFINITY would result into having min set to -Number.MAX_VALUE.
Remarks
Since 3.12.0

property noDefaultInfinity

noDefaultInfinity?: boolean;

By default, lower and upper bounds are -infinity and +infinity. By setting noDefaultInfinity to true, you move those defaults to minimal and maximal finite values.
Remarks
Since 2.8.0

property noInteger

noInteger?: boolean;

When set to true, Number.isInteger(value) will be false for any generated value. Note: -infinity and +infinity, or NaN can stil be generated except if you rejected them via another constraint.
Remarks
Since 3.18.0

property noNaN

noNaN?: boolean;

When set to true, no more Number.NaN can be generated.
Remarks
Since 2.8.0

interface EmailAddressConstraints

interface EmailAddressConstraints {}

Constraints to be applied on emailAddress
Remarks
Since 2.22.0
Modifiers
- @public

property size

size?: Exclude<SizeForArbitrary, 'max'>;

Define how large the generated values should be (at max)
Remarks
Since 2.22.0

interface ExecutionTree

interface ExecutionTree<Ts> {}

Summary of the execution process
Remarks
Since 1.9.0
Modifiers
- @public

property children

children: ExecutionTree<Ts>[];

Values derived from this value
Remarks
Since 1.9.0

property status

status: ExecutionStatus;

Status of the property
Remarks
Since 1.9.0

property value

value: Ts;

Generated value
Remarks
Since 1.9.0

interface FalsyContraints

interface FalsyContraints {}

Constraints to be applied on falsy
Remarks
Since 1.26.0
Modifiers
- @public

property withBigInt

withBigInt?: boolean;

Enable falsy bigint value
Remarks
Since 1.26.0

interface FloatConstraints

interface FloatConstraints {}

Constraints to be applied on float
Remarks
Since 2.6.0
Modifiers
- @public

property max

max?: number;

Upper bound for the generated 32-bit floats (included)
Remarks
Since 2.8.0

property maxExcluded

maxExcluded?: boolean;

Should the upper bound (aka max) be excluded? Note: Excluding max=Number.POSITIVE_INFINITY would result into having max set to 3.4028234663852886e+38.
Remarks
Since 3.12.0

property min

min?: number;

Lower bound for the generated 32-bit floats (included)
Remarks
Since 2.8.0

property minExcluded

minExcluded?: boolean;

Should the lower bound (aka min) be excluded? Note: Excluding min=Number.NEGATIVE_INFINITY would result into having min set to -3.4028234663852886e+38.
Remarks
Since 3.12.0

property noDefaultInfinity

noDefaultInfinity?: boolean;

By default, lower and upper bounds are -infinity and +infinity. By setting noDefaultInfinity to true, you move those defaults to minimal and maximal finite values.
Remarks
Since 2.8.0

property noInteger

noInteger?: boolean;

When set to true, Number.isInteger(value) will be false for any generated value. Note: -infinity and +infinity, or NaN can stil be generated except if you rejected them via another constraint.
Remarks
Since 3.18.0

property noNaN

noNaN?: boolean;

When set to true, no more Number.NaN can be generated.
Remarks
Since 2.8.0

interface IAsyncProperty

interface IAsyncProperty<Ts> extends IRawProperty<Ts, true> {}

Interface for asynchronous property, see IRawProperty
Remarks
Since 1.19.0
Modifiers
- @public

interface IAsyncPropertyWithHooks

interface IAsyncPropertyWithHooks<Ts> extends IAsyncProperty<Ts> {}

Interface for asynchronous property defining hooks, see IAsyncProperty
Remarks
Since 2.2.0
Modifiers
- @public

method afterEach

afterEach: (
    hookFunction: AsyncPropertyHookFunction
) => IAsyncPropertyWithHooks<Ts>;

Define a function that should be called after all calls to the predicate
Parameter hookFunction
Function to be called
Remarks
Since 1.6.0

method beforeEach

beforeEach: (
    hookFunction: AsyncPropertyHookFunction
) => IAsyncPropertyWithHooks<Ts>;

Define a function that should be called before all calls to the predicate
Parameter hookFunction
Function to be called
Remarks
Since 1.6.0

interface ICommand

interface ICommand<
    Model extends object,
    Real,
    RunResult,
    CheckAsync extends boolean = false
> {}

Interface that should be implemented in order to define a command
Remarks
Since 1.5.0
Modifiers
- @public

method check

check: (
    m: Readonly<Model>
) => CheckAsync extends false ? boolean : Promise<boolean>;

Check if the model is in the right state to apply the command
WARNING: does not change the model
Parameter m
Model, simplified or schematic representation of real system
Remarks
Since 1.5.0

method run

run: (m: Model, r: Real) => RunResult;

Receive the non-updated model and the real or system under test. Perform the checks post-execution - Throw in case of invalid state. Update the model accordingly
Parameter m
Model, simplified or schematic representation of real system
Parameter r
Sytem under test
Remarks
Since 1.5.0

method toString

toString: () => string;

Name of the command
Remarks
Since 1.5.0

interface IntegerConstraints

interface IntegerConstraints {}

Constraints to be applied on integer
Remarks
Since 2.6.0
Modifiers
- @public

property max

max?: number;

Upper bound for the generated integers (included)
Remarks
Since 2.6.0

property min

min?: number;

Lower bound for the generated integers (included)
Remarks
Since 2.6.0

interface IProperty

interface IProperty<Ts> extends IRawProperty<Ts, false> {}

Interface for synchronous property, see IRawProperty
Remarks
Since 1.19.0
Modifiers
- @public

interface IPropertyWithHooks

interface IPropertyWithHooks<Ts> extends IProperty<Ts> {}

Interface for synchronous property defining hooks, see IProperty
Remarks
Since 2.2.0
Modifiers
- @public

method afterEach

afterEach: {
    (
        invalidHookFunction: (
            hookFunction: GlobalPropertyHookFunction
        ) => Promise<unknown>
    ): 'afterEach expects a synchronous function but was given a function returning a Promise';
    (hookFunction: PropertyHookFunction): IPropertyWithHooks<Ts>;
};

Define a function that should be called after all calls to the predicate
Parameter invalidHookFunction
Function to be called, please provide a valid hook function
Remarks
Since 1.6.0
Define a function that should be called after all calls to the predicate
Parameter hookFunction
Function to be called
Remarks
Since 1.6.0

method beforeEach

beforeEach: {
    (
        invalidHookFunction: (
            hookFunction: GlobalPropertyHookFunction
        ) => Promise<unknown>
    ): 'beforeEach expects a synchronous function but was given a function returning a Promise';
    (hookFunction: PropertyHookFunction): IPropertyWithHooks<Ts>;
};

Define a function that should be called before all calls to the predicate
Parameter invalidHookFunction
Function to be called, please provide a valid hook function
Remarks
Since 1.6.0
Define a function that should be called before all calls to the predicate
Parameter hookFunction
Function to be called
Remarks
Since 1.6.0

interface IRawProperty

interface IRawProperty<Ts, IsAsync extends boolean = boolean> {}

Property
A property is the combination of: - Arbitraries: how to generate the inputs for the algorithm - Predicate: how to confirm the algorithm succeeded?
Remarks
Since 1.19.0
Modifiers
- @public

property runAfterEach

runAfterEach: () =>
    | (IsAsync extends true ? Promise<void> : never)
    | (IsAsync extends false ? void : never);

Run after each hook
Remarks
Since 3.4.0

property runBeforeEach

runBeforeEach: () =>
    | (IsAsync extends true ? Promise<void> : never)
    | (IsAsync extends false ? void : never);

Run before each hook
Remarks
Since 3.4.0

method generate

generate: (mrng: Random, runId?: number) => Value<Ts>;

Generate values of type Ts
Parameter mrng
Random number generator
Parameter runId
Id of the generation, starting at 0 - if set the generation might be biased
Remarks
Since 0.0.7 (return type changed in 3.0.0)

method isAsync

isAsync: () => IsAsync;

Is the property asynchronous?
true in case of asynchronous property, false otherwise
Remarks
Since 0.0.7

method run

run: (
    v: Ts
) =>
    | (IsAsync extends true
          ? Promise<PreconditionFailure | PropertyFailure | null>
          : never)
    | (IsAsync extends false
          ? PreconditionFailure | PropertyFailure | null
          : never);

Check the predicate for v
Parameter v
Value of which we want to check the predicate
Remarks
Since 0.0.7

method shrink

shrink: (value: Value<Ts>) => Stream<Value<Ts>>;

Shrink value of type Ts
Parameter value
The value to be shrunk, it can be context-less
Remarks
Since 3.0.0

interface JsonSharedConstraints

interface JsonSharedConstraints {}

Shared constraints for: - json, - jsonValue,
Remarks
Since 2.5.0
Modifiers
- @public

property depthSize

depthSize?: DepthSize;

Limit the depth of the object by increasing the probability to generate simple values (defined via values) as we go deeper in the object.
Remarks
Since 2.20.0

property maxDepth

maxDepth?: number;

Maximal depth allowed
Remarks
Since 2.5.0

property noUnicodeString

noUnicodeString?: boolean;

Only generate instances having keys and values made of ascii strings (when true)
Remarks
Since 3.19.0
Deprecated
Prefer using stringUnit to customize the kind of strings that will be generated by default.

property stringUnit

stringUnit?: StringConstraints['unit'];

Replace the default unit for strings.
Remarks
Since 3.23.0

interface LetrecTypedTie

interface LetrecTypedTie<T> {}

Strongly typed type for the tie function passed by letrec to the builder function we pass to it. You may want also want to use its loosely typed version LetrecLooselyTypedTie.
Remarks
Since 3.0.0
Modifiers
- @public

call signature

<K extends keyof T>(key: K): Arbitrary<T[K]>;

call signature

(key: string): Arbitrary<unknown>;

interface LoremConstraints

interface LoremConstraints {}

Constraints to be applied on lorem
Remarks
Since 2.5.0
Modifiers
- @public

property maxCount

maxCount?: number;

Maximal number of entities: - maximal number of words in case mode is 'words' - maximal number of sentences in case mode is 'sentences'
Remarks
Since 2.5.0

property mode

mode?: 'words' | 'sentences';

Type of strings that should be produced by lorem: - words: multiple words - sentences: multiple sentences
Remarks
Since 2.5.0

property size

size?: SizeForArbitrary;

Define how large the generated values should be (at max)
Remarks
Since 2.22.0

interface MapConstraints

interface MapConstraints {}

Constraints to be applied on map
Remarks
Since 4.4.0
Modifiers
- @public

property depthIdentifier

depthIdentifier?: DepthIdentifier | string;

Depth identifier can be used to share the current depth between several instances.
By default, if not specified, each instance of map will have its own depth. In other words: you can have depth=1 in one while you have depth=100 in another one.
Remarks
Since 4.4.0

property maxKeys

maxKeys?: number;

Upper bound for the number of entries defined into the generated instance
Remarks
Since 4.4.0

property minKeys

minKeys?: number;

Lower bound for the number of entries defined into the generated instance
Remarks
Since 4.4.0

property size

size?: SizeForArbitrary;

Define how large the generated values should be (at max)
Remarks
Since 4.4.0

interface MixedCaseConstraints

interface MixedCaseConstraints {}

Constraints to be applied on mixedCase
Remarks
Since 1.17.0
Modifiers
- @public

property toggleCase

toggleCase?: (rawChar: string) => string;

Transform a character to its upper and/or lower case version
Remarks
Since 1.17.0

property untoggleAll

untoggleAll?: (toggledString: string) => string;

In order to be fully reversable (only in case you want to shrink user definable values) you should provide a function taking a string containing possibly toggled items and returning its untoggled version.

interface NatConstraints

interface NatConstraints {}

Constraints to be applied on nat
Remarks
Since 2.6.0
Modifiers
- @public

property max

max?: number;

Upper bound for the generated postive integers (included)
Remarks
Since 2.6.0

interface ObjectConstraints

interface ObjectConstraints {}

Constraints for anything and object
Modifiers
- @public

property depthSize

depthSize?: DepthSize;

Limit the depth of the object by increasing the probability to generate simple values (defined via values) as we go deeper in the object.
Remarks
Since 2.20.0

property key

key?: Arbitrary<string>;

Arbitrary for keys
Remarks
Since 0.0.7

property maxDepth

maxDepth?: number;

Maximal depth allowed
Remarks
Since 0.0.7

property maxKeys

maxKeys?: number;

Maximal number of keys
Remarks
Since 1.13.0

property size

size?: SizeForArbitrary;

Define how large the generated values should be (at max)
Remarks
Since 2.22.0

property stringUnit

stringUnit?: StringConstraints['unit'];

Replace the default unit for strings.
Remarks
Since 3.23.0

property values

values?: Arbitrary<unknown>[];

Arbitrary for values
Remarks
Since 0.0.7

property withBigInt

withBigInt?: boolean;

Also generate BigInt
Remarks
Since 1.26.0

property withBoxedValues

withBoxedValues?: boolean;

Also generate boxed versions of values
Remarks
Since 1.11.0

property withDate

withDate?: boolean;

Also generate Date
Remarks
Since 2.5.0

property withMap

withMap?: boolean;

Also generate Map
Remarks
Since 1.11.0

property withNullPrototype

withNullPrototype?: boolean;

Also generate object with null prototype
Remarks
Since 1.23.0

property withObjectString

withObjectString?: boolean;

Also generate string representations of object instances
Remarks
Since 1.17.0

property withSet

withSet?: boolean;

Also generate Set
Remarks
Since 1.11.0

property withSparseArray

withSparseArray?: boolean;

Also generate sparse arrays (arrays with holes)
Remarks
Since 2.13.0

property withTypedArray

withTypedArray?: boolean;

Also generate typed arrays in: (Uint|Int)(8|16|32)Array and Float(32|64)Array Remark: no typed arrays made of bigint
Remarks
Since 2.9.0

property withUnicodeString

withUnicodeString?: boolean;

Replace the arbitrary of strings defaulted for key and values by one able to generate unicode strings with non-ascii characters. If you override key and/or values constraint, this flag will not apply to your override.
Remarks
Since 3.19.0
Deprecated
Prefer using stringUnit to customize the kind of strings that will be generated by default.

interface OptionConstraints

interface OptionConstraints<TNil = null> {}

Constraints to be applied on option
Remarks
Since 2.2.0
Modifiers
- @public

property depthIdentifier

depthIdentifier?: DepthIdentifier | string;

Depth identifier can be used to share the current depth between several instances.
By default, if not specified, each instance of option will have its own depth. In other words: you can have depth=1 in one while you have depth=100 in another one.
Remarks
Since 2.14.0

property depthSize

depthSize?: DepthSize;

While going deeper and deeper within a recursive structure (see letrec), this factor will be used to increase the probability to generate nil.
Remarks
Since 2.14.0

property freq

freq?: number;

The probability to build a nil value is of 1 / freq.
Remarks
Since 1.17.0

property maxDepth

maxDepth?: number;

Maximal authorized depth. Once this depth has been reached only nil will be used.
Remarks
Since 2.14.0

property nil

nil?: TNil;

The nil value
Remarks
Since 1.17.0

interface Parameters

interface Parameters<T = void> {}

Customization of the parameters used to run the properties
Remarks
Since 0.0.6
Modifiers
- @public

property asyncReporter

asyncReporter?: (runDetails: RunDetails<T>) => Promise<void>;

Replace the default reporter handling errors by a custom one
Reporter is responsible to throw in case of failure: default one throws whenever runDetails.failed is true. But you may want to change this behaviour in yours.
Only used when calling assert Cannot be defined in conjonction with reporter Not compatible with synchronous properties: runner will throw
Remarks
Since 1.25.0

property endOnFailure

endOnFailure?: boolean;

Stop run on failure
It makes the run stop at the first encountered failure without shrinking.
When used in complement to seed and path, it replays only the minimal counterexample.
Remarks
Since 1.11.0

property examples

examples?: T[];

Custom values added at the beginning of generated ones
It enables users to come with examples they want to test at every run
Remarks
Since 1.4.0

property ignoreEqualValues

ignoreEqualValues?: boolean;

Discard runs corresponding to already tried values.
WARNING: Discarded runs will not be replaced. In other words, if you ask for 100 runs and have 2 discarded runs you will only have 98 effective runs.
NOTE: Relies on fc.stringify to check the equality.
Remarks
Since 2.14.0

property includeErrorInReport

includeErrorInReport?: boolean;

By default the Error causing the failure of the predicate will not be directly exposed within the message of the Error thown by fast-check. It will be exposed by a cause field attached to the Error.
The Error with cause has been supported by Node since 16.14.0 and is properly supported in many test runners.
But if the original Error fails to appear within your test runner, Or if you prefer the Error to be included directly as part of the message of the resulted Error, you can toggle this flag and the Error produced by fast-check in case of failure will expose the source Error as part of the message and not as a cause.

property interruptAfterTimeLimit

interruptAfterTimeLimit?: number;

Interrupt test execution after a given time limit: disabled by default
NOTE: Relies on Date.now().
NOTE: Useful to avoid having too long running processes in your CI. Replay capability (see seed, path) can still be used if needed.
WARNING: If the test got interrupted before any failure occured and before it reached the requested number of runs specified by numRuns it will be marked as success. Except if markInterruptAsFailure has been set to true
Remarks
Since 1.19.0

property markInterruptAsFailure

markInterruptAsFailure?: boolean;

Mark interrupted runs as failed runs if preceded by one success or more: disabled by default Interrupted with no success at all always defaults to failure whatever the value of this flag.
Remarks
Since 1.19.0

property maxSkipsPerRun

maxSkipsPerRun?: number;

Maximal number of skipped values per run
Skipped is considered globally, so this value is used to compute maxSkips = maxSkipsPerRun * numRuns. Runner will consider a run to have failed if it skipped maxSkips+1 times before having generated numRuns valid entries.
See pre for more details on pre-conditions
Remarks
Since 1.3.0

property numRuns

numRuns?: number;

Number of runs before success: 100 by default
Remarks
Since 1.0.0

property path

path?: string;

Way to replay a failing property directly with the counterexample. It can be fed with the counterexamplePath returned by the failing test (requires seed too).
Remarks
Since 1.0.0

property randomType

randomType?: RandomType | ((seed: number) => RandomGenerator);

Random number generator: xorshift128plus by default
Random generator is the core element behind the generation of random values - changing it might directly impact the quality and performances of the generation of random values. It can be one of: 'mersenne', 'congruential', 'congruential32', 'xorshift128plus', 'xoroshiro128plus' Or any function able to build a RandomGenerator based on a seed
As required since pure-rand v6.0.0, when passing a builder for RandomGenerator, the random number generator must generate values between -0x80000000 and 0x7fffffff.
Remarks
Since 1.6.0

property reporter

reporter?: (runDetails: RunDetails<T>) => void;

Replace the default reporter handling errors by a custom one
Reporter is responsible to throw in case of failure: default one throws whenever runDetails.failed is true. But you may want to change this behaviour in yours.
Only used when calling assert Cannot be defined in conjonction with asyncReporter
Remarks
Since 1.25.0

property seed

seed?: number;

Initial seed of the generator: Date.now() by default
It can be forced to replay a failed run.
In theory, seeds are supposed to be 32-bit integers. In case of double value, the seed will be rescaled into a valid 32-bit integer (eg.: values between 0 and 1 will be evenly spread into the range of possible seeds).
Remarks
Since 0.0.6

property skipAllAfterTimeLimit

skipAllAfterTimeLimit?: number;

Skip all runs after a given time limit: disabled by default
NOTE: Relies on Date.now().
NOTE: Useful to stop too long shrinking processes. Replay capability (see seed, path) can resume the shrinking.
WARNING: It skips runs. Thus test might be marked as failed. Indeed, it might not reached the requested number of successful runs.
Remarks
Since 1.15.0

property skipEqualValues

skipEqualValues?: boolean;

Skip runs corresponding to already tried values.
WARNING: Discarded runs will be retried. Under the hood they are simple calls to fc.pre. In other words, if you ask for 100 runs but your generator can only generate 10 values then the property will fail as 100 runs will never be reached. Contrary to ignoreEqualValues you always have the number of runs you requested.
NOTE: Relies on fc.stringify to check the equality.
Remarks
Since 2.14.0

property timeout

timeout?: number;

Maximum time in milliseconds for the predicate to answer: disabled by default
WARNING: Only works for async code (see asyncProperty), will not interrupt a synchronous code.
Remarks
Since 0.0.11

property unbiased

unbiased?: boolean;

Force the use of unbiased arbitraries: biased by default
Remarks
Since 1.1.0

property verbose

verbose?: boolean | VerbosityLevel;

Enable verbose mode: VerbosityLevel.None by default
Using verbose: true is equivalent to verbose: VerbosityLevel.Verbose
It can prove very useful to troubleshoot issues. See VerbosityLevel for more details on each level.
Remarks
Since 1.1.0

method logger

logger: (v: string) => void;

Logger (see statistics): console.log by default
Remarks
Since 0.0.6

interface RunDetailsCommon

interface RunDetailsCommon<Ts> {}

Shared part between variants of RunDetails
Remarks
Since 2.2.0
Modifiers
- @public

property counterexample

counterexample: Ts | null;

In case of failure: the counterexample contains the minimal failing case (first failure after shrinking)
Remarks
Since 0.0.7

property counterexamplePath

counterexamplePath: string | null;

In case of failure: path to the counterexample
For replay purposes, it can be forced in assert, check, sample and statistics using Parameters
Remarks
Since 1.0.0

property errorInstance

errorInstance: unknown | null;

In case of failure: it contains the error that has been thrown if any
Remarks
Since 3.0.0

property executionSummary

executionSummary: ExecutionTree<Ts>[];

Execution summary of the run
Traces the origin of each value encountered during the test and its execution status. Can help to diagnose shrinking issues.
You must enable verbose with at least Verbosity.Verbose in Parameters in order to have values in it: - Verbose: Only failures - VeryVerbose: Failures, Successes and Skipped
Remarks
Since 1.9.0

property failed

failed: boolean;

Does the property failed during the execution of check?
Remarks
Since 0.0.7

property failures

failures: Ts[];

List all failures that have occurred during the run
You must enable verbose with at least Verbosity.Verbose in Parameters in order to have values in it
Remarks
Since 1.1.0

property interrupted

interrupted: boolean;

Was the execution interrupted?
Remarks
Since 1.19.0

property numRuns

numRuns: number;

Number of runs
- In case of failed property: Number of runs up to the first failure (including the failure run) - Otherwise: Number of successful executions
Remarks
Since 1.0.0

property numShrinks

numShrinks: number;

Number of shrinks required to get to the minimal failing case (aka counterexample)
Remarks
Since 1.0.0

property numSkips

numSkips: number;

Number of skipped entries due to failed pre-condition
As numRuns it only takes into account the skipped values that occured before the first failure. Refer to pre to add such pre-conditions.
Remarks
Since 1.3.0

property runConfiguration

runConfiguration: Parameters<Ts>;

Configuration of the run
It includes both local parameters set on check or assert and global ones specified using configureGlobal
Remarks
Since 1.25.0

property seed

seed: number;

Seed that have been used by the run
It can be forced in assert, check, sample and statistics using Parameters
Remarks
Since 0.0.7

property verbose

verbose: VerbosityLevel;

Verbosity level required by the user
Remarks
Since 1.9.0

interface RunDetailsFailureInterrupted

interface RunDetailsFailureInterrupted<Ts> extends RunDetailsCommon<Ts> {}

Run reported as failed because it took too long and thus has been interrupted
Refer to RunDetailsCommon for more details
Remarks
Since 1.25.0
Modifiers
- @public

property counterexample

counterexample: null;

property counterexamplePath

counterexamplePath: null;

property errorInstance

errorInstance: null;

property failed

failed: true;

property interrupted

interrupted: true;

interface RunDetailsFailureProperty

interface RunDetailsFailureProperty<Ts> extends RunDetailsCommon<Ts> {}

Run reported as failed because the property failed
Refer to RunDetailsCommon for more details
Remarks
Since 1.25.0
Modifiers
- @public

property counterexample

counterexample: Ts;

property counterexamplePath

counterexamplePath: string;

property errorInstance

errorInstance: unknown;

property failed

failed: true;

property interrupted

interrupted: boolean;

interface RunDetailsFailureTooManySkips

interface RunDetailsFailureTooManySkips<Ts> extends RunDetailsCommon<Ts> {}

Run reported as failed because too many retries have been attempted to generate valid values
Refer to RunDetailsCommon for more details
Remarks
Since 1.25.0
Modifiers
- @public

property counterexample

counterexample: null;

property counterexamplePath

counterexamplePath: null;

property errorInstance

errorInstance: null;

property failed

failed: true;

property interrupted

interrupted: false;

interface RunDetailsSuccess

interface RunDetailsSuccess<Ts> extends RunDetailsCommon<Ts> {}

Run reported as success
Refer to RunDetailsCommon for more details
Remarks
Since 1.25.0
Modifiers
- @public

property counterexample

counterexample: null;

property counterexamplePath

counterexamplePath: null;

property errorInstance

errorInstance: null;

property failed

failed: false;

property interrupted

interrupted: boolean;

interface Scheduler

interface Scheduler<TMetaData = unknown> {}

Instance able to reschedule the ordering of promises for a given app
Remarks
Since 1.20.0
Modifiers
- @public

property report

report: () => SchedulerReportItem<TMetaData>[];

Produce an array containing all the scheduled tasks so far with their execution status. If the task has been executed, it includes a string representation of the associated output or error produced by the task if any.
Tasks will be returned in the order they get executed by the scheduler.
Remarks
Since 1.25.0

property schedule

schedule: <T>(
    task: Promise<T>,
    label?: string,
    metadata?: TMetaData,
    customAct?: SchedulerAct
) => Promise<T>;

Wrap a new task using the Scheduler
Remarks
Since 1.20.0

property scheduleFunction

scheduleFunction: <TArgs extends any[], T>(
    asyncFunction: (...args: TArgs) => Promise<T>,
    customAct?: SchedulerAct
) => (...args: TArgs) => Promise<T>;

Automatically wrap function output using the Scheduler
Remarks
Since 1.20.0

property waitAll

waitAll: (customAct?: SchedulerAct) => Promise<void>;

Wait all scheduled tasks, including the ones that might be created by one of the resolved task
Remarks
Since 1.20.0
Deprecated
Use waitIdle() instead, it comes with a more predictable behavior awaiting all scheduled and reachable tasks to be completed

property waitFor

waitFor: <T>(
    unscheduledTask: Promise<T>,
    customAct?: SchedulerAct
) => Promise<T>;

Wait as many scheduled tasks as need to resolve the received Promise
Some tests frameworks like supertest are not triggering calls to subsequent queries in a synchronous way, some are waiting an explicit call to then to trigger them (either synchronously or asynchronously)... As a consequence, none of waitOne or waitAll cannot wait for them out-of-the-box.
This helper is responsible to wait as many scheduled tasks as needed (but the bare minimal) to get unscheduledTask resolved. Once resolved it returns its output either success or failure.
Be aware that while this helper will wait eveything to be ready for unscheduledTask to resolve, having uncontrolled tasks triggering stuff required for unscheduledTask might be a source a uncontrollable and not reproducible randomness as those triggers cannot be handled and scheduled by fast-check.
Remarks
Since 2.24.0

property waitIdle

waitIdle: (customAct?: SchedulerAct) => Promise<void>;

Wait until the scheduler becomes idle: all scheduled and reachable tasks have completed.
It will include tasks scheduled by other tasks, recursively.
Note: Tasks triggered by uncontrolled sources (like fetch or external events) cannot be detected or awaited and may lead to incomplete waits.
If you want to wait for a precise event to happen you should rather opt for waitFor or waitNext given they offer you a more granular control on what you are exactly waiting for.
Remarks
Since 4.2.0

property waitNext

waitNext: (count: number, customAct?: SchedulerAct) => Promise<void>;

Wait and schedule exactly count scheduled tasks.
Remarks
Since 4.2.0

property waitOne

waitOne: (customAct?: SchedulerAct) => Promise<void>;

Wait one scheduled task to be executed
Throws
Whenever there is no task scheduled
Remarks
Since 1.20.0
Deprecated
Use waitNext(1) instead, it comes with a more predictable behavior

method count

count: () => number;

Count of pending scheduled tasks
Remarks
Since 1.20.0

method scheduleSequence

scheduleSequence: (
    sequenceBuilders: SchedulerSequenceItem<TMetaData>[],
    customAct?: SchedulerAct
) => {
    done: boolean;
    faulty: boolean;
    task: Promise<{ done: boolean; faulty: boolean }>;
};

Schedule a sequence of Promise to be executed sequencially. Items within the sequence might be interleaved by other scheduled operations.
Please note that whenever an item from the sequence has started, the scheduler will wait until its end before moving to another scheduled task.
A handle is returned by the function in order to monitor the state of the sequence. Sequence will be marked: - done if all the promises have been executed properly - faulty if one of the promises within the sequence throws
Remarks
Since 1.20.0

interface SchedulerConstraints

interface SchedulerConstraints {}

Constraints to be applied on scheduler
Remarks
Since 2.2.0
Modifiers
- @public

property act

act: (f: () => Promise<void>) => Promise<unknown>;

Ensure that all scheduled tasks will be executed in the right context (for instance it can be the act of React)
Remarks
Since 1.21.0

interface SchedulerReportItem

interface SchedulerReportItem<TMetaData = unknown> {}

Describe a task for the report produced by the scheduler
Remarks
Since 1.25.0
Modifiers
- @public

property label

label: string;

Label of the task
Remarks
Since 1.25.0

property metadata

metadata?: TMetaData;

Metadata linked when scheduling the task
Remarks
Since 1.25.0

property outputValue

outputValue?: string;

Stringified version of the output or error computed using fc.stringify
Remarks
Since 1.25.0

property schedulingType

schedulingType: 'promise' | 'function' | 'sequence';

How was this task scheduled? - promise: schedule - function: scheduleFunction - sequence: scheduleSequence
Remarks
Since 1.25.0

property status

status: 'resolved' | 'rejected' | 'pending';

Execution status for this task - resolved: task released by the scheduler and successful - rejected: task released by the scheduler but with errors - pending: task still pending in the scheduler, not released yet
Remarks
Since 1.25.0

property taskId

taskId: number;

Incremental id for the task, first received task has taskId = 1
Remarks
Since 1.25.0

interface ShuffledSubarrayConstraints

interface ShuffledSubarrayConstraints {}

Constraints to be applied on shuffledSubarray
Remarks
Since 2.18.0
Modifiers
- @public

property maxLength

maxLength?: number;

Upper bound of the generated subarray size (included)
Remarks
Since 2.4.0

property minLength

minLength?: number;

Lower bound of the generated subarray size (included)
Remarks
Since 2.4.0

interface SparseArrayConstraints

interface SparseArrayConstraints {}

Constraints to be applied on sparseArray
Remarks
Since 2.13.0
Modifiers
- @public

property depthIdentifier

depthIdentifier?: DepthIdentifier | string;

When receiving a depth identifier, the arbitrary will impact the depth attached to it to avoid going too deep if it already generated lots of items.
In other words, if the number of generated values within the collection is large then the generated items will tend to be less deep to avoid creating structures a lot larger than expected.
For the moment, the depth is not taken into account to compute the number of items to define for a precise generate call of the array. Just applied onto eligible items.
Remarks
Since 2.25.0

property maxLength

maxLength?: number;

Upper bound of the generated array size (maximal size: 4294967295)
Remarks
Since 2.13.0

property maxNumElements

maxNumElements?: number;

Upper bound of the number of non-hole elements
Remarks
Since 2.13.0

property minNumElements

minNumElements?: number;

Lower bound of the number of non-hole elements
Remarks
Since 2.13.0

property noTrailingHole

noTrailingHole?: boolean;

When enabled, all generated arrays will either be the empty array or end by a non-hole
Remarks
Since 2.13.0

property size

size?: SizeForArbitrary;

Define how large the generated values should be (at max)
Remarks
Since 2.22.0

interface StringSharedConstraints

interface StringSharedConstraints {}

Constraints to be applied on arbitraries for strings
Remarks
Since 2.4.0
Modifiers
- @public

property maxLength

maxLength?: number;

Upper bound of the generated string length (included)
Remarks
Since 2.4.0

property minLength

minLength?: number;

Lower bound of the generated string length (included)
Remarks
Since 2.4.0

property size

size?: SizeForArbitrary;

Define how large the generated values should be (at max)
Remarks
Since 2.22.0

interface SubarrayConstraints

interface SubarrayConstraints {}

Constraints to be applied on subarray
Remarks
Since 2.4.0
Modifiers
- @public

property maxLength

maxLength?: number;

Upper bound of the generated subarray size (included)
Remarks
Since 2.4.0

property minLength

minLength?: number;

Lower bound of the generated subarray size (included)
Remarks
Since 2.4.0

interface UuidConstraints

interface UuidConstraints {}

Constraints to be applied on uuid
Remarks
Since 3.21.0
Modifiers
- @public

property version

version?:
    | (1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15)
    | (1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15)[];

Define accepted versions in the [1-15] according to RFC 9562
Remarks
Since 3.21.0

interface WebAuthorityConstraints

interface WebAuthorityConstraints {}

Constraints to be applied on webAuthority
Remarks
Since 1.14.0
Modifiers
- @public

property size

size?: Exclude<SizeForArbitrary, 'max'>;

Define how large the generated values should be (at max)
Remarks
Since 2.22.0

property withIPv4

withIPv4?: boolean;

Enable IPv4 in host
Remarks
Since 1.14.0

property withIPv4Extended

withIPv4Extended?: boolean;

Enable extended IPv4 format
Remarks
Since 1.17.0

property withIPv6

withIPv6?: boolean;

Enable IPv6 in host
Remarks
Since 1.14.0

property withPort

withPort?: boolean;

Enable port suffix
Remarks
Since 1.14.0

property withUserInfo

withUserInfo?: boolean;

Enable user information prefix
Remarks
Since 1.14.0

interface WebFragmentsConstraints

interface WebFragmentsConstraints {}

Constraints to be applied on webFragments
Remarks
Since 2.22.0
Modifiers
- @public

property size

size?: Exclude<SizeForArbitrary, 'max'>;

Define how large the generated values should be (at max)
Remarks
Since 2.22.0

interface WebPathConstraints

interface WebPathConstraints {}

Constraints to be applied on webPath
Remarks
Since 3.3.0
Modifiers
- @public

property size

size?: Exclude<SizeForArbitrary, 'max'>;

Define how large the generated values should be (at max)
Remarks
Since 3.3.0

interface WebQueryParametersConstraints

interface WebQueryParametersConstraints {}

Constraints to be applied on webQueryParameters
Remarks
Since 2.22.0
Modifiers
- @public

property size

size?: Exclude<SizeForArbitrary, 'max'>;

Define how large the generated values should be (at max)
Remarks
Since 2.22.0

interface WebSegmentConstraints

interface WebSegmentConstraints {}

Constraints to be applied on webSegment
Remarks
Since 2.22.0
Modifiers
- @public

property size

size?: Exclude<SizeForArbitrary, 'max'>;

Define how large the generated values should be (at max)
Remarks
Since 2.22.0

interface WebUrlConstraints

interface WebUrlConstraints {}

Constraints to be applied on webUrl
Remarks
Since 1.14.0
Modifiers
- @public

property authoritySettings

authoritySettings?: WebAuthorityConstraints;

Settings for webAuthority
Remarks
Since 1.14.0

property size

size?: Exclude<SizeForArbitrary, 'max'>;

Define how large the generated values should be (at max)
Remarks
Since 2.22.0

property validSchemes

validSchemes?: string[];

Enforce specific schemes, eg.: http, https
Remarks
Since 1.14.0

property withFragments

withFragments?: boolean;

Enable fragments in the generated url
Remarks
Since 1.14.0

property withQueryParameters

withQueryParameters?: boolean;

Enable query parameters in the generated url
Remarks
Since 1.14.0

interface WeightedArbitrary

interface WeightedArbitrary<T> {}

Conjonction of a weight and an arbitrary used by oneof in order to generate values
Remarks
Since 1.18.0
Modifiers
- @public

property arbitrary

arbitrary: Arbitrary<T>;

Instance of Arbitrary
Remarks
Since 0.0.7

property weight

weight: number;

Weight to be applied when selecting which arbitrary should be used
Remarks
Since 0.0.7

interface WithCloneMethod

interface WithCloneMethod<T> {}

Object instance that should be cloned from one generation/shrink to another
Remarks
Since 2.15.0
Modifiers
- @public

property [cloneMethod]

[cloneMethod]: () => T;

Enums

enum ExecutionStatus

enum ExecutionStatus {
    Success = 0,
    Skipped = -1,
    Failure = 1,
}

Status of the execution of the property
Remarks
Since 1.9.0
Modifiers
- @public

member Failure

Failure = 1

member Skipped

Skipped = -1

member Success

Success = 0

enum VerbosityLevel

enum VerbosityLevel {
    None = 0,
    Verbose = 1,
    VeryVerbose = 2,
}

Verbosity level
Remarks
Since 1.9.1
Modifiers
- @public

member None

None = 0

Level 0 (default)
Minimal reporting: - minimal failing case - error log corresponding to the minimal failing case
Remarks
Since 1.9.1

member Verbose

Verbose = 1

Level 1
Failures reporting: - same as VerbosityLevel.None - list all the failures encountered during the shrinking process
Remarks
Since 1.9.1

member VeryVerbose

VeryVerbose = 2

Level 2
Execution flow reporting: - same as VerbosityLevel.None - all runs with their associated status displayed as a tree
Remarks
Since 1.9.1

Type Aliases

type AsyncPropertyHookFunction

type AsyncPropertyHookFunction =
    | ((previousHookFunction: GlobalAsyncPropertyHookFunction) => Promise<unknown>)
    | ((previousHookFunction: GlobalAsyncPropertyHookFunction) => void);

Type of legal hook function that can be used to call beforeEach or afterEach on a IAsyncPropertyWithHooks
Remarks
Since 2.2.0
Modifiers
- @public

type BigIntArrayConstraints

type BigIntArrayConstraints = {
    /**
     * Lower bound of the generated array size
     * @defaultValue 0
     * @remarks Since 3.0.0
     */
    minLength?: number;
    /**
     * Upper bound of the generated array size
     * @defaultValue 0x7fffffff — _defaulting seen as "max non specified" when `defaultSizeToMaxWhenMaxSpecified=true`_
     * @remarks Since 3.0.0
     */
    maxLength?: number;
    /**
     * Lower bound for the generated int (included)
     * @defaultValue smallest possible value for this type
     * @remarks Since 3.0.0
     */
    min?: bigint;
    /**
     * Upper bound for the generated int (included)
     * @defaultValue highest possible value for this type
     * @remarks Since 3.0.0
     */
    max?: bigint;
    /**
     * Define how large the generated values should be (at max)
     * @remarks Since 3.0.0
     */
    size?: SizeForArbitrary;
};

Constraints to be applied on typed arrays for big int values
Remarks
Since 3.0.0
Modifiers
- @public

type CloneValue

type CloneValue<T, N extends number, Rest extends T[] = []> = [number] extends [N]
    ? T[]
    : Rest['length'] extends N
    ? Rest
    : CloneValue<T, N, [T, ...Rest]>;

Type of the value produced by clone
Remarks
Since 2.5.0
Modifiers
- @public

type DepthContext

type DepthContext = {
    /**
     * Current depth (starts at 0, continues with 1, 2...).
     * Only made of integer values superior or equal to 0.
     *
     * Remark: Whenever altering the `depth` during a `generate`, please make sure to ALWAYS
     * reset it to its original value before you leave the `generate`. Otherwise the execution
     * will imply side-effects that will potentially impact the following runs and make replay
     * of the issue barely impossible.
     */
    depth: number;
};

Instance of depth, can be used to alter the depth perceived by an arbitrary or to bias your own arbitraries based on the current depth
Remarks
Since 2.25.0
Modifiers
- @public

type DepthIdentifier

type DepthIdentifier = {} & DepthContext;

Type used to strongly type instances of depth identifier while keeping internals what they contain internally
Remarks
Since 2.25.0
Modifiers
- @public

type DepthSize

type DepthSize = RelativeSize | Size | 'max' | number | undefined;

Superset of Size to override the default defined for size. It can either be based on a numeric value manually selected by the user (not recommended) or rely on presets based on size (recommended).
This size will be used to infer a bias to limit the depth, used as follow within recursive structures: While going deeper, the bias on depth will increase the probability to generate small instances.
When used with Size, the larger the size the deeper the structure. When used with numeric values, the larger the number (floating point number >= 0), the deeper the structure. +0 means extremelly biased depth meaning barely impossible to generate deep structures, while Number.POSITIVE_INFINITY means "depth has no impact".
Using max or Number.POSITIVE_INFINITY is fully equivalent.
Remarks
Since 2.25.0
Modifiers
- @public

type EntityGraphArbitraries

type Arbitraries<TEntityFields> = {
    [TEntityName in keyof TEntityFields]: ArbitraryStructure<
        TEntityFields[TEntityName]
    >;
};

Defines all entity types and their data fields for entityGraph.
This is the first argument to entityGraph and specifies the non-relational properties of each entity type. Each key is the name of an entity type and its value defines the arbitraries for that entity.
Remarks
Since 4.5.0
Example 1
{ employee: { name: fc.string(), age: fc.nat(100) }, team: { name: fc.string(), size: fc.nat(50) } }
Modifiers
- @public

type EntityGraphContraints

type EntityGraphContraints<TEntityFields> = {
    /**
     * Controls the minimum number of entities generated for each entity type in the initial pool.
     *
     * The initial pool defines the baseline set of entities that are created before any relationships
     * are established. Other entities may be created later to satisfy relationship requirements.
     *
     * @example
     * ```typescript
     * // Ensure at least 2 employees and at most 5 teams in the initial pool
     * // But possibly more than 5 teams at the end
     * { initialPoolConstraints: { employee: { minLength: 2 }, team: { maxLength: 5 } } }
     * ```
     *
     * @defaultValue When unspecified, defaults from {@link array} are used for each entity type
     * @remarks Since 4.5.0
     */
    initialPoolConstraints?: {
        [EntityName in keyof TEntityFields]?: ArrayConstraints;
    };
    /**
     * Defines uniqueness criteria for entities of each type to prevent duplicate values.
     *
     * The selector function extracts a key from each entity. Entities with identical keys
     * (compared using `Object.is`) are considered duplicates and only one instance will be kept.
     *
     * @example
     * ```typescript
     * // Ensure employees have unique names
     * { unicityConstraints: { employee: (emp) => emp.name } }
     * ```
     *
     * @defaultValue All entities are considered unique (no deduplication is performed)
     * @remarks Since 4.5.0
     */
    unicityConstraints?: {
        [EntityName in keyof TEntityFields]?: UniqueArrayConstraintsRecommended<
            TEntityFields[EntityName],
            unknown
        >['selector'];
    };
    /**
     * Do not generate values with null prototype
     * @defaultValue false
     * @remarks Since 4.5.0
     */
    noNullPrototype?: boolean;
};

Constraints to be applied on entityGraph
Remarks
Since 4.5.0
Modifiers
- @public

type EntityGraphRelations

type EntityRelations<TEntityFields> = {
    [TEntityName in keyof TEntityFields]: {
        [TField in string]: Relationship<keyof TEntityFields>;
    };
};

Defines all relationships between entity types for entityGraph.
This is the second argument to entityGraph and specifies how entities reference each other. Each entity type can have zero or more relationship fields, where each field defines a link to other entities.
Remarks
Since 4.5.0
Example 1
{ employee: { manager: { arity: '0-1', type: 'employee' }, team: { arity: '1', type: 'team' } }, team: {} }
Modifiers
- @public

type EntityGraphValue

type EntityGraphValue<
    TEntityFields,
    TEntityRelations extends EntityRelations<TEntityFields>
> = {
    [TEntityName in keyof EntityGraphSingleValue<
        TEntityFields,
        TEntityRelations
    >]: EntityGraphSingleValue<TEntityFields, TEntityRelations>[TEntityName][];
};

Type of the values generated by entityGraph.
The output is an object where each key is an entity type name and each value is an array of entities of that type. Each entity contains both its data fields (from arbitraries) and relationship fields (from relations), with relationships resolved to actual entity references.
Remarks
Since 4.5.0
Modifiers
- @public

type FalsyValue

type FalsyValue<TConstraints extends FalsyContraints = object> =
    | false
    | null
    | 0
    | ''
    | typeof NaN
    | undefined
    | (TConstraints extends {
          withBigInt: true;
      }
          ? 0n
          : never);

Typing for values generated by falsy
Remarks
Since 2.2.0
Modifiers
- @public

type Float32ArrayConstraints

type Float32ArrayConstraints = {
    /**
     * Lower bound of the generated array size
     * @defaultValue 0
     * @remarks Since 2.9.0
     */
    minLength?: number;
    /**
     * Upper bound of the generated array size
     * @defaultValue 0x7fffffff — _defaulting seen as "max non specified" when `defaultSizeToMaxWhenMaxSpecified=true`_
     * @remarks Since 2.9.0
     */
    maxLength?: number;
    /**
     * Define how large the generated values should be (at max)
     * @remarks Since 2.22.0
     */
    size?: SizeForArbitrary;
} & FloatConstraints;

Constraints to be applied on float32Array
Remarks
Since 2.9.0
Modifiers
- @public

type Float64ArrayConstraints

type Float64ArrayConstraints = {
    /**
     * Lower bound of the generated array size
     * @defaultValue 0
     * @remarks Since 2.9.0
     */
    minLength?: number;
    /**
     * Upper bound of the generated array size
     * @defaultValue 0x7fffffff — _defaulting seen as "max non specified" when `defaultSizeToMaxWhenMaxSpecified=true`_
     * @remarks Since 2.9.0
     */
    maxLength?: number;
    /**
     * Define how large the generated values should be (at max)
     * @remarks Since 2.22.0
     */
    size?: SizeForArbitrary;
} & DoubleConstraints;

Constraints to be applied on float64Array
Remarks
Since 2.9.0
Modifiers
- @public

type GeneratorValue

type GeneratorValue = GeneratorValueFunction & GeneratorValueMethods;

An instance of GeneratorValue can be leveraged within predicates themselves to produce extra random values while preserving part of the shrinking capabilities on the produced values.
It can be seen as a way to start property based testing within something looking closer from what users will think about when thinking about random in tests. But contrary to raw random, it comes with many useful strengths such as: ability to re-run the test (seeded), shrinking...
Remarks
Since 3.8.0
Modifiers
- @public

type GlobalAsyncPropertyHookFunction

type GlobalAsyncPropertyHookFunction = (() => Promise<unknown>) | (() => void);

Type of legal hook function that can be used in the global parameter asyncBeforeEach and/or asyncAfterEach
Remarks
Since 2.3.0
Modifiers
- @public

type GlobalParameters

type GlobalParameters = Pick<
    Parameters<unknown>,
    Exclude<keyof Parameters<unknown>, 'path' | 'examples'>
> & {
    /**
     * Specify a function that will be called before each execution of a property.
     * It behaves as-if you manually called `beforeEach` method on all the properties you execute with fast-check.
     *
     * The function will be used for both {@link fast-check#property} and {@link fast-check#asyncProperty}.
     * This global override should never be used in conjunction with `asyncBeforeEach`.
     *
     * @remarks Since 2.3.0
     */
    beforeEach?: GlobalPropertyHookFunction;
    /**
     * Specify a function that will be called after each execution of a property.
     * It behaves as-if you manually called `afterEach` method on all the properties you execute with fast-check.
     *
     * The function will be used for both {@link fast-check#property} and {@link fast-check#asyncProperty}.
     * This global override should never be used in conjunction with `asyncAfterEach`.
     *
     * @remarks Since 2.3.0
     */
    afterEach?: GlobalPropertyHookFunction;
    /**
     * Specify a function that will be called before each execution of an asynchronous property.
     * It behaves as-if you manually called `beforeEach` method on all the asynchronous properties you execute with fast-check.
     *
     * The function will be used only for {@link fast-check#asyncProperty}. It makes synchronous properties created by {@link fast-check#property} unable to run.
     * This global override should never be used in conjunction with `beforeEach`.
     *
     * @remarks Since 2.3.0
     */
    asyncBeforeEach?: GlobalAsyncPropertyHookFunction;
    /**
     * Specify a function that will be called after each execution of an asynchronous property.
     * It behaves as-if you manually called `afterEach` method on all the asynchronous properties you execute with fast-check.
     *
     * The function will be used only for {@link fast-check#asyncProperty}. It makes synchronous properties created by {@link fast-check#property} unable to run.
     * This global override should never be used in conjunction with `afterEach`.
     *
     * @remarks Since 2.3.0
     */
    asyncAfterEach?: GlobalAsyncPropertyHookFunction;
    /**
     * Define the base size to be used by arbitraries.
     *
     * By default arbitraries not specifying any size will default to it (except in some cases when used defaultSizeToMaxWhenMaxSpecified is true).
     * For some arbitraries users will want to override the default and either define another size relative to this one,
     * or a fixed one.
     *
     * @defaultValue `"small"`
     * @remarks Since 2.22.0
     */
    baseSize?: Size;
    /**
     * When set to `true` and if the size has not been defined for this precise instance,
     * it will automatically default to `"max"` if the user specified a upper bound for the range
     * (applies to length and to depth).
     *
     * When `false`, the size will be defaulted to `baseSize` even if the user specified
     * a upper bound for the range.
     *
     * @remarks Since 2.22.0
     */
    defaultSizeToMaxWhenMaxSpecified?: boolean;
};

Type describing the global overrides
Remarks
Since 1.18.0
Modifiers
- @public

type GlobalPropertyHookFunction

type GlobalPropertyHookFunction = () => void;

Type of legal hook function that can be used in the global parameter beforeEach and/or afterEach
Remarks
Since 2.3.0
Modifiers
- @public

type IntArrayConstraints

type IntArrayConstraints = {
    /**
     * Lower bound of the generated array size
     * @defaultValue 0
     * @remarks Since 2.9.0
     */
    minLength?: number;
    /**
     * Upper bound of the generated array size
     * @defaultValue 0x7fffffff — _defaulting seen as "max non specified" when `defaultSizeToMaxWhenMaxSpecified=true`_
     * @remarks Since 2.9.0
     */
    maxLength?: number;
    /**
     * Lower bound for the generated int (included)
     * @defaultValue smallest possible value for this type
     * @remarks Since 2.9.0
     */
    min?: number;
    /**
     * Upper bound for the generated int (included)
     * @defaultValue highest possible value for this type
     * @remarks Since 2.9.0
     */
    max?: number;
    /**
     * Define how large the generated values should be (at max)
     * @remarks Since 2.22.0
     */
    size?: SizeForArbitrary;
};

Constraints to be applied on typed arrays for integer values
Remarks
Since 2.9.0
Modifiers
- @public

type JsonValue

type JsonValue = boolean | number | string | null | JsonArray | JsonObject;

Typings for a Json value
Remarks
Since 2.20.0
Modifiers
- @public

type LetrecLooselyTypedBuilder

type LetrecLooselyTypedBuilder<T> = (tie: LetrecLooselyTypedTie) => LetrecValue<T>;

Loosely typed type for the builder function passed to letrec. You may want also want to use its strongly typed version LetrecTypedBuilder.
Remarks
Since 3.0.0
Modifiers
- @public

type LetrecLooselyTypedTie

type LetrecLooselyTypedTie = (key: string) => Arbitrary<unknown>;

Loosely typed type for the tie function passed by letrec to the builder function we pass to it. You may want also want to use its strongly typed version LetrecTypedTie.
Remarks
Since 3.0.0
Modifiers
- @public

type LetrecTypedBuilder

type LetrecTypedBuilder<T> = (tie: LetrecTypedTie<T>) => LetrecValue<T>;

Strongly typed type for the builder function passed to letrec. You may want also want to use its loosely typed version LetrecLooselyTypedBuilder.
Remarks
Since 3.0.0
Modifiers
- @public

type LetrecValue

type LetrecValue<T> = { [K in keyof T]: Arbitrary<T[K]> };

Type of the value produced by letrec
Remarks
Since 3.0.0
Modifiers
- @public

type MaybeWeightedArbitrary

type MaybeWeightedArbitrary<T> = Arbitrary<T> | WeightedArbitrary<T>;

Either an Arbitrary<T> or a WeightedArbitrary<T>
Remarks
Since 3.0.0
Modifiers
- @public

type Memo

type Memo<T> = (maxDepth?: number) => Arbitrary<T>;

Output type for memo
Remarks
Since 1.16.0
Modifiers
- @public

type ModelRunAsyncSetup

type ModelRunAsyncSetup<Model, Real> = () => Promise<{
    model: Model;
    real: Real;
}>;

Asynchronous definition of model and real
Remarks
Since 2.2.0
Modifiers
- @public

type ModelRunSetup

type ModelRunSetup<Model, Real> = () => {
    model: Model;
    real: Real;
};

Synchronous definition of model and real
Remarks
Since 2.2.0
Modifiers
- @public

type OneOfConstraints

type OneOfConstraints = {
    /**
     * When set to true, the shrinker of oneof will try to check if the first arbitrary
     * could have been used to discover an issue. It allows to shrink trees.
     *
     * Warning: First arbitrary must be the one resulting in the smallest structures
     * for usages in deep tree-like structures.
     *
     * @defaultValue false
     * @remarks Since 2.14.0
     */
    withCrossShrink?: boolean;
    /**
     * While going deeper and deeper within a recursive structure (see {@link letrec}),
     * this factor will be used to increase the probability to generate instances
     * of the first passed arbitrary.
     *
     * @remarks Since 2.14.0
     */
    depthSize?: DepthSize;
    /**
     * Maximal authorized depth.
     * Once this depth has been reached only the first arbitrary will be used.
     *
     * @defaultValue Number.POSITIVE_INFINITY — _defaulting seen as "max non specified" when `defaultSizeToMaxWhenMaxSpecified=true`_
     * @remarks Since 2.14.0
     */
    maxDepth?: number;
    /**
     * Depth identifier can be used to share the current depth between several instances.
     *
     * By default, if not specified, each instance of oneof will have its own depth.
     * In other words: you can have depth=1 in one while you have depth=100 in another one.
     *
     * @remarks Since 2.14.0
     */
    depthIdentifier?: DepthIdentifier | string;
};

Constraints to be applied on oneof
Remarks
Since 2.14.0
Modifiers
- @public

type OneOfValue

type OneOfValue<Ts extends MaybeWeightedArbitrary<unknown>[]> = {
    [K in keyof Ts]: Ts[K] extends MaybeWeightedArbitrary<infer U> ? U : never;
}[number];

Infer the type of the Arbitrary produced by oneof given the type of the source arbitraries
Remarks
Since 2.2.0
Modifiers
- @public

type PropertyFailure

type PropertyFailure = {
    /**
     * The original error that has been intercepted.
     * Possibly not an instance Error as users can throw anything.
     * @remarks Since 3.0.0
     */
    error: unknown;
};

Represent failures of the property
Remarks
Since 3.0.0
Modifiers
- @public

type PropertyHookFunction

type PropertyHookFunction = (globalHookFunction: GlobalPropertyHookFunction) => void;

Type of legal hook function that can be used to call beforeEach or afterEach on a IPropertyWithHooks
Remarks
Since 2.2.0
Modifiers
- @public

type RandomGenerator

type RandomGenerator =
    | RandomGenerator7x
    | RandomGenerator$1
    | JumpableRandomGenerator;

Merged type supporting both pure-rand v7 and v8 random generators. Keeping compatibility with v7 avoids a breaking API change and a new major version.
Remarks
Since 4.6.0
Modifiers
- @public

type RandomType

type RandomType =
    | 'mersenne'
    | 'congruential'
    | 'congruential32'
    | 'xorshift128plus'
    | 'xoroshiro128plus';

Random generators automatically recognized by the framework without having to pass a builder function
Remarks
Since 2.2.0
Modifiers
- @public

type RecordConstraints

type RecordConstraints<T = unknown> = {
    /**
     * List keys that should never be deleted.
     *
     * Remark:
     * You might need to use an explicit typing in case you need to declare symbols as required (not needed when required keys are simple strings).
     * With something like `{ requiredKeys: [mySymbol1, 'a'] as [typeof mySymbol1, 'a'] }` when both `mySymbol1` and `a` are required.
     *
     * @defaultValue Array containing all keys of recordModel
     * @remarks Since 2.11.0
     */
    requiredKeys?: T[];
    /**
     * Do not generate records with null prototype
     * @defaultValue false
     * @remarks Since 3.13.0
     */
    noNullPrototype?: boolean;
};

Constraints to be applied on record
Remarks
Since 0.0.12
Modifiers
- @public

type RecordValue

type RecordValue<T, K> = Prettify<Partial<T> & Pick<T, K & keyof T>>;

Infer the type of the Arbitrary produced by record given the type of the source arbitrary and constraints to be applied
Remarks
Since 2.2.0
Modifiers
- @public

type RunDetails

type RunDetails<Ts> =
    | RunDetailsFailureProperty<Ts>
    | RunDetailsFailureTooManySkips<Ts>
    | RunDetailsFailureInterrupted<Ts>
    | RunDetailsSuccess<Ts>;

Post-run details produced by check
A failing property can easily detected by checking the failed flag of this structure
Remarks
Since 0.0.7
Modifiers
- @public

type SchedulerAct

type SchedulerAct = (f: () => Promise<void>) => Promise<void>;

Function responsible to run the passed function and surround it with whatever needed. The name has been inspired from the act function coming with React.
This wrapper function is not supposed to throw. The received function f will never throw.
Wrapping order in the following:
- global act defined on fc.scheduler wraps wait level one - wait act defined on s.waitX wraps local one - local act defined on s.scheduleX(...) wraps the trigger function
Remarks
Since 3.9.0
Modifiers
- @public

type SchedulerSequenceItem

type SchedulerSequenceItem<TMetaData = unknown> =
    | {
          /**
           * Builder to start the task
           * @remarks Since 1.20.0
           */
          builder: () => Promise<any>;
          /**
           * Label
           * @remarks Since 1.20.0
           */
          label: string;
          /**
           * Metadata to be attached into logs
           * @remarks Since 1.25.0
           */
          metadata?: TMetaData;
      }
    | (() => Promise<any>);

Define an item to be passed to scheduleSequence
Remarks
Since 1.20.0
Modifiers
- @public

type SetConstraints

type SetConstraints = {
    /**
     * Lower bound of the generated set size
     * @defaultValue 0
     * @remarks Since 4.4.0
     */
    minLength?: number;
    /**
     * Upper bound of the generated set size
     * @defaultValue 0x7fffffff — _defaulting seen as "max non specified" when `defaultSizeToMaxWhenMaxSpecified=true`_
     * @remarks Since 4.4.0
     */
    maxLength?: number;
    /**
     * Define how large the generated values should be (at max)
     * @remarks Since 4.4.0
     */
    size?: SizeForArbitrary;
    /**
     * When receiving a depth identifier, the arbitrary will impact the depth
     * attached to it to avoid going too deep if it already generated lots of items.
     *
     * In other words, if the number of generated values within the collection is large
     * then the generated items will tend to be less deep to avoid creating structures a lot
     * larger than expected.
     *
     * For the moment, the depth is not taken into account to compute the number of items to
     * define for a precise generate call of the set. Just applied onto eligible items.
     *
     * @remarks Since 4.4.0
     */
    depthIdentifier?: DepthIdentifier | string;
};

Constraints to be applied on set
Remarks
Since 4.4.0
Modifiers
- @public

type Size

type Size = 'xsmall' | 'small' | 'medium' | 'large' | 'xlarge';

The size parameter defines how large the generated values could be.
The default in fast-check is 'small' but it could be increased (resp. decreased) to ask arbitraries for larger (resp. smaller) values.
Remarks
Since 2.22.0
Modifiers
- @public

type SizeForArbitrary

type SizeForArbitrary = RelativeSize | Size | 'max' | undefined;

Superset of Size to override the default defined for size
Remarks
Since 2.22.0
Modifiers
- @public

type StringConstraints

type StringConstraints = StringSharedConstraints & {
    /**
     * A string results from the join between several unitary strings produced by the Arbitrary instance defined by `unit`.
     * The `minLength` and `maxLength` refers to the number of these units composing the string. In other words it does not have to be confound with `.length` on an instance of string.
     *
     * A unit can either be a fully custom Arbitrary or one of the pre-defined options:
     * - `'grapheme'` - Any printable grapheme as defined by the Unicode standard. This unit includes graphemes that may:
     *   - Span multiple code points (e.g., `'\u{0061}\u{0300}'`)
     *   - Consist of multiple characters (e.g., `'\u{1f431}'`)
     *   - Include non-European and non-ASCII characters.
     *   - **Note:** Graphemes produced by this unit are designed to remain visually distinct when joined together.
     *   - **Note:** We are relying on the specifications of Unicode 15.
     * - `'grapheme-composite'` - Any printable grapheme limited to a single code point. This option produces graphemes limited to a single code point.
     *   - **Note:** Graphemes produced by this unit are designed to remain visually distinct when joined together.
     *   - **Note:** We are relying on the specifications of Unicode 15.
     * - `'grapheme-ascii'` - Any printable ASCII character.
     * - `'binary'` - Any possible code point (except half surrogate pairs), regardless of how it may combine with subsequent code points in the produced string. This unit produces a single code point within the full Unicode range (0000-10FFFF).
     * - `'binary-ascii'` - Any possible ASCII character, including control characters. This unit produces any code point in the range 0000-00FF.
     *
     * @defaultValue 'grapheme-ascii'
     * @remarks Since 3.22.0
     */
    unit?:
        | 'grapheme'
        | 'grapheme-composite'
        | 'grapheme-ascii'
        | 'binary'
        | 'binary-ascii'
        | Arbitrary<string>;
};

Constraints to be applied on arbitrary string
Remarks
Since 3.22.0
Modifiers
- @public

type StringMatchingConstraints

type StringMatchingConstraints = {
    /**
     * Upper bound of the generated string length (included)
     * @defaultValue 0x7fffffff
     * @remarks Since 4.6.0
     */
    maxLength?: number;
    /**
     * Define how large the generated values should be (at max)
     * @remarks Since 3.10.0
     */
    size?: SizeForArbitrary;
};

Constraints to be applied on the arbitrary stringMatching
Remarks
Since 3.10.0
Modifiers
- @public

type UniqueArrayConstraints

type UniqueArrayConstraints<T, U> =
    | UniqueArrayConstraintsRecommended<T, U>
    | UniqueArrayConstraintsCustomCompare<T>
    | UniqueArrayConstraintsCustomCompareSelect<T, U>;

Constraints implying known and optimized comparison function to be applied on uniqueArray
The defaults relies on the defaults specified by UniqueArrayConstraintsRecommended
Remarks
Since 2.23.0
Modifiers
- @public

type UniqueArrayConstraintsCustomCompare

type UniqueArrayConstraintsCustomCompare<T> = UniqueArraySharedConstraints & {
    /**
     * The operator to be used to compare the values after having applied the selector (if any)
     * @remarks Since 2.23.0
     */
    comparator: (a: T, b: T) => boolean;
    /**
     * How we should project the values before comparing them together
     * @remarks Since 2.23.0
     */
    selector?: undefined;
};

Constraints implying a fully custom comparison function to be applied on uniqueArray
WARNING - Imply an extra performance cost whenever you want to generate large arrays
Remarks
Since 2.23.0
Modifiers
- @public

type UniqueArrayConstraintsCustomCompareSelect

type UniqueArrayConstraintsCustomCompareSelect<T, U> =
    UniqueArraySharedConstraints & {
        /**
         * The operator to be used to compare the values after having applied the selector (if any)
         * @remarks Since 2.23.0
         */
        comparator: (a: U, b: U) => boolean;
        /**
         * How we should project the values before comparing them together
         * @remarks Since 2.23.0
         */
        selector: (v: T) => U;
    };

Constraints implying fully custom comparison function and selector to be applied on uniqueArray
WARNING - Imply an extra performance cost whenever you want to generate large arrays
Remarks
Since 2.23.0
Modifiers
- @public

type UniqueArrayConstraintsRecommended

type UniqueArrayConstraintsRecommended<T, U> = UniqueArraySharedConstraints & {
    /**
     * The operator to be used to compare the values after having applied the selector (if any):
     * - SameValue behaves like `Object.is` — {@link https://tc39.es/ecma262/multipage/abstract-operations.html#sec-samevalue}
     * - SameValueZero behaves like `Set` or `Map` — {@link https://tc39.es/ecma262/multipage/abstract-operations.html#sec-samevaluezero}
     * - IsStrictlyEqual behaves like `===` — {@link https://tc39.es/ecma262/multipage/abstract-operations.html#sec-isstrictlyequal}
     * - Fully custom comparison function: it implies performance costs for large arrays
     *
     * @defaultValue 'SameValue'
     * @remarks Since 2.23.0
     */
    comparator?: 'SameValue' | 'SameValueZero' | 'IsStrictlyEqual';
    /**
     * How we should project the values before comparing them together
     * @defaultValue (v =&gt; v)
     * @remarks Since 2.23.0
     */
    selector?: (v: T) => U;
};

Constraints implying known and optimized comparison function to be applied on uniqueArray
Remarks
Since 2.23.0
Modifiers
- @public

type UniqueArraySharedConstraints

type UniqueArraySharedConstraints = {
    /**
     * Lower bound of the generated array size
     * @defaultValue 0
     * @remarks Since 2.23.0
     */
    minLength?: number;
    /**
     * Upper bound of the generated array size
     * @defaultValue 0x7fffffff — _defaulting seen as "max non specified" when `defaultSizeToMaxWhenMaxSpecified=true`_
     * @remarks Since 2.23.0
     */
    maxLength?: number;
    /**
     * Define how large the generated values should be (at max)
     * @remarks Since 2.23.0
     */
    size?: SizeForArbitrary;
    /**
     * When receiving a depth identifier, the arbitrary will impact the depth
     * attached to it to avoid going too deep if it already generated lots of items.
     *
     * In other words, if the number of generated values within the collection is large
     * then the generated items will tend to be less deep to avoid creating structures a lot
     * larger than expected.
     *
     * For the moment, the depth is not taken into account to compute the number of items to
     * define for a precise generate call of the array. Just applied onto eligible items.
     *
     * @remarks Since 2.25.0
     */
    depthIdentifier?: DepthIdentifier | string;
};

Shared constraints to be applied on uniqueArray
Remarks
Since 2.23.0
Modifiers
- @public

type WithAsyncToStringMethod

type WithAsyncToStringMethod = {
    [asyncToStringMethod]: () => Promise<string>;
};

Interface to implement for asyncToStringMethod
Remarks
Since 2.17.0
Modifiers
- @public

type WithToStringMethod

type WithToStringMethod = {
    [toStringMethod]: () => string;
};

Interface to implement for toStringMethod
Remarks
Since 2.17.0
Modifiers
- @public

Namespaces

namespace fc

namespace fc {}

Modifiers
- @public

variable asyncToStringMethod

const asyncToStringMethod: Symbol;

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
Modifiers
- @public

variable cloneMethod

const cloneMethod: Symbol;

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
Modifiers
- @public

variable toStringMethod

const toStringMethod: Symbol;

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
Modifiers
- @public

function anything

anything: {
    (): Arbitrary<unknown>;
    (constraints: ObjectConstraints): Arbitrary<unknown>;
};

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]}
Modifiers
- @public

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.string(),
    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]...

Modifiers

@public

function array

array: <T>(arb: Arbitrary<T>, constraints?: ArrayConstraints) => Arbitrary<T[]>;

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
Modifiers
- @public

function assert

assert: {
    <Ts>(property: IAsyncProperty<Ts>, params?: Parameters<Ts>): Promise<void>;
    <Ts>(property: IProperty<Ts>, params?: Parameters<Ts>): void;
    <Ts>(
        property: IRawProperty<Ts, boolean>,
        params?: Parameters<Ts>
    ): void | Promise<void>;
};

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
Modifiers
- @public
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
Modifiers
- @public
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
Modifiers
- @public

function asyncDefaultReportMessage

asyncDefaultReportMessage: {
    <Ts>(out: RunDetails<Ts> & { failed: false }): Promise<undefined>;
    <Ts>(
        out:
            | (RunDetailsFailureProperty<Ts> & { failed: true })
            | (RunDetailsFailureTooManySkips<Ts> & { failed: true })
            | (RunDetailsFailureInterrupted<Ts> & { failed: true })
    ): Promise<string>;
    <Ts>(out: RunDetails<Ts>): Promise<string>;
};

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
Modifiers
- @public

function asyncModelRun

asyncModelRun: <
    Model extends object,
    Real,
    CheckAsync extends boolean,
    InitialModel extends Model
>(
    s: ModelRunSetup<InitialModel, Real> | ModelRunAsyncSetup<InitialModel, Real>,
    cmds: Iterable<AsyncCommand<Model, Real, CheckAsync>>
) => Promise<void>;

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
Modifiers
- @public

function asyncProperty

asyncProperty: <Ts extends [unknown, ...unknown[]]>(
    ...args: [
        ...arbitraries: { [K in keyof Ts]: Arbitrary<Ts[K]> },
        predicate: (...args: Ts) => Promise<boolean | void>
    ]
) => IAsyncPropertyWithHooks<Ts>;

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
Modifiers
- @public

function asyncStringify

asyncStringify: <Ts>(value: Ts) => Promise<string>;

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
Modifiers
- @public

function base64String

base64String: (constraints?: StringSharedConstraints) => Arbitrary<string>;

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
Modifiers
- @public

function bigInt

bigInt: {
    (): Arbitrary<bigint>;
    (min: bigint, max: bigint): Arbitrary<bigint>;
    (constraints: BigIntConstraints): Arbitrary<bigint>;
    (...args: [] | [bigint, bigint] | [BigIntConstraints]): Arbitrary<bigint>;
};

For bigint
Remarks
Since 1.9.0
Modifiers
- @public
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
Modifiers
- @public
For bigint between min (included) and max (included)
Parameter constraints
Constraints to apply when building instances
Remarks
Since 2.6.0
Modifiers
- @public
For bigint between min (included) and max (included)
Parameter args
Either min/max bounds as an object or constraints to apply when building instances
Remarks
Since 2.6.0
Modifiers
- @public

function bigInt64Array

bigInt64Array: (
    constraints?: BigIntArrayConstraints
) => Arbitrary<BigInt64Array<ArrayBuffer>>;

For BigInt64Array
Remarks
Since 3.0.0
Modifiers
- @public

function bigUint64Array

bigUint64Array: (
    constraints?: BigIntArrayConstraints
) => Arbitrary<BigUint64Array<ArrayBuffer>>;

For BigUint64Array
Remarks
Since 3.0.0
Modifiers
- @public

function boolean

boolean: () => Arbitrary<boolean>;

For boolean values - true or false
Remarks
Since 0.0.6
Modifiers
- @public

function check

check: {
    <Ts>(property: IAsyncProperty<Ts>, params?: Parameters<Ts>): Promise<
        RunDetails<Ts>
    >;
    <Ts>(property: IProperty<Ts>, params?: Parameters<Ts>): RunDetails<Ts>;
    <Ts>(property: IRawProperty<Ts, boolean>, params?: Parameters<Ts>):
        | RunDetails<Ts>
        | Promise<RunDetails<Ts>>;
};

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
Modifiers
- @public
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
Modifiers
- @public
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
Modifiers
- @public

function clone

clone: <T, N extends number>(
    arb: Arbitrary<T>,
    numValues: N
) => Arbitrary<CloneValue<T, N>>;

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
Modifiers
- @public

function cloneIfNeeded

cloneIfNeeded: <T>(instance: T) => T;

Clone an instance if needed
Remarks
Since 2.15.0
Modifiers
- @public

function commands

commands: {
    <Model extends object, Real, CheckAsync extends boolean>(
        commandArbs: Arbitrary<AsyncCommand<Model, Real, CheckAsync>>[],
        constraints?: CommandsContraints
    ): Arbitrary<Iterable<AsyncCommand<Model, Real, CheckAsync>>>;
    <Model extends object, Real>(
        commandArbs: Arbitrary<Command<Model, Real>>[],
        constraints?: CommandsContraints
    ): Arbitrary<Iterable<Command<Model, Real>>>;
};

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
Modifiers
- @public
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
Modifiers
- @public

function compareBooleanFunc

compareBooleanFunc: <T>() => Arbitrary<(a: T, b: T) => boolean>;

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
Modifiers
- @public

function compareFunc

compareFunc: <T>() => Arbitrary<(a: T, b: T) => number>;

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
Modifiers
- @public

function configureGlobal

configureGlobal: (parameters: GlobalParameters) => void;

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 }

Modifiers

@public

function constant

constant: () => any;

For value
Parameter value
The value to produce
Remarks
Since 0.0.1
Modifiers
- @public

function constantFrom

constantFrom: {
    (): any;
    <TArgs extends any[] | [any]>(...values: TArgs): Arbitrary<TArgs[number]>;
};

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
Modifiers
- @public

function context

context: () => Arbitrary<ContextValue>;

Produce a ContextValue instance
Remarks
Since 1.8.0
Modifiers
- @public

function createDepthIdentifier

createDepthIdentifier: () => DepthIdentifier;

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

function date

date: (constraints?: DateConstraints) => Arbitrary<Date>;

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
Modifiers
- @public

function defaultReportMessage

defaultReportMessage: {
    <Ts>(out: RunDetails<Ts> & { failed: false }): undefined;
    <Ts>(
        out:
            | (RunDetailsFailureProperty<Ts> & { failed: true })
            | (RunDetailsFailureTooManySkips<Ts> & { failed: true })
            | (RunDetailsFailureInterrupted<Ts> & { failed: true })
    ): string;
    <Ts>(out: RunDetails<Ts>): string;
};

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
Modifiers
- @public

function dictionary

dictionary: {
    <T>(
        keyArb: Arbitrary<string>,
        valueArb: Arbitrary<T>,
        constraints?: DictionaryConstraints
    ): Arbitrary<Record<string, T>>;
    <K extends PropertyKey, V>(
        keyArb: Arbitrary<K>,
        valueArb: Arbitrary<V>,
        constraints?: DictionaryConstraints
    ): Arbitrary<Record<K, V>>;
};

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
Modifiers
- @public
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 4.4.0
Modifiers
- @public

function domain

domain: (constraints?: DomainConstraints) => Arbitrary<string>;

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
Modifiers
- @public

function double

double: (constraints?: DoubleConstraints) => Arbitrary<number>;

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
Modifiers
- @public

function emailAddress

emailAddress: (constraints?: EmailAddressConstraints) => Arbitrary<string>;

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
Modifiers
- @public

function entityGraph

entityGraph: <
    TEntityFields,
    TEntityRelations extends EntityRelations<TEntityFields>
>(
    arbitraries: Arbitraries<TEntityFields>,
    relations: TEntityRelations,
    constraints?: EntityGraphContraints<TEntityFields>
) => Arbitrary<EntityGraphValue<TEntityFields, TEntityRelations>>;

Generates interconnected entities with relationships based on a schema definition.
This arbitrary creates structured data where entities can reference each other through defined relationships. The generated values automatically include links between entities, making it ideal for testing graph structures, relational data, or interconnected object models.
The output is an object where each key corresponds to an entity type and the value is an array of entities of that type. Entities contain both their data fields and relationship links.
Parameter arbitraries
Defines the data fields for each entity type (non-relational properties)
Parameter relations
Defines how entities reference each other (relational properties)
Parameter constraints
Optional configuration to customize generation behavior
Remarks
Since 4.5.0
Example 1
// Generate a simple directed graph where nodes link to other nodes fc.entityGraph( { node: { id: fc.stringMatching(/^[A-Z][a-z]*$/) } }, { node: { linkTo: { arity: 'many', type: 'node' } } }, ) // Produces: { node: [{ id: "Abc", linkTo: [<node#1>, <node#0>] }, ...] }
Example 2
// Generate employees with managers and teams fc.entityGraph( { employee: { name: fc.string() }, team: { name: fc.string() } }, { employee: { manager: { arity: '0-1', type: 'employee' }, // Optional manager team: { arity: '1', type: 'team' } // Required team }, team: {} } )
Modifiers
- @public

function falsy

falsy: <TConstraints extends FalsyContraints>(
    constraints?: TConstraints
) => Arbitrary<FalsyValue<TConstraints>>;

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
Modifiers
- @public

function float

float: (constraints?: FloatConstraints) => Arbitrary<number>;

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
Modifiers
- @public

function float32Array

float32Array: (
    constraints?: Float32ArrayConstraints
) => Arbitrary<Float32Array<ArrayBuffer>>;

For Float32Array
Remarks
Since 2.9.0
Modifiers
- @public

function float64Array

float64Array: (
    constraints?: Float64ArrayConstraints
) => Arbitrary<Float64Array<ArrayBuffer>>;

For Float64Array
Remarks
Since 2.9.0
Modifiers
- @public

function func

func: <TArgs extends any[], TOut>(
    arb: Arbitrary<TOut>
) => Arbitrary<(...args: TArgs) => TOut>;

For pure functions
Parameter arb
Arbitrary responsible to produce the values
Remarks
Since 1.6.0
Modifiers
- @public

function gen

gen: () => Arbitrary<GeneratorValue>;

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.
Modifiers
- @public

function getDepthContextFor

getDepthContextFor: (
    contextMeta: DepthContext | DepthIdentifier | string | undefined
) => DepthContext;

Get back the requested DepthContext
Remarks
Since 2.25.0
Modifiers
- @public

function hasAsyncToStringMethod

hasAsyncToStringMethod: <T>(
    instance: T
) => instance is T & WithAsyncToStringMethod;

Check if an instance implements WithAsyncToStringMethod
Remarks
Since 2.17.0
Modifiers
- @public

function hasCloneMethod

hasCloneMethod: <T>(
    instance: T | WithCloneMethod<T>
) => instance is WithCloneMethod<T>;

Check if an instance has to be clone
Remarks
Since 2.15.0
Modifiers
- @public

function hash

hash: (repr: string) => number;

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
Modifiers
- @public

function hasToStringMethod

hasToStringMethod: <T>(instance: T) => instance is T & WithToStringMethod;

Check if an instance implements WithToStringMethod
Remarks
Since 2.17.0
Modifiers
- @public

function infiniteStream

infiniteStream: <T>(
    arb: Arbitrary<T>,
    constraints?: InfiniteStreamConstraints
) => Arbitrary<Stream<T>>;

Produce an infinite stream of values
WARNING: By default, infiniteStream remembers all values it has ever generated. This causes unbounded memory growth during large tests. Set noHistory to disable.
WARNING: Requires Object.assign
Parameter arb
Arbitrary used to generate the values
Parameter constraints
Constraints to apply when building instances (since 4.3.0)
Remarks
Since 1.8.0
Modifiers
- @public

function int16Array

int16Array: (
    constraints?: IntArrayConstraints
) => Arbitrary<Int16Array<ArrayBuffer>>;

For Int16Array
Remarks
Since 2.9.0
Modifiers
- @public

function int32Array

int32Array: (
    constraints?: IntArrayConstraints
) => Arbitrary<Int32Array<ArrayBuffer>>;

For Int32Array
Remarks
Since 2.9.0
Modifiers
- @public

function int8Array

int8Array: (
    constraints?: IntArrayConstraints
) => Arbitrary<Int8Array<ArrayBuffer>>;

For Int8Array
Remarks
Since 2.9.0
Modifiers
- @public

function integer

integer: (constraints?: IntegerConstraints) => Arbitrary<number>;

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
Modifiers
- @public

function ipV4

ipV4: () => Arbitrary<string>;

For valid IP v4
Following RFC 3986
Remarks
Since 1.14.0
Modifiers
- @public

function ipV4Extended

ipV4Extended: () => Arbitrary<string>;

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
Modifiers
- @public

function ipV6

ipV6: () => Arbitrary<string>;

For valid IP v6
Following RFC 3986
Remarks
Since 1.14.0
Modifiers
- @public

function json

json: (constraints?: JsonSharedConstraints) => Arbitrary<string>;

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
Modifiers
- @public

function jsonValue

jsonValue: (constraints?: JsonSharedConstraints) => Arbitrary<JsonValue>;

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
Modifiers
- @public

function letrec

letrec: {
    <T>(
        builder: T extends Record<string, unknown> ? LetrecTypedBuilder<T> : never
    ): LetrecValue<T>;
    <T>(builder: LetrecLooselyTypedBuilder<T>): LetrecValue<T>;
};

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)

Modifiers

@public

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)

Modifiers

@public

function limitShrink

limitShrink: <T>(arbitrary: Arbitrary<T>, maxShrinks: number) => Arbitrary<T>;

Create another Arbitrary with a limited (or capped) number of shrink values
Parameter arbitrary
Instance of arbitrary responsible to generate and shrink values
Parameter maxShrinks
Maximal number of shrunk values that can be pulled from the resulting arbitrary
Returns
Create another arbitrary with limited number of shrink values
Remarks
Since 3.20.0
Example 1
const dataGenerator: Arbitrary<string> = ...; const limitedShrinkableDataGenerator: Arbitrary<string> = fc.limitShrink(dataGenerator, 10); // up to 10 shrunk values could be extracted from the resulting arbitrary
NOTE: Although limiting the shrinking capabilities can speed up your CI when failures occur, we do not recommend this approach. Instead, if you want to reduce the shrinking time for automated jobs or local runs, consider using endOnFailure or interruptAfterTimeLimit.
Modifiers
- @public

function lorem

lorem: (constraints?: LoremConstraints) => Arbitrary<string>;

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
Modifiers
- @public

function map

map: <K, V>(
    keyArb: Arbitrary<K>,
    valueArb: Arbitrary<V>,
    constraints?: MapConstraints
) => Arbitrary<Map<K, V>>;

For Maps with keys produced by keyArb and values from valueArb
Parameter keyArb
Arbitrary used to generate the keys of the Map
Parameter valueArb
Arbitrary used to generate the values of the Map
Parameter constraints
Constraints to apply when building instances
Remarks
Since 4.4.0
Modifiers
- @public

function mapToConstant

mapToConstant: <T>(
    ...entries: { num: number; build: (idInGroup: number) => T }[]
) => Arbitrary<T>;

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) }, )
Modifiers
- @public

function maxSafeInteger

maxSafeInteger: () => Arbitrary<number>;

For integers between Number.MIN_SAFE_INTEGER (included) and Number.MAX_SAFE_INTEGER (included)
Remarks
Since 1.11.0
Modifiers
- @public

function maxSafeNat

maxSafeNat: () => Arbitrary<number>;

For positive integers between 0 (included) and Number.MAX_SAFE_INTEGER (included)
Remarks
Since 1.11.0
Modifiers
- @public

function memo

memo: <T>(builder: (maxDepth: number) => Arbitrary<T>) => Memo<T>;

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;

Modifiers

@public

function mixedCase

mixedCase: (
    stringArb: Arbitrary<string>,
    constraints?: MixedCaseConstraints
) => Arbitrary<string>;

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
Modifiers
- @public

function modelRun

modelRun: <Model extends object, Real, InitialModel extends Model>(
    s: ModelRunSetup<InitialModel, Real>,
    cmds: Iterable<Command<Model, Real>>
) => void;

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
Modifiers
- @public

function nat

nat: {
    (): Arbitrary<number>;
    (max: number): Arbitrary<number>;
    (constraints: NatConstraints): Arbitrary<number>;
    (arg?: number | NatConstraints): Arbitrary<number>;
};

For positive integers between 0 (included) and 2147483647 (included)
Remarks
Since 0.0.1
Modifiers
- @public
For positive integers between 0 (included) and max (included)
Parameter max
Upper bound for the generated integers
Remarks
Since 0.0.1
Modifiers
- @public
For positive integers between 0 (included) and max (included)
Parameter constraints
Constraints to apply when building instances
Remarks
Since 2.6.0
Modifiers
- @public
For positive integers between 0 (included) and max (included)
Parameter arg
Either a maximum number or constraints to apply when building instances
Remarks
Since 2.6.0
Modifiers
- @public

function noBias

noBias: <T>(arb: Arbitrary<T>) => Arbitrary<T>;

Build an arbitrary without any bias.
The produced instance wraps the source one and ensures the bias factor will always be passed to undefined meaning bias will be deactivated. All the rest stays unchanged.
Parameter arb
The original arbitrary used for generating values. This arbitrary remains unchanged.
Remarks
Since 3.20.0
Modifiers
- @public

function noShrink

noShrink: <T>(arb: Arbitrary<T>) => Arbitrary<T>;

Build an arbitrary without shrinking capabilities.
NOTE: In most cases, users should avoid disabling shrinking capabilities. If the concern is the shrinking process taking too long or being unnecessary in CI environments, consider using alternatives like endOnFailure or interruptAfterTimeLimit instead.
Parameter arb
The original arbitrary used for generating values. This arbitrary remains unchanged, but its shrinking capabilities will not be included in the new arbitrary.
Remarks
Since 3.20.0
Modifiers
- @public

function object

object: {
    (): Arbitrary<Record<string, unknown>>;
    (constraints: ObjectConstraints): Arbitrary<Record<string, unknown>>;
};

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]}
Modifiers
- @public
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]}
Modifiers
- @public

function oneof

oneof: {
    <Ts extends MaybeWeightedArbitrary<unknown>[]>(...arbs: Ts): Arbitrary<
        OneOfValue<Ts>
    >;
    <Ts extends MaybeWeightedArbitrary<unknown>[]>(
        constraints: OneOfConstraints,
        ...arbs: Ts
    ): Arbitrary<OneOfValue<Ts>>;
};

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
Modifiers
- @public
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
Modifiers
- @public

function option

option: <T, TNil = null>(
    arb: Arbitrary<T>,
    constraints?: OptionConstraints<TNil>
) => Arbitrary<T | TNil>;

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
Modifiers
- @public

function pre

pre: (expectTruthy: boolean) => asserts expectTruthy;

Add pre-condition checks inside a property execution
Parameter expectTruthy
cancel the run whenever this value is falsy
Remarks
Since 1.3.0
Modifiers
- @public

function property

property: <Ts extends [unknown, ...unknown[]]>(
    ...args: [
        ...arbitraries: { [K in keyof Ts]: Arbitrary<Ts[K]> },
        predicate: (...args: Ts) => boolean | void
    ]
) => IPropertyWithHooks<Ts>;

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
Modifiers
- @public

function readConfigureGlobal

readConfigureGlobal: () => GlobalParameters;

Read global parameters that will be used by runners
Remarks
Since 1.18.0
Modifiers
- @public

function record

record: <T, K extends keyof T = keyof T>(
    model: { [K in keyof T]: Arbitrary<T[K]> },
    constraints?: RecordConstraints<K>
) => Arbitrary<RecordValue<T, K>>;

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 }, {requiredKeys: []}): Arbitrary<{x?:number,y?:number}>
// merge two integer arbitraries to produce a {x, y}, {x}, {y} or {} record

Modifiers

@public

function resetConfigureGlobal

resetConfigureGlobal: () => void;

Reset global parameters
Remarks
Since 1.18.0
Modifiers
- @public

function sample

sample: <Ts>(
    generator: IRawProperty<Ts> | Arbitrary<Ts>,
    params?: Parameters<Ts> | number
) => Ts[];

Generate an array containing all the values that would have been generated during assert or check
Parameter generator
IProperty or Arbitrary to extract the values from
Parameter params
Integer representing the number of values to generate or Parameters as in assert
Remarks
Since 0.0.6
Example 1
fc.sample(fc.nat(), 10); // extract 10 values from fc.nat() Arbitrary fc.sample(fc.nat(), {seed: 42}); // extract values from fc.nat() as if we were running fc.assert with seed=42
Modifiers
- @public

function scheduledModelRun

scheduledModelRun: <
    Model extends object,
    Real,
    CheckAsync extends boolean,
    InitialModel extends Model
>(
    scheduler: Scheduler,
    s: ModelRunSetup<InitialModel, Real> | ModelRunAsyncSetup<InitialModel, Real>,
    cmds: Iterable<AsyncCommand<Model, Real, CheckAsync>>
) => Promise<void>;

Run asynchronous and scheduled commands over a Model and the Real system
Throw in case of inconsistency
Parameter scheduler
Scheduler
Parameter s
Initial state provider
Parameter cmds
Asynchronous commands to be executed
Remarks
Since 1.24.0
Modifiers
- @public

function scheduler

scheduler: <TMetaData = unknown>(
    constraints?: SchedulerConstraints
) => Arbitrary<Scheduler<TMetaData>>;

For scheduler of promises
Remarks
Since 1.20.0
Modifiers
- @public

function schedulerFor

schedulerFor: {
    <TMetaData = unknown>(constraints?: SchedulerConstraints): (
        _strs: TemplateStringsArray,
        ...ordering: number[]
    ) => Scheduler<TMetaData>;
    <TMetaData = unknown>(
        customOrdering: number[],
        constraints?: SchedulerConstraints
    ): Scheduler<TMetaData>;
};

For custom scheduler with predefined resolution order
Ordering is defined by using a template string like the one generated in case of failure of a scheduler
It may be something like:
Remarks
Since 1.25.0
Example 1
fc.schedulerFor()` -> [task\${2}] promise pending -> [task\${3}] promise pending -> [task\${1}] promise pending `
Or more generally:
fc.schedulerFor()` This scheduler will resolve task ${2} first followed by ${3} and only then task ${1} `
WARNING: Custom scheduler will neither check that all the referred promises have been scheduled nor that they resolved with the same status and value.
WARNING: If one the promises is wrongly defined it will fail - for instance asking to resolve 5 while 5 does not exist.
Modifiers
- @public
For custom scheduler with predefined resolution order
WARNING: Custom scheduler will not check that all the referred promises have been scheduled.
WARNING: If one the promises is wrongly defined it will fail - for instance asking to resolve 5 while 5 does not exist.
Parameter customOrdering
Array defining in which order the promises will be resolved. Id of the promises start at 1. 1 means first scheduled promise, 2 second scheduled promise and so on.
Remarks
Since 1.25.0
Modifiers
- @public

function set

set: <T>(arb: Arbitrary<T>, constraints?: SetConstraints) => Arbitrary<Set<T>>;

For sets of values coming from arb
All the values in the set are unique. Comparison of values relies on SameValueZero which is the same comparison algorithm used by Set.
Parameter arb
Arbitrary used to generate the values inside the set
Parameter constraints
Constraints to apply when building instances
Remarks
Since 4.4.0
Modifiers
- @public

function shuffledSubarray

shuffledSubarray: <T>(
    originalArray: T[],
    constraints?: ShuffledSubarrayConstraints
) => Arbitrary<T[]>;

For subarrays of originalArray
Parameter originalArray
Original array
Parameter constraints
Constraints to apply when building instances (since 2.4.0)
Remarks
Since 1.5.0
Modifiers
- @public

function sparseArray

sparseArray: <T>(
    arb: Arbitrary<T>,
    constraints?: SparseArrayConstraints
) => Arbitrary<T[]>;

For sparse arrays of values coming from arb
Parameter arb
Arbitrary used to generate the values inside the sparse array
Parameter constraints
Constraints to apply when building instances
Remarks
Since 2.13.0
Modifiers
- @public

function statistics

statistics: <Ts>(
    generator: IRawProperty<Ts> | Arbitrary<Ts>,
    classify: (v: Ts) => string | string[],
    params?: Parameters<Ts> | number
) => void;

Gather useful statistics concerning generated values
Print the result in console.log or params.logger (if defined)
Parameter generator
IProperty or Arbitrary to extract the values from
Parameter classify
Classifier function that can classify the generated value in zero, one or more categories (with free labels)
Parameter params
Integer representing the number of values to generate or Parameters as in assert
Remarks
Since 0.0.6
Example 1
fc.statistics( fc.nat(999), v => v < 100 ? 'Less than 100' : 'More or equal to 100', {numRuns: 1000, logger: console.log}); // Classify 1000 values generated by fc.nat(999) into two categories: // - Less than 100 // - More or equal to 100 // The output will be sent line by line to the logger
Modifiers
- @public

function stream

stream: <T>(g: IterableIterator<T>) => Stream<T>;

Create a Stream based on g
Parameter g
Underlying data of the Stream
Remarks
Since 0.0.7
Modifiers
- @public

function string

string: (constraints?: StringConstraints) => Arbitrary<string>;

For strings of char
Parameter constraints
Constraints to apply when building instances (since 2.4.0)
Remarks
Since 0.0.1
Modifiers
- @public

function stringify

stringify: <Ts>(value: Ts) => string;

Convert any value to its fast-check string representation
Parameter value
Value to be converted into a string
Remarks
Since 1.15.0
Modifiers
- @public

function stringMatching

stringMatching: (
    regex: RegExp,
    constraints?: StringMatchingConstraints
) => Arbitrary<string>;

For strings matching the provided regex
Parameter regex
Arbitrary able to generate random strings (possibly multiple characters)
Parameter constraints
Constraints to apply when building instances
Remarks
Since 3.10.0
Modifiers
- @public

function subarray

subarray: <T>(
    originalArray: T[],
    constraints?: SubarrayConstraints
) => Arbitrary<T[]>;

For subarrays of originalArray (keeps ordering)
Parameter originalArray
Original array
Parameter constraints
Constraints to apply when building instances (since 2.4.0)
Remarks
Since 1.5.0
Modifiers
- @public

function tuple

tuple: <Ts extends unknown[]>(
    ...arbs: { [K in keyof Ts]: Arbitrary<Ts[K]> }
) => Arbitrary<Ts>;

For tuples produced using the provided arbs
Parameter arbs
Ordered list of arbitraries
Remarks
Since 0.0.1
Modifiers
- @public

function uint16Array

uint16Array: (
    constraints?: IntArrayConstraints
) => Arbitrary<Uint16Array<ArrayBuffer>>;

For Uint16Array
Remarks
Since 2.9.0
Modifiers
- @public

function uint32Array

uint32Array: (
    constraints?: IntArrayConstraints
) => Arbitrary<Uint32Array<ArrayBuffer>>;

For Uint32Array
Remarks
Since 2.9.0
Modifiers
- @public

function uint8Array

uint8Array: (
    constraints?: IntArrayConstraints
) => Arbitrary<Uint8Array<ArrayBuffer>>;

For Uint8Array
Remarks
Since 2.9.0
Modifiers
- @public

function uint8ClampedArray

uint8ClampedArray: (
    constraints?: IntArrayConstraints
) => Arbitrary<Uint8ClampedArray<ArrayBuffer>>;

For Uint8ClampedArray
Remarks
Since 2.9.0
Modifiers
- @public

function ulid

ulid: () => Arbitrary<string>;

For ulid
According to ulid spec
No mixed case, only upper case digits (0-9A-Z except for: I,L,O,U)
Remarks
Since 3.11.0
Modifiers
- @public

function uniqueArray

uniqueArray: {
    <T, U>(
        arb: Arbitrary<T>,
        constraints?: UniqueArrayConstraintsRecommended<T, U>
    ): Arbitrary<T[]>;
    <T>(
        arb: Arbitrary<T>,
        constraints: UniqueArrayConstraintsCustomCompare<T>
    ): Arbitrary<T[]>;
    <T, U>(
        arb: Arbitrary<T>,
        constraints: UniqueArrayConstraintsCustomCompareSelect<T, U>
    ): Arbitrary<T[]>;
    <T, U>(arb: Arbitrary<T>, constraints: UniqueArrayConstraints<T, U>): Arbitrary<
        T[]
    >;
};

For arrays of unique values coming from arb
Parameter arb
Arbitrary used to generate the values inside the array
Parameter constraints
Constraints to apply when building instances
Remarks
Since 2.23.0
Modifiers
- @public

function uuid

uuid: (constraints?: UuidConstraints) => Arbitrary<string>;

For UUID from v1 to v5
According to RFC 4122
No mixed case, only lower case digits (0-9a-f)
Remarks
Since 1.17.0
Modifiers
- @public

function webAuthority

webAuthority: (constraints?: WebAuthorityConstraints) => Arbitrary<string>;

For web authority
According to RFC 3986 - authority = [ userinfo "@" ] host [ ":" port ]
Parameter constraints
Constraints to apply when building instances
Remarks
Since 1.14.0
Modifiers
- @public

function webFragments

webFragments: (constraints?: WebFragmentsConstraints) => Arbitrary<string>;

For fragments of an URI (web included)
According to RFC 3986
eg.: In the url https://domain/plop?page=1#hello=1&world=2, ?hello=1&world=2 are query parameters
Parameter constraints
Constraints to apply when building instances (since 2.22.0)
Remarks
Since 1.14.0
Modifiers
- @public

function webPath

webPath: (constraints?: WebPathConstraints) => Arbitrary<string>;

For web path
According to RFC 3986 and WHATWG URL Standard
Parameter constraints
Constraints to apply when building instances
Remarks
Since 3.3.0
Modifiers
- @public

function webQueryParameters

webQueryParameters: (
    constraints?: WebQueryParametersConstraints
) => Arbitrary<string>;

For query parameters of an URI (web included)
According to RFC 3986
eg.: In the url https://domain/plop/?hello=1&world=2, ?hello=1&world=2 are query parameters
Parameter constraints
Constraints to apply when building instances (since 2.22.0)
Remarks
Since 1.14.0
Modifiers
- @public

function webSegment

webSegment: (constraints?: WebSegmentConstraints) => Arbitrary<string>;

For internal segment of an URI (web included)
According to RFC 3986
eg.: In the url https://github.com/dubzzz/fast-check/, dubzzz and fast-check are segments
Parameter constraints
Constraints to apply when building instances (since 2.22.0)
Remarks
Since 1.14.0
Modifiers
- @public

function webUrl

webUrl: (constraints?: WebUrlConstraints) => Arbitrary<string>;

For web url
According to RFC 3986 and WHATWG URL Standard
Parameter constraints
Constraints to apply when building instances
Remarks
Since 1.14.0
Modifiers
- @public

class Arbitrary

abstract class Arbitrary<T> {}

Abstract class able to generate values on type T
The values generated by an instance of Arbitrary can be previewed - with sample - or classified - with statistics.
Remarks
Since 0.0.7
Modifiers
- @public

method canShrinkWithoutContext

abstract canShrinkWithoutContext: (value: unknown) => value is T;

Check if a given value could be pass to shrink without providing any context.
In general, canShrinkWithoutContext is not designed to be called for each shrink but rather on very special cases. Its usage must be restricted to canShrinkWithoutContext or in the rare* contexts of a shrink method being called without any context. In this ill-formed case of shrink, canShrinkWithoutContext could be used or called if needed.
*we fall in that case when fast-check is asked to shrink a value that has been provided manually by the user, in other words: a value not coming from a call to generate or a normal shrink with context.
Parameter value
Value to be assessed
Returns
true if and only if the value could have been generated by this instance
Remarks
Since 3.0.0

method chain

chain: <U>(chainer: (t: T) => Arbitrary<U>) => Arbitrary<U>;

Create another arbitrary by mapping a value from a base Arbirary using the provided fmapper Values produced by the new arbitrary are the result of the arbitrary generated by applying fmapper to a value
Parameter chainer
Chain function, to produce a new Arbitrary using a value from another Arbitrary
Returns
New arbitrary of new type
Remarks
Since 1.2.0
Example 1
const arrayAndLimitArbitrary = fc.nat().chain((c: number) => fc.tuple( fc.array(fc.nat(c)), fc.constant(c)));

method filter

filter: {
    <U extends T>(refinement: (t: T) => t is U): Arbitrary<U>;
    (predicate: (t: T) => boolean): Arbitrary<T>;
};

Create another arbitrary by filtering values against predicate
All the values produced by the resulting arbitrary satisfy predicate(value) == true
Be aware that using filter may highly impact the time required to generate a valid entry
Parameter refinement
Predicate, to test each produced element. Return true to keep the element, false otherwise
Returns
New arbitrary filtered using predicate
Remarks
Since 1.23.0
Example 1
const integerGenerator: Arbitrary<number> = ...; const evenIntegerGenerator: Arbitrary<number> = integerGenerator.filter(e => e % 2 === 0); // new Arbitrary only keeps even values
Create another arbitrary by filtering values against predicate
All the values produced by the resulting arbitrary satisfy predicate(value) == true
Be aware that using filter may highly impact the time required to generate a valid entry
Parameter predicate
Predicate, to test each produced element. Return true to keep the element, false otherwise
Returns
New arbitrary filtered using predicate
Remarks
Since 0.0.1
Example 1
const integerGenerator: Arbitrary<number> = ...; const evenIntegerGenerator: Arbitrary<number> = integerGenerator.filter(e => e % 2 === 0); // new Arbitrary only keeps even values

method generate

abstract generate: (mrng: Random, biasFactor: number | undefined) => Value<T>;

Generate a value of type T along with its context (if any) based on the provided random number generator
Parameter mrng
Random number generator
Parameter biasFactor
If taken into account 1 value over biasFactor must be biased. Either integer value greater or equal to 2 (bias) or undefined (no bias)
Returns
Random value of type T and its context
Remarks
Since 0.0.1 (return type changed in 3.0.0)

method map

map: <U>(
    mapper: (t: T) => U,
    unmapper?: (possiblyU: unknown) => T
) => Arbitrary<U>;

Create another arbitrary by mapping all produced values using the provided mapper Values produced by the new arbitrary are the result of applying mapper value by value
Parameter mapper
Map function, to produce a new element based on an old one
Parameter unmapper
Optional unmap function, it will never be used except when shrinking user defined values. Must throw if value is not compatible (since 3.0.0)
Returns
New arbitrary with mapped elements
Remarks
Since 0.0.1
Example 1
const rgbChannels: Arbitrary<{r:number,g:number,b:number}> = ...; const color: Arbitrary<string> = rgbChannels.map(ch => `#${(ch.r*65536 + ch.g*256 + ch.b).toString(16).padStart(6, '0')}`); // transform an Arbitrary producing {r,g,b} integers into an Arbitrary of '#rrggbb'

method shrink

abstract shrink: (value: T, context: unknown | undefined) => Stream<Value<T>>;

Shrink a value of type T, may rely on the context previously provided to shrink efficiently
Must never be called with possibly invalid values and no context without ensuring that such call is legal by calling canShrinkWithoutContext first on the value.
Parameter value
The value to shrink
Parameter context
Its associated context (the one returned by generate) or undefined if no context but canShrinkWithoutContext(value) === true
Returns
Stream of shrinks for value based on context (if provided)
Remarks
Since 3.0.0

class PreconditionFailure

class PreconditionFailure extends Error {}

Error type produced whenever a precondition fails
Remarks
Since 2.2.0
Modifiers
- @public

constructor

constructor(interruptExecution?: boolean);

property interruptExecution

readonly interruptExecution: boolean;

method isFailure

static isFailure: (err: unknown) => err is PreconditionFailure;

class Random

class Random {}

Wrapper around an instance of a pure-rand's random number generator offering a simpler interface to deal with random with impure patterns
Modifiers
- @public

constructor

constructor(sourceRng: any);

Create a mutable random number generator by cloning the passed one and mutate it
Parameter sourceRng
Immutable random generator from pure-rand library, will not be altered (a clone will be)

method clone

clone: () => Random;

Clone the random number generator

method getState

getState: () => readonly number[] | undefined;

Extract the internal state of the internal RandomGenerator backing the current instance of Random

method next

next: (bits: number) => number;

Generate an integer having bits random bits
Parameter bits
Number of bits to generate
Deprecated
Prefer nextInt with explicit bounds: nextInt(0, (1 << bits) - 1)

method nextBigInt

nextBigInt: (min: bigint, max: bigint) => bigint;

Generate a random bigint between min (included) and max (included)
Parameter min
Minimal bigint value
Parameter max
Maximal bigint value

method nextBoolean

nextBoolean: () => boolean;

Generate a random boolean

method nextDouble

nextDouble: () => number;

Generate a random floating point number between 0.0 (included) and 1.0 (excluded)

method nextInt

nextInt: { (): number; (min: number, max: number): number };

Generate a random integer (32 bits)
Deprecated
Prefer nextInt with explicit bounds: nextInt(-2147483648, 2147483647)
Generate a random integer between min (included) and max (included)
Parameter min
Minimal integer value
Parameter max
Maximal integer value

class Stream

class Stream<T> implements IterableIterator<T> {}

Wrapper around IterableIterator interface offering a set of helpers to deal with iterations in a simple way
Remarks
Since 0.0.7
Modifiers
- @public

constructor

constructor(g: IterableIterator<T>);

Create a Stream based on g
Parameter g
Underlying data of the Stream

method [Symbol.iterator]

[Symbol.iterator]: () => IterableIterator<T>;

method drop

drop: (n: number) => Stream<T>;

Drop n first elements of the Stream
WARNING: It closes the current stream
Parameter n
Number of elements to drop
Remarks
Since 0.0.1

method dropWhile

dropWhile: (f: (v: T) => boolean) => Stream<T>;

Drop elements from the Stream while f(element) === true
WARNING: It closes the current stream
Parameter f
Drop condition
Remarks
Since 0.0.1

method every

every: (f: (v: T) => boolean) => boolean;

Check whether all elements of the Stream are successful for f
WARNING: It closes the current stream
Parameter f
Condition to check
Remarks
Since 0.0.1

method filter

filter: {
    <U extends T>(f: (v: T) => v is U): Stream<U>;
    (f: (v: T) => boolean): Stream<T>;
};

Filter elements of the Stream
WARNING: It closes the current stream
Parameter f
Elements to keep
Remarks
Since 1.23.0
Filter elements of the Stream
WARNING: It closes the current stream
Parameter f
Elements to keep
Remarks
Since 0.0.1

method flatMap

flatMap: <U>(f: (v: T) => IterableIterator<U>) => Stream<U>;

Flat map all elements of the Stream using f
WARNING: It closes the current stream
Parameter f
Mapper function
Remarks
Since 0.0.1

method getNthOrLast

getNthOrLast: (nth: number) => T | null;

Take the nth element of the Stream of the last (if it does not exist)
WARNING: It closes the current stream
Parameter nth
Position of the element to extract
Remarks
Since 0.0.12

method has

has: (f: (v: T) => boolean) => [boolean, T | null];

Check whether one of the elements of the Stream is successful for f
WARNING: It closes the current stream
Parameter f
Condition to check
Remarks
Since 0.0.1

method join

join: (...others: IterableIterator<T>[]) => Stream<T>;

Join others Stream to the current Stream
WARNING: It closes the current stream and the other ones (as soon as it iterates over them)
Parameter others
Streams to join to the current Stream
Remarks
Since 0.0.1

method map

map: <U>(f: (v: T) => U) => Stream<U>;

Map all elements of the Stream using f
WARNING: It closes the current stream
Parameter f
Mapper function
Remarks
Since 0.0.1

method next

next: () => IteratorResult<T>;

method nil

static nil: <T>() => Stream<T>;

Create an empty stream of T
Remarks
Since 0.0.1

method of

static of: <T>(...elements: T[]) => Stream<T>;

Create a stream of T from a variable number of elements
Parameter elements
Elements used to create the Stream
Remarks
Since 2.12.0

method take

take: (n: number) => Stream<T>;

Take n first elements of the Stream
WARNING: It closes the current stream
Parameter n
Number of elements to take
Remarks
Since 0.0.1

method takeWhile

takeWhile: (f: (v: T) => boolean) => Stream<T>;

Take elements from the Stream while f(element) === true
WARNING: It closes the current stream
Parameter f
Take condition
Remarks
Since 0.0.1

class Value

class Value<T> {}

A Value<T, TShrink = T> holds an internal value of type T and its associated context
Remarks
Since 3.0.0 (previously called NextValue in 2.15.0)
Modifiers
- @public

constructor

constructor(value_: {}, context: {}, customGetValue?: () => T);

Parameter value_
Internal value of the shrinkable
Parameter context
Context associated to the generated value (useful for shrink)
Parameter customGetValue
Limited to internal usages (to ease migration to next), it will be removed on next major

property context

readonly context: {};

Context for the generated value TODO - Do we want to clone it too?
Remarks
2.15.0

property hasToBeCloned

readonly hasToBeCloned: boolean;

State storing the result of hasCloneMethod If true the value will be cloned each time it gets accessed
Remarks
Since 2.15.0

property value

readonly value: {};

Safe value of the shrinkable Depending on hasToBeCloned it will either be value_ or a clone of it
Remarks
Since 2.15.0

property value_

readonly value_: {};

Internal value of the shrinkable
Remarks
Since 2.15.0

interface ArrayConstraints

interface ArrayConstraints {}

Constraints to be applied on array
Remarks
Since 2.4.0
Modifiers
- @public

property depthIdentifier

depthIdentifier?: DepthIdentifier | string;

When receiving a depth identifier, the arbitrary will impact the depth attached to it to avoid going too deep if it already generated lots of items.
In other words, if the number of generated values within the collection is large then the generated items will tend to be less deep to avoid creating structures a lot larger than expected.
For the moment, the depth is not taken into account to compute the number of items to define for a precise generate call of the array. Just applied onto eligible items.
Remarks
Since 2.25.0

property maxLength

maxLength?: number;

Upper bound of the generated array size
Remarks
Since 2.4.0

property minLength

minLength?: number;

Lower bound of the generated array size
Remarks
Since 2.4.0

property size

size?: SizeForArbitrary;

Define how large the generated values should be (at max)
When used in conjonction with maxLength, size will be used to define the upper bound of the generated array size while maxLength will be used to define and document the general maximal length allowed for this case.
Remarks
Since 2.22.0

interface AsyncCommand

interface AsyncCommand<
    Model extends object,
    Real,
    CheckAsync extends boolean = false
> extends ICommand<Model, Real, Promise<void>, CheckAsync> {}

Interface that should be implemented in order to define an asynchronous command
Remarks
Since 1.5.0
Modifiers
- @public

interface BigIntConstraints

interface BigIntConstraints {}

Constraints to be applied on bigInt
Remarks
Since 2.6.0
Modifiers
- @public

property max

max?: bigint;

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

property min

min?: bigint;

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

interface Command

interface Command<Model extends object, Real> extends ICommand<Model, Real, void> {}

Interface that should be implemented in order to define a synchronous command
Remarks
Since 1.5.0
Modifiers
- @public

interface CommandsContraints

interface CommandsContraints {}

Parameters for commands
Remarks
Since 2.2.0
Modifiers
- @public

property disableReplayLog

disableReplayLog?: boolean;

Do not show replayPath in the output
Remarks
Since 1.11.0

property maxCommands

maxCommands?: number;

Maximal number of commands to generate per run
You probably want to use size instead.
Remarks
Since 1.11.0

property replayPath

replayPath?: string;

Hint for replay purposes only
Should be used in conjonction with { seed, path } of assert
Remarks
Since 1.11.0

property size

size?: SizeForArbitrary;

Define how large the generated values (number of commands) should be (at max)
Remarks
Since 2.22.0

interface ContextValue

interface ContextValue {}

Execution context attached to one predicate run
Remarks
Since 2.2.0
Modifiers
- @public

method log

log: (data: string) => void;

Log execution details during a test. Very helpful when troubleshooting failures
Parameter data
Data to be logged into the current context
Remarks
Since 1.8.0

method size

size: () => number;

Number of logs already logged into current context
Remarks
Since 1.8.0

interface DateConstraints

interface DateConstraints {}

Constraints to be applied on date
Remarks
Since 3.3.0
Modifiers
- @public

property max

max?: Date;

Upper bound of the range (included)
Remarks
Since 1.17.0

property min

min?: Date;

Lower bound of the range (included)
Remarks
Since 1.17.0

property noInvalidDate

noInvalidDate?: boolean;

When set to true, no more "Invalid Date" can be generated.
Remarks
Since 3.13.0

interface DictionaryConstraints

interface DictionaryConstraints {}

Constraints to be applied on dictionary
Remarks
Since 2.22.0
Modifiers
- @public

property depthIdentifier

depthIdentifier?: DepthIdentifier | string;

Depth identifier can be used to share the current depth between several instances.
By default, if not specified, each instance of dictionary will have its own depth. In other words: you can have depth=1 in one while you have depth=100 in another one.
Remarks
Since 3.15.0

property maxKeys

maxKeys?: number;

Upper bound for the number of keys defined into the generated instance
Remarks
Since 2.22.0

property minKeys

minKeys?: number;

Lower bound for the number of keys defined into the generated instance
Remarks
Since 2.22.0

property noNullPrototype

noNullPrototype?: boolean;

Do not generate objects with null prototype
Remarks
Since 3.13.0

property size

size?: SizeForArbitrary;

Define how large the generated values should be (at max)
Remarks
Since 2.22.0

interface DomainConstraints

interface DomainConstraints {}

Constraints to be applied on domain
Remarks
Since 2.22.0
Modifiers
- @public

property size

size?: Exclude<SizeForArbitrary, 'max'>;

Define how large the generated values should be (at max)
Remarks
Since 2.22.0

interface DoubleConstraints

interface DoubleConstraints {}

Constraints to be applied on double
Remarks
Since 2.6.0
Modifiers
- @public

property max

max?: number;

Upper bound for the generated 64-bit floats (included, see maxExcluded to exclude it)
Remarks
Since 2.8.0

property maxExcluded

maxExcluded?: boolean;

Should the upper bound (aka max) be excluded? Note: Excluding max=Number.POSITIVE_INFINITY would result into having max set to Number.MAX_VALUE.
Remarks
Since 3.12.0

property min

min?: number;

Lower bound for the generated 64-bit floats (included, see minExcluded to exclude it)
Remarks
Since 2.8.0

property minExcluded

minExcluded?: boolean;

Should the lower bound (aka min) be excluded? Note: Excluding min=Number.NEGATIVE_INFINITY would result into having min set to -Number.MAX_VALUE.
Remarks
Since 3.12.0

property noDefaultInfinity

noDefaultInfinity?: boolean;

By default, lower and upper bounds are -infinity and +infinity. By setting noDefaultInfinity to true, you move those defaults to minimal and maximal finite values.
Remarks
Since 2.8.0

property noInteger

noInteger?: boolean;

When set to true, Number.isInteger(value) will be false for any generated value. Note: -infinity and +infinity, or NaN can stil be generated except if you rejected them via another constraint.
Remarks
Since 3.18.0

property noNaN

noNaN?: boolean;

When set to true, no more Number.NaN can be generated.
Remarks
Since 2.8.0

interface EmailAddressConstraints

interface EmailAddressConstraints {}

Constraints to be applied on emailAddress
Remarks
Since 2.22.0
Modifiers
- @public

property size

size?: Exclude<SizeForArbitrary, 'max'>;

Define how large the generated values should be (at max)
Remarks
Since 2.22.0

interface ExecutionTree

interface ExecutionTree<Ts> {}

Summary of the execution process
Remarks
Since 1.9.0
Modifiers
- @public

property children

children: ExecutionTree<Ts>[];

Values derived from this value
Remarks
Since 1.9.0

property status

status: ExecutionStatus;

Status of the property
Remarks
Since 1.9.0

property value

value: Ts;

Generated value
Remarks
Since 1.9.0

interface FalsyContraints

interface FalsyContraints {}

Constraints to be applied on falsy
Remarks
Since 1.26.0
Modifiers
- @public

property withBigInt

withBigInt?: boolean;

Enable falsy bigint value
Remarks
Since 1.26.0

interface FloatConstraints

interface FloatConstraints {}

Constraints to be applied on float
Remarks
Since 2.6.0
Modifiers
- @public

property max

max?: number;

Upper bound for the generated 32-bit floats (included)
Remarks
Since 2.8.0

property maxExcluded

maxExcluded?: boolean;

Should the upper bound (aka max) be excluded? Note: Excluding max=Number.POSITIVE_INFINITY would result into having max set to 3.4028234663852886e+38.
Remarks
Since 3.12.0

property min

min?: number;

Lower bound for the generated 32-bit floats (included)
Remarks
Since 2.8.0

property minExcluded

minExcluded?: boolean;

Should the lower bound (aka min) be excluded? Note: Excluding min=Number.NEGATIVE_INFINITY would result into having min set to -3.4028234663852886e+38.
Remarks
Since 3.12.0

property noDefaultInfinity

noDefaultInfinity?: boolean;

By default, lower and upper bounds are -infinity and +infinity. By setting noDefaultInfinity to true, you move those defaults to minimal and maximal finite values.
Remarks
Since 2.8.0

property noInteger

noInteger?: boolean;

When set to true, Number.isInteger(value) will be false for any generated value. Note: -infinity and +infinity, or NaN can stil be generated except if you rejected them via another constraint.
Remarks
Since 3.18.0

property noNaN

noNaN?: boolean;

When set to true, no more Number.NaN can be generated.
Remarks
Since 2.8.0

interface IAsyncProperty

interface IAsyncProperty<Ts> extends IRawProperty<Ts, true> {}

Interface for asynchronous property, see IRawProperty
Remarks
Since 1.19.0
Modifiers
- @public

interface IAsyncPropertyWithHooks

interface IAsyncPropertyWithHooks<Ts> extends IAsyncProperty<Ts> {}

Interface for asynchronous property defining hooks, see IAsyncProperty
Remarks
Since 2.2.0
Modifiers
- @public

method afterEach

afterEach: (
    hookFunction: AsyncPropertyHookFunction
) => IAsyncPropertyWithHooks<Ts>;

Define a function that should be called after all calls to the predicate
Parameter hookFunction
Function to be called
Remarks
Since 1.6.0

method beforeEach

beforeEach: (
    hookFunction: AsyncPropertyHookFunction
) => IAsyncPropertyWithHooks<Ts>;

Define a function that should be called before all calls to the predicate
Parameter hookFunction
Function to be called
Remarks
Since 1.6.0

interface ICommand

interface ICommand<
    Model extends object,
    Real,
    RunResult,
    CheckAsync extends boolean = false
> {}

Interface that should be implemented in order to define a command
Remarks
Since 1.5.0
Modifiers
- @public

method check

check: (
    m: Readonly<Model>
) => CheckAsync extends false ? boolean : Promise<boolean>;

Check if the model is in the right state to apply the command
WARNING: does not change the model
Parameter m
Model, simplified or schematic representation of real system
Remarks
Since 1.5.0

method run

run: (m: Model, r: Real) => RunResult;

Receive the non-updated model and the real or system under test. Perform the checks post-execution - Throw in case of invalid state. Update the model accordingly
Parameter m
Model, simplified or schematic representation of real system
Parameter r
Sytem under test
Remarks
Since 1.5.0

method toString

toString: () => string;

Name of the command
Remarks
Since 1.5.0

interface IntegerConstraints

interface IntegerConstraints {}

Constraints to be applied on integer
Remarks
Since 2.6.0
Modifiers
- @public

property max

max?: number;

Upper bound for the generated integers (included)
Remarks
Since 2.6.0

property min

min?: number;

Lower bound for the generated integers (included)
Remarks
Since 2.6.0

interface IProperty

interface IProperty<Ts> extends IRawProperty<Ts, false> {}

Interface for synchronous property, see IRawProperty
Remarks
Since 1.19.0
Modifiers
- @public

interface IPropertyWithHooks

interface IPropertyWithHooks<Ts> extends IProperty<Ts> {}

Interface for synchronous property defining hooks, see IProperty
Remarks
Since 2.2.0
Modifiers
- @public

method afterEach

afterEach: {
    (
        invalidHookFunction: (
            hookFunction: GlobalPropertyHookFunction
        ) => Promise<unknown>
    ): 'afterEach expects a synchronous function but was given a function returning a Promise';
    (hookFunction: PropertyHookFunction): IPropertyWithHooks<Ts>;
};

Define a function that should be called after all calls to the predicate
Parameter invalidHookFunction
Function to be called, please provide a valid hook function
Remarks
Since 1.6.0
Define a function that should be called after all calls to the predicate
Parameter hookFunction
Function to be called
Remarks
Since 1.6.0

method beforeEach

beforeEach: {
    (
        invalidHookFunction: (
            hookFunction: GlobalPropertyHookFunction
        ) => Promise<unknown>
    ): 'beforeEach expects a synchronous function but was given a function returning a Promise';
    (hookFunction: PropertyHookFunction): IPropertyWithHooks<Ts>;
};

Define a function that should be called before all calls to the predicate
Parameter invalidHookFunction
Function to be called, please provide a valid hook function
Remarks
Since 1.6.0
Define a function that should be called before all calls to the predicate
Parameter hookFunction
Function to be called
Remarks
Since 1.6.0

interface IRawProperty

interface IRawProperty<Ts, IsAsync extends boolean = boolean> {}

Property
A property is the combination of: - Arbitraries: how to generate the inputs for the algorithm - Predicate: how to confirm the algorithm succeeded?
Remarks
Since 1.19.0
Modifiers
- @public

property runAfterEach

runAfterEach: () =>
    | (IsAsync extends true ? Promise<void> : never)
    | (IsAsync extends false ? void : never);

Run after each hook
Remarks
Since 3.4.0

property runBeforeEach

runBeforeEach: () =>
    | (IsAsync extends true ? Promise<void> : never)
    | (IsAsync extends false ? void : never);

Run before each hook
Remarks
Since 3.4.0

method generate

generate: (mrng: Random, runId?: number) => Value<Ts>;

Generate values of type Ts
Parameter mrng
Random number generator
Parameter runId
Id of the generation, starting at 0 - if set the generation might be biased
Remarks
Since 0.0.7 (return type changed in 3.0.0)

method isAsync

isAsync: () => IsAsync;

Is the property asynchronous?
true in case of asynchronous property, false otherwise
Remarks
Since 0.0.7

method run

run: (
    v: Ts
) =>
    | (IsAsync extends true
          ? Promise<PreconditionFailure | PropertyFailure | null>
          : never)
    | (IsAsync extends false
          ? PreconditionFailure | PropertyFailure | null
          : never);

Check the predicate for v
Parameter v
Value of which we want to check the predicate
Remarks
Since 0.0.7

method shrink

shrink: (value: Value<Ts>) => Stream<Value<Ts>>;

Shrink value of type Ts
Parameter value
The value to be shrunk, it can be context-less
Remarks
Since 3.0.0

interface JsonSharedConstraints

interface JsonSharedConstraints {}

Shared constraints for: - json, - jsonValue,
Remarks
Since 2.5.0
Modifiers
- @public

property depthSize

depthSize?: DepthSize;

Limit the depth of the object by increasing the probability to generate simple values (defined via values) as we go deeper in the object.
Remarks
Since 2.20.0

property maxDepth

maxDepth?: number;

Maximal depth allowed
Remarks
Since 2.5.0

property noUnicodeString

noUnicodeString?: boolean;

Only generate instances having keys and values made of ascii strings (when true)
Remarks
Since 3.19.0
Deprecated
Prefer using stringUnit to customize the kind of strings that will be generated by default.

property stringUnit

stringUnit?: StringConstraints['unit'];

Replace the default unit for strings.
Remarks
Since 3.23.0

interface LetrecTypedTie

interface LetrecTypedTie<T> {}

Strongly typed type for the tie function passed by letrec to the builder function we pass to it. You may want also want to use its loosely typed version LetrecLooselyTypedTie.
Remarks
Since 3.0.0
Modifiers
- @public

call signature

<K extends keyof T>(key: K): Arbitrary<T[K]>;

call signature

(key: string): Arbitrary<unknown>;

interface LoremConstraints

interface LoremConstraints {}

Constraints to be applied on lorem
Remarks
Since 2.5.0
Modifiers
- @public

property maxCount

maxCount?: number;

Maximal number of entities: - maximal number of words in case mode is 'words' - maximal number of sentences in case mode is 'sentences'
Remarks
Since 2.5.0

property mode

mode?: 'words' | 'sentences';

Type of strings that should be produced by lorem: - words: multiple words - sentences: multiple sentences
Remarks
Since 2.5.0

property size

size?: SizeForArbitrary;

Define how large the generated values should be (at max)
Remarks
Since 2.22.0

interface MapConstraints

interface MapConstraints {}

Constraints to be applied on map
Remarks
Since 4.4.0
Modifiers
- @public

property depthIdentifier

depthIdentifier?: DepthIdentifier | string;

Depth identifier can be used to share the current depth between several instances.
By default, if not specified, each instance of map will have its own depth. In other words: you can have depth=1 in one while you have depth=100 in another one.
Remarks
Since 4.4.0

property maxKeys

maxKeys?: number;

Upper bound for the number of entries defined into the generated instance
Remarks
Since 4.4.0

property minKeys

minKeys?: number;

Lower bound for the number of entries defined into the generated instance
Remarks
Since 4.4.0

property size

size?: SizeForArbitrary;

Define how large the generated values should be (at max)
Remarks
Since 4.4.0

interface MixedCaseConstraints

interface MixedCaseConstraints {}

Constraints to be applied on mixedCase
Remarks
Since 1.17.0
Modifiers
- @public

property toggleCase

toggleCase?: (rawChar: string) => string;

Transform a character to its upper and/or lower case version
Remarks
Since 1.17.0

property untoggleAll

untoggleAll?: (toggledString: string) => string;

In order to be fully reversable (only in case you want to shrink user definable values) you should provide a function taking a string containing possibly toggled items and returning its untoggled version.

interface NatConstraints

interface NatConstraints {}

Constraints to be applied on nat
Remarks
Since 2.6.0
Modifiers
- @public

property max

max?: number;

Upper bound for the generated postive integers (included)
Remarks
Since 2.6.0

interface ObjectConstraints

interface ObjectConstraints {}

Constraints for anything and object
Modifiers
- @public

property depthSize

depthSize?: DepthSize;

Limit the depth of the object by increasing the probability to generate simple values (defined via values) as we go deeper in the object.
Remarks
Since 2.20.0

property key

key?: Arbitrary<string>;

Arbitrary for keys
Remarks
Since 0.0.7

property maxDepth

maxDepth?: number;

Maximal depth allowed
Remarks
Since 0.0.7

property maxKeys

maxKeys?: number;

Maximal number of keys
Remarks
Since 1.13.0

property size

size?: SizeForArbitrary;

Define how large the generated values should be (at max)
Remarks
Since 2.22.0

property stringUnit

stringUnit?: StringConstraints['unit'];

Replace the default unit for strings.
Remarks
Since 3.23.0

property values

values?: Arbitrary<unknown>[];

Arbitrary for values
Remarks
Since 0.0.7

property withBigInt

withBigInt?: boolean;

Also generate BigInt
Remarks
Since 1.26.0

property withBoxedValues

withBoxedValues?: boolean;

Also generate boxed versions of values
Remarks
Since 1.11.0

property withDate

withDate?: boolean;

Also generate Date
Remarks
Since 2.5.0

property withMap

withMap?: boolean;

Also generate Map
Remarks
Since 1.11.0

property withNullPrototype

withNullPrototype?: boolean;

Also generate object with null prototype
Remarks
Since 1.23.0

property withObjectString

withObjectString?: boolean;

Also generate string representations of object instances
Remarks
Since 1.17.0

property withSet

withSet?: boolean;

Also generate Set
Remarks
Since 1.11.0

property withSparseArray

withSparseArray?: boolean;

Also generate sparse arrays (arrays with holes)
Remarks
Since 2.13.0

property withTypedArray

withTypedArray?: boolean;

Also generate typed arrays in: (Uint|Int)(8|16|32)Array and Float(32|64)Array Remark: no typed arrays made of bigint
Remarks
Since 2.9.0

property withUnicodeString

withUnicodeString?: boolean;

Replace the arbitrary of strings defaulted for key and values by one able to generate unicode strings with non-ascii characters. If you override key and/or values constraint, this flag will not apply to your override.
Remarks
Since 3.19.0
Deprecated
Prefer using stringUnit to customize the kind of strings that will be generated by default.

interface OptionConstraints

interface OptionConstraints<TNil = null> {}

Constraints to be applied on option
Remarks
Since 2.2.0
Modifiers
- @public

property depthIdentifier

depthIdentifier?: DepthIdentifier | string;

Depth identifier can be used to share the current depth between several instances.
By default, if not specified, each instance of option will have its own depth. In other words: you can have depth=1 in one while you have depth=100 in another one.
Remarks
Since 2.14.0

property depthSize

depthSize?: DepthSize;

While going deeper and deeper within a recursive structure (see letrec), this factor will be used to increase the probability to generate nil.
Remarks
Since 2.14.0

property freq

freq?: number;

The probability to build a nil value is of 1 / freq.
Remarks
Since 1.17.0

property maxDepth

maxDepth?: number;

Maximal authorized depth. Once this depth has been reached only nil will be used.
Remarks
Since 2.14.0

property nil

nil?: TNil;

The nil value
Remarks
Since 1.17.0

interface Parameters

interface Parameters<T = void> {}

Customization of the parameters used to run the properties
Remarks
Since 0.0.6
Modifiers
- @public

property asyncReporter

asyncReporter?: (runDetails: RunDetails<T>) => Promise<void>;

Replace the default reporter handling errors by a custom one
Reporter is responsible to throw in case of failure: default one throws whenever runDetails.failed is true. But you may want to change this behaviour in yours.
Only used when calling assert Cannot be defined in conjonction with reporter Not compatible with synchronous properties: runner will throw
Remarks
Since 1.25.0

property endOnFailure

endOnFailure?: boolean;

Stop run on failure
It makes the run stop at the first encountered failure without shrinking.
When used in complement to seed and path, it replays only the minimal counterexample.
Remarks
Since 1.11.0

property examples

examples?: T[];

Custom values added at the beginning of generated ones
It enables users to come with examples they want to test at every run
Remarks
Since 1.4.0

property ignoreEqualValues

ignoreEqualValues?: boolean;

Discard runs corresponding to already tried values.
WARNING: Discarded runs will not be replaced. In other words, if you ask for 100 runs and have 2 discarded runs you will only have 98 effective runs.
NOTE: Relies on fc.stringify to check the equality.
Remarks
Since 2.14.0

property includeErrorInReport

includeErrorInReport?: boolean;

By default the Error causing the failure of the predicate will not be directly exposed within the message of the Error thown by fast-check. It will be exposed by a cause field attached to the Error.
The Error with cause has been supported by Node since 16.14.0 and is properly supported in many test runners.
But if the original Error fails to appear within your test runner, Or if you prefer the Error to be included directly as part of the message of the resulted Error, you can toggle this flag and the Error produced by fast-check in case of failure will expose the source Error as part of the message and not as a cause.

property interruptAfterTimeLimit

interruptAfterTimeLimit?: number;

Interrupt test execution after a given time limit: disabled by default
NOTE: Relies on Date.now().
NOTE: Useful to avoid having too long running processes in your CI. Replay capability (see seed, path) can still be used if needed.
WARNING: If the test got interrupted before any failure occured and before it reached the requested number of runs specified by numRuns it will be marked as success. Except if markInterruptAsFailure has been set to true
Remarks
Since 1.19.0

property markInterruptAsFailure

markInterruptAsFailure?: boolean;

Mark interrupted runs as failed runs if preceded by one success or more: disabled by default Interrupted with no success at all always defaults to failure whatever the value of this flag.
Remarks
Since 1.19.0

property maxSkipsPerRun

maxSkipsPerRun?: number;

Maximal number of skipped values per run
Skipped is considered globally, so this value is used to compute maxSkips = maxSkipsPerRun * numRuns. Runner will consider a run to have failed if it skipped maxSkips+1 times before having generated numRuns valid entries.
See pre for more details on pre-conditions
Remarks
Since 1.3.0

property numRuns

numRuns?: number;

Number of runs before success: 100 by default
Remarks
Since 1.0.0

property path

path?: string;

Way to replay a failing property directly with the counterexample. It can be fed with the counterexamplePath returned by the failing test (requires seed too).
Remarks
Since 1.0.0

property randomType

randomType?: RandomType | ((seed: number) => RandomGenerator);

Random number generator: xorshift128plus by default
Random generator is the core element behind the generation of random values - changing it might directly impact the quality and performances of the generation of random values. It can be one of: 'mersenne', 'congruential', 'congruential32', 'xorshift128plus', 'xoroshiro128plus' Or any function able to build a RandomGenerator based on a seed
As required since pure-rand v6.0.0, when passing a builder for RandomGenerator, the random number generator must generate values between -0x80000000 and 0x7fffffff.
Remarks
Since 1.6.0

property reporter

reporter?: (runDetails: RunDetails<T>) => void;

Replace the default reporter handling errors by a custom one
Reporter is responsible to throw in case of failure: default one throws whenever runDetails.failed is true. But you may want to change this behaviour in yours.
Only used when calling assert Cannot be defined in conjonction with asyncReporter
Remarks
Since 1.25.0

property seed

seed?: number;

Initial seed of the generator: Date.now() by default
It can be forced to replay a failed run.
In theory, seeds are supposed to be 32-bit integers. In case of double value, the seed will be rescaled into a valid 32-bit integer (eg.: values between 0 and 1 will be evenly spread into the range of possible seeds).
Remarks
Since 0.0.6

property skipAllAfterTimeLimit

skipAllAfterTimeLimit?: number;

Skip all runs after a given time limit: disabled by default
NOTE: Relies on Date.now().
NOTE: Useful to stop too long shrinking processes. Replay capability (see seed, path) can resume the shrinking.
WARNING: It skips runs. Thus test might be marked as failed. Indeed, it might not reached the requested number of successful runs.
Remarks
Since 1.15.0

property skipEqualValues

skipEqualValues?: boolean;

Skip runs corresponding to already tried values.
WARNING: Discarded runs will be retried. Under the hood they are simple calls to fc.pre. In other words, if you ask for 100 runs but your generator can only generate 10 values then the property will fail as 100 runs will never be reached. Contrary to ignoreEqualValues you always have the number of runs you requested.
NOTE: Relies on fc.stringify to check the equality.
Remarks
Since 2.14.0

property timeout

timeout?: number;

Maximum time in milliseconds for the predicate to answer: disabled by default
WARNING: Only works for async code (see asyncProperty), will not interrupt a synchronous code.
Remarks
Since 0.0.11

property unbiased

unbiased?: boolean;

Force the use of unbiased arbitraries: biased by default
Remarks
Since 1.1.0

property verbose

verbose?: boolean | VerbosityLevel;

Enable verbose mode: VerbosityLevel.None by default
Using verbose: true is equivalent to verbose: VerbosityLevel.Verbose
It can prove very useful to troubleshoot issues. See VerbosityLevel for more details on each level.
Remarks
Since 1.1.0

method logger

logger: (v: string) => void;

Logger (see statistics): console.log by default
Remarks
Since 0.0.6

interface RunDetailsCommon

interface RunDetailsCommon<Ts> {}

Shared part between variants of RunDetails
Remarks
Since 2.2.0
Modifiers
- @public

property counterexample

counterexample: Ts | null;

In case of failure: the counterexample contains the minimal failing case (first failure after shrinking)
Remarks
Since 0.0.7

property counterexamplePath

counterexamplePath: string | null;

In case of failure: path to the counterexample
For replay purposes, it can be forced in assert, check, sample and statistics using Parameters
Remarks
Since 1.0.0

property errorInstance

errorInstance: unknown | null;

In case of failure: it contains the error that has been thrown if any
Remarks
Since 3.0.0

property executionSummary

executionSummary: ExecutionTree<Ts>[];

Execution summary of the run
Traces the origin of each value encountered during the test and its execution status. Can help to diagnose shrinking issues.
You must enable verbose with at least Verbosity.Verbose in Parameters in order to have values in it: - Verbose: Only failures - VeryVerbose: Failures, Successes and Skipped
Remarks
Since 1.9.0

property failed

failed: boolean;

Does the property failed during the execution of check?
Remarks
Since 0.0.7

property failures

failures: Ts[];

List all failures that have occurred during the run
You must enable verbose with at least Verbosity.Verbose in Parameters in order to have values in it
Remarks
Since 1.1.0

property interrupted

interrupted: boolean;

Was the execution interrupted?
Remarks
Since 1.19.0

property numRuns

numRuns: number;

Number of runs
- In case of failed property: Number of runs up to the first failure (including the failure run) - Otherwise: Number of successful executions
Remarks
Since 1.0.0

property numShrinks

numShrinks: number;

Number of shrinks required to get to the minimal failing case (aka counterexample)
Remarks
Since 1.0.0

property numSkips

numSkips: number;

Number of skipped entries due to failed pre-condition
As numRuns it only takes into account the skipped values that occured before the first failure. Refer to pre to add such pre-conditions.
Remarks
Since 1.3.0

property runConfiguration

runConfiguration: Parameters<Ts>;

Configuration of the run
It includes both local parameters set on check or assert and global ones specified using configureGlobal
Remarks
Since 1.25.0

property seed

seed: number;

Seed that have been used by the run
It can be forced in assert, check, sample and statistics using Parameters
Remarks
Since 0.0.7

property verbose

verbose: VerbosityLevel;

Verbosity level required by the user
Remarks
Since 1.9.0

interface RunDetailsFailureInterrupted

interface RunDetailsFailureInterrupted<Ts> extends RunDetailsCommon<Ts> {}

Run reported as failed because it took too long and thus has been interrupted
Refer to RunDetailsCommon for more details
Remarks
Since 1.25.0
Modifiers
- @public

property counterexample

counterexample: null;

property counterexamplePath

counterexamplePath: null;

property errorInstance

errorInstance: null;

property failed

failed: true;

property interrupted

interrupted: true;

interface RunDetailsFailureProperty

interface RunDetailsFailureProperty<Ts> extends RunDetailsCommon<Ts> {}

Run reported as failed because the property failed
Refer to RunDetailsCommon for more details
Remarks
Since 1.25.0
Modifiers
- @public

property counterexample

counterexample: Ts;

property counterexamplePath

counterexamplePath: string;

property errorInstance

errorInstance: unknown;

property failed

failed: true;

property interrupted

interrupted: boolean;

interface RunDetailsFailureTooManySkips

interface RunDetailsFailureTooManySkips<Ts> extends RunDetailsCommon<Ts> {}

Run reported as failed because too many retries have been attempted to generate valid values
Refer to RunDetailsCommon for more details
Remarks
Since 1.25.0
Modifiers
- @public

property counterexample

counterexample: null;

property counterexamplePath

counterexamplePath: null;

property errorInstance

errorInstance: null;

property failed

failed: true;

property interrupted

interrupted: false;

interface RunDetailsSuccess

interface RunDetailsSuccess<Ts> extends RunDetailsCommon<Ts> {}

Run reported as success
Refer to RunDetailsCommon for more details
Remarks
Since 1.25.0
Modifiers
- @public

property counterexample

counterexample: null;

property counterexamplePath

counterexamplePath: null;

property errorInstance

errorInstance: null;

property failed

failed: false;

property interrupted

interrupted: boolean;

interface Scheduler

interface Scheduler<TMetaData = unknown> {}

Instance able to reschedule the ordering of promises for a given app
Remarks
Since 1.20.0
Modifiers
- @public

property report

report: () => SchedulerReportItem<TMetaData>[];

Produce an array containing all the scheduled tasks so far with their execution status. If the task has been executed, it includes a string representation of the associated output or error produced by the task if any.
Tasks will be returned in the order they get executed by the scheduler.
Remarks
Since 1.25.0

property schedule

schedule: <T>(
    task: Promise<T>,
    label?: string,
    metadata?: TMetaData,
    customAct?: SchedulerAct
) => Promise<T>;

Wrap a new task using the Scheduler
Remarks
Since 1.20.0

property scheduleFunction

scheduleFunction: <TArgs extends any[], T>(
    asyncFunction: (...args: TArgs) => Promise<T>,
    customAct?: SchedulerAct
) => (...args: TArgs) => Promise<T>;

Automatically wrap function output using the Scheduler
Remarks
Since 1.20.0

property waitAll

waitAll: (customAct?: SchedulerAct) => Promise<void>;

Wait all scheduled tasks, including the ones that might be created by one of the resolved task
Remarks
Since 1.20.0
Deprecated
Use waitIdle() instead, it comes with a more predictable behavior awaiting all scheduled and reachable tasks to be completed

property waitFor

waitFor: <T>(
    unscheduledTask: Promise<T>,
    customAct?: SchedulerAct
) => Promise<T>;

Wait as many scheduled tasks as need to resolve the received Promise
Some tests frameworks like supertest are not triggering calls to subsequent queries in a synchronous way, some are waiting an explicit call to then to trigger them (either synchronously or asynchronously)... As a consequence, none of waitOne or waitAll cannot wait for them out-of-the-box.
This helper is responsible to wait as many scheduled tasks as needed (but the bare minimal) to get unscheduledTask resolved. Once resolved it returns its output either success or failure.
Be aware that while this helper will wait eveything to be ready for unscheduledTask to resolve, having uncontrolled tasks triggering stuff required for unscheduledTask might be a source a uncontrollable and not reproducible randomness as those triggers cannot be handled and scheduled by fast-check.
Remarks
Since 2.24.0

property waitIdle

waitIdle: (customAct?: SchedulerAct) => Promise<void>;

Wait until the scheduler becomes idle: all scheduled and reachable tasks have completed.
It will include tasks scheduled by other tasks, recursively.
Note: Tasks triggered by uncontrolled sources (like fetch or external events) cannot be detected or awaited and may lead to incomplete waits.
If you want to wait for a precise event to happen you should rather opt for waitFor or waitNext given they offer you a more granular control on what you are exactly waiting for.
Remarks
Since 4.2.0

property waitNext

waitNext: (count: number, customAct?: SchedulerAct) => Promise<void>;

Wait and schedule exactly count scheduled tasks.
Remarks
Since 4.2.0

property waitOne

waitOne: (customAct?: SchedulerAct) => Promise<void>;

Wait one scheduled task to be executed
Throws
Whenever there is no task scheduled
Remarks
Since 1.20.0
Deprecated
Use waitNext(1) instead, it comes with a more predictable behavior

method count

count: () => number;

Count of pending scheduled tasks
Remarks
Since 1.20.0

method scheduleSequence

scheduleSequence: (
    sequenceBuilders: SchedulerSequenceItem<TMetaData>[],
    customAct?: SchedulerAct
) => {
    done: boolean;
    faulty: boolean;
    task: Promise<{ done: boolean; faulty: boolean }>;
};

Schedule a sequence of Promise to be executed sequencially. Items within the sequence might be interleaved by other scheduled operations.
Please note that whenever an item from the sequence has started, the scheduler will wait until its end before moving to another scheduled task.
A handle is returned by the function in order to monitor the state of the sequence. Sequence will be marked: - done if all the promises have been executed properly - faulty if one of the promises within the sequence throws
Remarks
Since 1.20.0

interface SchedulerConstraints

interface SchedulerConstraints {}

Constraints to be applied on scheduler
Remarks
Since 2.2.0
Modifiers
- @public

property act

act: (f: () => Promise<void>) => Promise<unknown>;

Ensure that all scheduled tasks will be executed in the right context (for instance it can be the act of React)
Remarks
Since 1.21.0

interface SchedulerReportItem

interface SchedulerReportItem<TMetaData = unknown> {}

Describe a task for the report produced by the scheduler
Remarks
Since 1.25.0
Modifiers
- @public

property label

label: string;

Label of the task
Remarks
Since 1.25.0

property metadata

metadata?: TMetaData;

Metadata linked when scheduling the task
Remarks
Since 1.25.0

property outputValue

outputValue?: string;

Stringified version of the output or error computed using fc.stringify
Remarks
Since 1.25.0

property schedulingType

schedulingType: 'promise' | 'function' | 'sequence';

How was this task scheduled? - promise: schedule - function: scheduleFunction - sequence: scheduleSequence
Remarks
Since 1.25.0

property status

status: 'resolved' | 'rejected' | 'pending';

Execution status for this task - resolved: task released by the scheduler and successful - rejected: task released by the scheduler but with errors - pending: task still pending in the scheduler, not released yet
Remarks
Since 1.25.0

property taskId

taskId: number;

Incremental id for the task, first received task has taskId = 1
Remarks
Since 1.25.0

interface ShuffledSubarrayConstraints

interface ShuffledSubarrayConstraints {}

Constraints to be applied on shuffledSubarray
Remarks
Since 2.18.0
Modifiers
- @public

property maxLength

maxLength?: number;

Upper bound of the generated subarray size (included)
Remarks
Since 2.4.0

property minLength

minLength?: number;

Lower bound of the generated subarray size (included)
Remarks
Since 2.4.0

interface SparseArrayConstraints

interface SparseArrayConstraints {}

Constraints to be applied on sparseArray
Remarks
Since 2.13.0
Modifiers
- @public

property depthIdentifier

depthIdentifier?: DepthIdentifier | string;

When receiving a depth identifier, the arbitrary will impact the depth attached to it to avoid going too deep if it already generated lots of items.
In other words, if the number of generated values within the collection is large then the generated items will tend to be less deep to avoid creating structures a lot larger than expected.
For the moment, the depth is not taken into account to compute the number of items to define for a precise generate call of the array. Just applied onto eligible items.
Remarks
Since 2.25.0

property maxLength

maxLength?: number;

Upper bound of the generated array size (maximal size: 4294967295)
Remarks
Since 2.13.0

property maxNumElements

maxNumElements?: number;

Upper bound of the number of non-hole elements
Remarks
Since 2.13.0

property minNumElements

minNumElements?: number;

Lower bound of the number of non-hole elements
Remarks
Since 2.13.0

property noTrailingHole

noTrailingHole?: boolean;

When enabled, all generated arrays will either be the empty array or end by a non-hole
Remarks
Since 2.13.0

property size

size?: SizeForArbitrary;

Define how large the generated values should be (at max)
Remarks
Since 2.22.0

interface StringSharedConstraints

interface StringSharedConstraints {}

Constraints to be applied on arbitraries for strings
Remarks
Since 2.4.0
Modifiers
- @public

property maxLength

maxLength?: number;

Upper bound of the generated string length (included)
Remarks
Since 2.4.0

property minLength

minLength?: number;

Lower bound of the generated string length (included)
Remarks
Since 2.4.0

property size

size?: SizeForArbitrary;

Define how large the generated values should be (at max)
Remarks
Since 2.22.0

interface SubarrayConstraints

interface SubarrayConstraints {}

Constraints to be applied on subarray
Remarks
Since 2.4.0
Modifiers
- @public

property maxLength

maxLength?: number;

Upper bound of the generated subarray size (included)
Remarks
Since 2.4.0

property minLength

minLength?: number;

Lower bound of the generated subarray size (included)
Remarks
Since 2.4.0

interface UuidConstraints

interface UuidConstraints {}

Constraints to be applied on uuid
Remarks
Since 3.21.0
Modifiers
- @public

property version

version?:
    | (1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15)
    | (1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15)[];

Define accepted versions in the [1-15] according to RFC 9562
Remarks
Since 3.21.0

interface WebAuthorityConstraints

interface WebAuthorityConstraints {}

Constraints to be applied on webAuthority
Remarks
Since 1.14.0
Modifiers
- @public

property size

size?: Exclude<SizeForArbitrary, 'max'>;

Define how large the generated values should be (at max)
Remarks
Since 2.22.0

property withIPv4

withIPv4?: boolean;

Enable IPv4 in host
Remarks
Since 1.14.0

property withIPv4Extended

withIPv4Extended?: boolean;

Enable extended IPv4 format
Remarks
Since 1.17.0

property withIPv6

withIPv6?: boolean;

Enable IPv6 in host
Remarks
Since 1.14.0

property withPort

withPort?: boolean;

Enable port suffix
Remarks
Since 1.14.0

property withUserInfo

withUserInfo?: boolean;

Enable user information prefix
Remarks
Since 1.14.0

interface WebFragmentsConstraints

interface WebFragmentsConstraints {}

Constraints to be applied on webFragments
Remarks
Since 2.22.0
Modifiers
- @public

property size

size?: Exclude<SizeForArbitrary, 'max'>;

Define how large the generated values should be (at max)
Remarks
Since 2.22.0

interface WebPathConstraints

interface WebPathConstraints {}

Constraints to be applied on webPath
Remarks
Since 3.3.0
Modifiers
- @public

property size

size?: Exclude<SizeForArbitrary, 'max'>;

Define how large the generated values should be (at max)
Remarks
Since 3.3.0

interface WebQueryParametersConstraints

interface WebQueryParametersConstraints {}

Constraints to be applied on webQueryParameters
Remarks
Since 2.22.0
Modifiers
- @public

property size

size?: Exclude<SizeForArbitrary, 'max'>;

Define how large the generated values should be (at max)
Remarks
Since 2.22.0

interface WebSegmentConstraints

interface WebSegmentConstraints {}

Constraints to be applied on webSegment
Remarks
Since 2.22.0
Modifiers
- @public

property size

size?: Exclude<SizeForArbitrary, 'max'>;

Define how large the generated values should be (at max)
Remarks
Since 2.22.0

interface WebUrlConstraints

interface WebUrlConstraints {}

Constraints to be applied on webUrl
Remarks
Since 1.14.0
Modifiers
- @public

property authoritySettings

authoritySettings?: WebAuthorityConstraints;

Settings for webAuthority
Remarks
Since 1.14.0

property size

size?: Exclude<SizeForArbitrary, 'max'>;

Define how large the generated values should be (at max)
Remarks
Since 2.22.0

property validSchemes

validSchemes?: string[];

Enforce specific schemes, eg.: http, https
Remarks
Since 1.14.0

property withFragments

withFragments?: boolean;

Enable fragments in the generated url
Remarks
Since 1.14.0

property withQueryParameters

withQueryParameters?: boolean;

Enable query parameters in the generated url
Remarks
Since 1.14.0

interface WeightedArbitrary

interface WeightedArbitrary<T> {}

Conjonction of a weight and an arbitrary used by oneof in order to generate values
Remarks
Since 1.18.0
Modifiers
- @public

property arbitrary

arbitrary: Arbitrary<T>;

Instance of Arbitrary
Remarks
Since 0.0.7

property weight

weight: number;

Weight to be applied when selecting which arbitrary should be used
Remarks
Since 0.0.7

interface WithCloneMethod

interface WithCloneMethod<T> {}

Object instance that should be cloned from one generation/shrink to another
Remarks
Since 2.15.0
Modifiers
- @public

property [cloneMethod]

[cloneMethod]: () => T;

enum ExecutionStatus

enum ExecutionStatus {
    Success = 0,
    Skipped = -1,
    Failure = 1,
}

Status of the execution of the property
Remarks
Since 1.9.0
Modifiers
- @public

member Failure

Failure = 1

member Skipped

Skipped = -1

member Success

Success = 0

enum VerbosityLevel

enum VerbosityLevel {
    None = 0,
    Verbose = 1,
    VeryVerbose = 2,
}

Verbosity level
Remarks
Since 1.9.1
Modifiers
- @public

member None

None = 0

Level 0 (default)
Minimal reporting: - minimal failing case - error log corresponding to the minimal failing case
Remarks
Since 1.9.1

member Verbose

Verbose = 1

Level 1
Failures reporting: - same as VerbosityLevel.None - list all the failures encountered during the shrinking process
Remarks
Since 1.9.1

member VeryVerbose

VeryVerbose = 2

Level 2
Execution flow reporting: - same as VerbosityLevel.None - all runs with their associated status displayed as a tree
Remarks
Since 1.9.1

type AsyncPropertyHookFunction

type AsyncPropertyHookFunction =
    | ((previousHookFunction: GlobalAsyncPropertyHookFunction) => Promise<unknown>)
    | ((previousHookFunction: GlobalAsyncPropertyHookFunction) => void);

Type of legal hook function that can be used to call beforeEach or afterEach on a IAsyncPropertyWithHooks
Remarks
Since 2.2.0
Modifiers
- @public

type BigIntArrayConstraints

type BigIntArrayConstraints = {
    /**
     * Lower bound of the generated array size
     * @defaultValue 0
     * @remarks Since 3.0.0
     */
    minLength?: number;
    /**
     * Upper bound of the generated array size
     * @defaultValue 0x7fffffff — _defaulting seen as "max non specified" when `defaultSizeToMaxWhenMaxSpecified=true`_
     * @remarks Since 3.0.0
     */
    maxLength?: number;
    /**
     * Lower bound for the generated int (included)
     * @defaultValue smallest possible value for this type
     * @remarks Since 3.0.0
     */
    min?: bigint;
    /**
     * Upper bound for the generated int (included)
     * @defaultValue highest possible value for this type
     * @remarks Since 3.0.0
     */
    max?: bigint;
    /**
     * Define how large the generated values should be (at max)
     * @remarks Since 3.0.0
     */
    size?: SizeForArbitrary;
};

Constraints to be applied on typed arrays for big int values
Remarks
Since 3.0.0
Modifiers
- @public

type CloneValue

type CloneValue<T, N extends number, Rest extends T[] = []> = [number] extends [N]
    ? T[]
    : Rest['length'] extends N
    ? Rest
    : CloneValue<T, N, [T, ...Rest]>;

Type of the value produced by clone
Remarks
Since 2.5.0
Modifiers
- @public

type DepthContext

type DepthContext = {
    /**
     * Current depth (starts at 0, continues with 1, 2...).
     * Only made of integer values superior or equal to 0.
     *
     * Remark: Whenever altering the `depth` during a `generate`, please make sure to ALWAYS
     * reset it to its original value before you leave the `generate`. Otherwise the execution
     * will imply side-effects that will potentially impact the following runs and make replay
     * of the issue barely impossible.
     */
    depth: number;
};

Instance of depth, can be used to alter the depth perceived by an arbitrary or to bias your own arbitraries based on the current depth
Remarks
Since 2.25.0
Modifiers
- @public

type DepthIdentifier

type DepthIdentifier = {} & DepthContext;

Type used to strongly type instances of depth identifier while keeping internals what they contain internally
Remarks
Since 2.25.0
Modifiers
- @public

type DepthSize

type DepthSize = RelativeSize | Size | 'max' | number | undefined;

Superset of Size to override the default defined for size. It can either be based on a numeric value manually selected by the user (not recommended) or rely on presets based on size (recommended).
This size will be used to infer a bias to limit the depth, used as follow within recursive structures: While going deeper, the bias on depth will increase the probability to generate small instances.
When used with Size, the larger the size the deeper the structure. When used with numeric values, the larger the number (floating point number >= 0), the deeper the structure. +0 means extremelly biased depth meaning barely impossible to generate deep structures, while Number.POSITIVE_INFINITY means "depth has no impact".
Using max or Number.POSITIVE_INFINITY is fully equivalent.
Remarks
Since 2.25.0
Modifiers
- @public

type EntityGraphArbitraries

type Arbitraries<TEntityFields> = {
    [TEntityName in keyof TEntityFields]: ArbitraryStructure<
        TEntityFields[TEntityName]
    >;
};

Defines all entity types and their data fields for entityGraph.
This is the first argument to entityGraph and specifies the non-relational properties of each entity type. Each key is the name of an entity type and its value defines the arbitraries for that entity.
Remarks
Since 4.5.0
Example 1
{ employee: { name: fc.string(), age: fc.nat(100) }, team: { name: fc.string(), size: fc.nat(50) } }
Modifiers
- @public

type EntityGraphContraints

type EntityGraphContraints<TEntityFields> = {
    /**
     * Controls the minimum number of entities generated for each entity type in the initial pool.
     *
     * The initial pool defines the baseline set of entities that are created before any relationships
     * are established. Other entities may be created later to satisfy relationship requirements.
     *
     * @example
     * ```typescript
     * // Ensure at least 2 employees and at most 5 teams in the initial pool
     * // But possibly more than 5 teams at the end
     * { initialPoolConstraints: { employee: { minLength: 2 }, team: { maxLength: 5 } } }
     * ```
     *
     * @defaultValue When unspecified, defaults from {@link array} are used for each entity type
     * @remarks Since 4.5.0
     */
    initialPoolConstraints?: {
        [EntityName in keyof TEntityFields]?: ArrayConstraints;
    };
    /**
     * Defines uniqueness criteria for entities of each type to prevent duplicate values.
     *
     * The selector function extracts a key from each entity. Entities with identical keys
     * (compared using `Object.is`) are considered duplicates and only one instance will be kept.
     *
     * @example
     * ```typescript
     * // Ensure employees have unique names
     * { unicityConstraints: { employee: (emp) => emp.name } }
     * ```
     *
     * @defaultValue All entities are considered unique (no deduplication is performed)
     * @remarks Since 4.5.0
     */
    unicityConstraints?: {
        [EntityName in keyof TEntityFields]?: UniqueArrayConstraintsRecommended<
            TEntityFields[EntityName],
            unknown
        >['selector'];
    };
    /**
     * Do not generate values with null prototype
     * @defaultValue false
     * @remarks Since 4.5.0
     */
    noNullPrototype?: boolean;
};

Constraints to be applied on entityGraph
Remarks
Since 4.5.0
Modifiers
- @public

type EntityGraphRelations

type EntityRelations<TEntityFields> = {
    [TEntityName in keyof TEntityFields]: {
        [TField in string]: Relationship<keyof TEntityFields>;
    };
};

Defines all relationships between entity types for entityGraph.
This is the second argument to entityGraph and specifies how entities reference each other. Each entity type can have zero or more relationship fields, where each field defines a link to other entities.
Remarks
Since 4.5.0
Example 1
{ employee: { manager: { arity: '0-1', type: 'employee' }, team: { arity: '1', type: 'team' } }, team: {} }
Modifiers
- @public

type EntityGraphValue

type EntityGraphValue<
    TEntityFields,
    TEntityRelations extends EntityRelations<TEntityFields>
> = {
    [TEntityName in keyof EntityGraphSingleValue<
        TEntityFields,
        TEntityRelations
    >]: EntityGraphSingleValue<TEntityFields, TEntityRelations>[TEntityName][];
};

Type of the values generated by entityGraph.
The output is an object where each key is an entity type name and each value is an array of entities of that type. Each entity contains both its data fields (from arbitraries) and relationship fields (from relations), with relationships resolved to actual entity references.
Remarks
Since 4.5.0
Modifiers
- @public

type FalsyValue

type FalsyValue<TConstraints extends FalsyContraints = object> =
    | false
    | null
    | 0
    | ''
    | typeof NaN
    | undefined
    | (TConstraints extends {
          withBigInt: true;
      }
          ? 0n
          : never);

Typing for values generated by falsy
Remarks
Since 2.2.0
Modifiers
- @public

type Float32ArrayConstraints

type Float32ArrayConstraints = {
    /**
     * Lower bound of the generated array size
     * @defaultValue 0
     * @remarks Since 2.9.0
     */
    minLength?: number;
    /**
     * Upper bound of the generated array size
     * @defaultValue 0x7fffffff — _defaulting seen as "max non specified" when `defaultSizeToMaxWhenMaxSpecified=true`_
     * @remarks Since 2.9.0
     */
    maxLength?: number;
    /**
     * Define how large the generated values should be (at max)
     * @remarks Since 2.22.0
     */
    size?: SizeForArbitrary;
} & FloatConstraints;

Constraints to be applied on float32Array
Remarks
Since 2.9.0
Modifiers
- @public

type Float64ArrayConstraints

type Float64ArrayConstraints = {
    /**
     * Lower bound of the generated array size
     * @defaultValue 0
     * @remarks Since 2.9.0
     */
    minLength?: number;
    /**
     * Upper bound of the generated array size
     * @defaultValue 0x7fffffff — _defaulting seen as "max non specified" when `defaultSizeToMaxWhenMaxSpecified=true`_
     * @remarks Since 2.9.0
     */
    maxLength?: number;
    /**
     * Define how large the generated values should be (at max)
     * @remarks Since 2.22.0
     */
    size?: SizeForArbitrary;
} & DoubleConstraints;

Constraints to be applied on float64Array
Remarks
Since 2.9.0
Modifiers
- @public

type GeneratorValue

type GeneratorValue = GeneratorValueFunction & GeneratorValueMethods;

An instance of GeneratorValue can be leveraged within predicates themselves to produce extra random values while preserving part of the shrinking capabilities on the produced values.
It can be seen as a way to start property based testing within something looking closer from what users will think about when thinking about random in tests. But contrary to raw random, it comes with many useful strengths such as: ability to re-run the test (seeded), shrinking...
Remarks
Since 3.8.0
Modifiers
- @public

type GlobalAsyncPropertyHookFunction

type GlobalAsyncPropertyHookFunction = (() => Promise<unknown>) | (() => void);

Type of legal hook function that can be used in the global parameter asyncBeforeEach and/or asyncAfterEach
Remarks
Since 2.3.0
Modifiers
- @public

type GlobalParameters

type GlobalParameters = Pick<
    Parameters<unknown>,
    Exclude<keyof Parameters<unknown>, 'path' | 'examples'>
> & {
    /**
     * Specify a function that will be called before each execution of a property.
     * It behaves as-if you manually called `beforeEach` method on all the properties you execute with fast-check.
     *
     * The function will be used for both {@link fast-check#property} and {@link fast-check#asyncProperty}.
     * This global override should never be used in conjunction with `asyncBeforeEach`.
     *
     * @remarks Since 2.3.0
     */
    beforeEach?: GlobalPropertyHookFunction;
    /**
     * Specify a function that will be called after each execution of a property.
     * It behaves as-if you manually called `afterEach` method on all the properties you execute with fast-check.
     *
     * The function will be used for both {@link fast-check#property} and {@link fast-check#asyncProperty}.
     * This global override should never be used in conjunction with `asyncAfterEach`.
     *
     * @remarks Since 2.3.0
     */
    afterEach?: GlobalPropertyHookFunction;
    /**
     * Specify a function that will be called before each execution of an asynchronous property.
     * It behaves as-if you manually called `beforeEach` method on all the asynchronous properties you execute with fast-check.
     *
     * The function will be used only for {@link fast-check#asyncProperty}. It makes synchronous properties created by {@link fast-check#property} unable to run.
     * This global override should never be used in conjunction with `beforeEach`.
     *
     * @remarks Since 2.3.0
     */
    asyncBeforeEach?: GlobalAsyncPropertyHookFunction;
    /**
     * Specify a function that will be called after each execution of an asynchronous property.
     * It behaves as-if you manually called `afterEach` method on all the asynchronous properties you execute with fast-check.
     *
     * The function will be used only for {@link fast-check#asyncProperty}. It makes synchronous properties created by {@link fast-check#property} unable to run.
     * This global override should never be used in conjunction with `afterEach`.
     *
     * @remarks Since 2.3.0
     */
    asyncAfterEach?: GlobalAsyncPropertyHookFunction;
    /**
     * Define the base size to be used by arbitraries.
     *
     * By default arbitraries not specifying any size will default to it (except in some cases when used defaultSizeToMaxWhenMaxSpecified is true).
     * For some arbitraries users will want to override the default and either define another size relative to this one,
     * or a fixed one.
     *
     * @defaultValue `"small"`
     * @remarks Since 2.22.0
     */
    baseSize?: Size;
    /**
     * When set to `true` and if the size has not been defined for this precise instance,
     * it will automatically default to `"max"` if the user specified a upper bound for the range
     * (applies to length and to depth).
     *
     * When `false`, the size will be defaulted to `baseSize` even if the user specified
     * a upper bound for the range.
     *
     * @remarks Since 2.22.0
     */
    defaultSizeToMaxWhenMaxSpecified?: boolean;
};

Type describing the global overrides
Remarks
Since 1.18.0
Modifiers
- @public

type GlobalPropertyHookFunction

type GlobalPropertyHookFunction = () => void;

Type of legal hook function that can be used in the global parameter beforeEach and/or afterEach
Remarks
Since 2.3.0
Modifiers
- @public

type IntArrayConstraints

type IntArrayConstraints = {
    /**
     * Lower bound of the generated array size
     * @defaultValue 0
     * @remarks Since 2.9.0
     */
    minLength?: number;
    /**
     * Upper bound of the generated array size
     * @defaultValue 0x7fffffff — _defaulting seen as "max non specified" when `defaultSizeToMaxWhenMaxSpecified=true`_
     * @remarks Since 2.9.0
     */
    maxLength?: number;
    /**
     * Lower bound for the generated int (included)
     * @defaultValue smallest possible value for this type
     * @remarks Since 2.9.0
     */
    min?: number;
    /**
     * Upper bound for the generated int (included)
     * @defaultValue highest possible value for this type
     * @remarks Since 2.9.0
     */
    max?: number;
    /**
     * Define how large the generated values should be (at max)
     * @remarks Since 2.22.0
     */
    size?: SizeForArbitrary;
};

Constraints to be applied on typed arrays for integer values
Remarks
Since 2.9.0
Modifiers
- @public

type JsonValue

type JsonValue = boolean | number | string | null | JsonArray | JsonObject;

Typings for a Json value
Remarks
Since 2.20.0
Modifiers
- @public

type LetrecLooselyTypedBuilder

type LetrecLooselyTypedBuilder<T> = (tie: LetrecLooselyTypedTie) => LetrecValue<T>;

Loosely typed type for the builder function passed to letrec. You may want also want to use its strongly typed version LetrecTypedBuilder.
Remarks
Since 3.0.0
Modifiers
- @public

type LetrecLooselyTypedTie

type LetrecLooselyTypedTie = (key: string) => Arbitrary<unknown>;

Loosely typed type for the tie function passed by letrec to the builder function we pass to it. You may want also want to use its strongly typed version LetrecTypedTie.
Remarks
Since 3.0.0
Modifiers
- @public

type LetrecTypedBuilder

type LetrecTypedBuilder<T> = (tie: LetrecTypedTie<T>) => LetrecValue<T>;

Strongly typed type for the builder function passed to letrec. You may want also want to use its loosely typed version LetrecLooselyTypedBuilder.
Remarks
Since 3.0.0
Modifiers
- @public

type LetrecValue

type LetrecValue<T> = { [K in keyof T]: Arbitrary<T[K]> };

Type of the value produced by letrec
Remarks
Since 3.0.0
Modifiers
- @public

type MaybeWeightedArbitrary

type MaybeWeightedArbitrary<T> = Arbitrary<T> | WeightedArbitrary<T>;

Either an Arbitrary<T> or a WeightedArbitrary<T>
Remarks
Since 3.0.0
Modifiers
- @public

type Memo

type Memo<T> = (maxDepth?: number) => Arbitrary<T>;

Output type for memo
Remarks
Since 1.16.0
Modifiers
- @public

type ModelRunAsyncSetup

type ModelRunAsyncSetup<Model, Real> = () => Promise<{
    model: Model;
    real: Real;
}>;

Asynchronous definition of model and real
Remarks
Since 2.2.0
Modifiers
- @public

type ModelRunSetup

type ModelRunSetup<Model, Real> = () => {
    model: Model;
    real: Real;
};

Synchronous definition of model and real
Remarks
Since 2.2.0
Modifiers
- @public

type OneOfConstraints

type OneOfConstraints = {
    /**
     * When set to true, the shrinker of oneof will try to check if the first arbitrary
     * could have been used to discover an issue. It allows to shrink trees.
     *
     * Warning: First arbitrary must be the one resulting in the smallest structures
     * for usages in deep tree-like structures.
     *
     * @defaultValue false
     * @remarks Since 2.14.0
     */
    withCrossShrink?: boolean;
    /**
     * While going deeper and deeper within a recursive structure (see {@link letrec}),
     * this factor will be used to increase the probability to generate instances
     * of the first passed arbitrary.
     *
     * @remarks Since 2.14.0
     */
    depthSize?: DepthSize;
    /**
     * Maximal authorized depth.
     * Once this depth has been reached only the first arbitrary will be used.
     *
     * @defaultValue Number.POSITIVE_INFINITY — _defaulting seen as "max non specified" when `defaultSizeToMaxWhenMaxSpecified=true`_
     * @remarks Since 2.14.0
     */
    maxDepth?: number;
    /**
     * Depth identifier can be used to share the current depth between several instances.
     *
     * By default, if not specified, each instance of oneof will have its own depth.
     * In other words: you can have depth=1 in one while you have depth=100 in another one.
     *
     * @remarks Since 2.14.0
     */
    depthIdentifier?: DepthIdentifier | string;
};

Constraints to be applied on oneof
Remarks
Since 2.14.0
Modifiers
- @public

type OneOfValue

type OneOfValue<Ts extends MaybeWeightedArbitrary<unknown>[]> = {
    [K in keyof Ts]: Ts[K] extends MaybeWeightedArbitrary<infer U> ? U : never;
}[number];

Infer the type of the Arbitrary produced by oneof given the type of the source arbitraries
Remarks
Since 2.2.0
Modifiers
- @public

type PropertyFailure

type PropertyFailure = {
    /**
     * The original error that has been intercepted.
     * Possibly not an instance Error as users can throw anything.
     * @remarks Since 3.0.0
     */
    error: unknown;
};

Represent failures of the property
Remarks
Since 3.0.0
Modifiers
- @public

type PropertyHookFunction

type PropertyHookFunction = (globalHookFunction: GlobalPropertyHookFunction) => void;

Type of legal hook function that can be used to call beforeEach or afterEach on a IPropertyWithHooks
Remarks
Since 2.2.0
Modifiers
- @public

type RandomGenerator

type RandomGenerator =
    | RandomGenerator7x
    | RandomGenerator$1
    | JumpableRandomGenerator;

Merged type supporting both pure-rand v7 and v8 random generators. Keeping compatibility with v7 avoids a breaking API change and a new major version.
Remarks
Since 4.6.0
Modifiers
- @public

type RandomType

type RandomType =
    | 'mersenne'
    | 'congruential'
    | 'congruential32'
    | 'xorshift128plus'
    | 'xoroshiro128plus';

Random generators automatically recognized by the framework without having to pass a builder function
Remarks
Since 2.2.0
Modifiers
- @public

type RecordConstraints

type RecordConstraints<T = unknown> = {
    /**
     * List keys that should never be deleted.
     *
     * Remark:
     * You might need to use an explicit typing in case you need to declare symbols as required (not needed when required keys are simple strings).
     * With something like `{ requiredKeys: [mySymbol1, 'a'] as [typeof mySymbol1, 'a'] }` when both `mySymbol1` and `a` are required.
     *
     * @defaultValue Array containing all keys of recordModel
     * @remarks Since 2.11.0
     */
    requiredKeys?: T[];
    /**
     * Do not generate records with null prototype
     * @defaultValue false
     * @remarks Since 3.13.0
     */
    noNullPrototype?: boolean;
};

Constraints to be applied on record
Remarks
Since 0.0.12
Modifiers
- @public

type RecordValue

type RecordValue<T, K> = Prettify<Partial<T> & Pick<T, K & keyof T>>;

Infer the type of the Arbitrary produced by record given the type of the source arbitrary and constraints to be applied
Remarks
Since 2.2.0
Modifiers
- @public

type RunDetails

type RunDetails<Ts> =
    | RunDetailsFailureProperty<Ts>
    | RunDetailsFailureTooManySkips<Ts>
    | RunDetailsFailureInterrupted<Ts>
    | RunDetailsSuccess<Ts>;

Post-run details produced by check
A failing property can easily detected by checking the failed flag of this structure
Remarks
Since 0.0.7
Modifiers
- @public

type SchedulerAct

type SchedulerAct = (f: () => Promise<void>) => Promise<void>;

Function responsible to run the passed function and surround it with whatever needed. The name has been inspired from the act function coming with React.
This wrapper function is not supposed to throw. The received function f will never throw.
Wrapping order in the following:
- global act defined on fc.scheduler wraps wait level one - wait act defined on s.waitX wraps local one - local act defined on s.scheduleX(...) wraps the trigger function
Remarks
Since 3.9.0
Modifiers
- @public

type SchedulerSequenceItem

type SchedulerSequenceItem<TMetaData = unknown> =
    | {
          /**
           * Builder to start the task
           * @remarks Since 1.20.0
           */
          builder: () => Promise<any>;
          /**
           * Label
           * @remarks Since 1.20.0
           */
          label: string;
          /**
           * Metadata to be attached into logs
           * @remarks Since 1.25.0
           */
          metadata?: TMetaData;
      }
    | (() => Promise<any>);

Define an item to be passed to scheduleSequence
Remarks
Since 1.20.0
Modifiers
- @public

type SetConstraints

type SetConstraints = {
    /**
     * Lower bound of the generated set size
     * @defaultValue 0
     * @remarks Since 4.4.0
     */
    minLength?: number;
    /**
     * Upper bound of the generated set size
     * @defaultValue 0x7fffffff — _defaulting seen as "max non specified" when `defaultSizeToMaxWhenMaxSpecified=true`_
     * @remarks Since 4.4.0
     */
    maxLength?: number;
    /**
     * Define how large the generated values should be (at max)
     * @remarks Since 4.4.0
     */
    size?: SizeForArbitrary;
    /**
     * When receiving a depth identifier, the arbitrary will impact the depth
     * attached to it to avoid going too deep if it already generated lots of items.
     *
     * In other words, if the number of generated values within the collection is large
     * then the generated items will tend to be less deep to avoid creating structures a lot
     * larger than expected.
     *
     * For the moment, the depth is not taken into account to compute the number of items to
     * define for a precise generate call of the set. Just applied onto eligible items.
     *
     * @remarks Since 4.4.0
     */
    depthIdentifier?: DepthIdentifier | string;
};

Constraints to be applied on set
Remarks
Since 4.4.0
Modifiers
- @public

type Size

type Size = 'xsmall' | 'small' | 'medium' | 'large' | 'xlarge';

The size parameter defines how large the generated values could be.
The default in fast-check is 'small' but it could be increased (resp. decreased) to ask arbitraries for larger (resp. smaller) values.
Remarks
Since 2.22.0
Modifiers
- @public

type SizeForArbitrary

type SizeForArbitrary = RelativeSize | Size | 'max' | undefined;

Superset of Size to override the default defined for size
Remarks
Since 2.22.0
Modifiers
- @public

type StringConstraints

type StringConstraints = StringSharedConstraints & {
    /**
     * A string results from the join between several unitary strings produced by the Arbitrary instance defined by `unit`.
     * The `minLength` and `maxLength` refers to the number of these units composing the string. In other words it does not have to be confound with `.length` on an instance of string.
     *
     * A unit can either be a fully custom Arbitrary or one of the pre-defined options:
     * - `'grapheme'` - Any printable grapheme as defined by the Unicode standard. This unit includes graphemes that may:
     *   - Span multiple code points (e.g., `'\u{0061}\u{0300}'`)
     *   - Consist of multiple characters (e.g., `'\u{1f431}'`)
     *   - Include non-European and non-ASCII characters.
     *   - **Note:** Graphemes produced by this unit are designed to remain visually distinct when joined together.
     *   - **Note:** We are relying on the specifications of Unicode 15.
     * - `'grapheme-composite'` - Any printable grapheme limited to a single code point. This option produces graphemes limited to a single code point.
     *   - **Note:** Graphemes produced by this unit are designed to remain visually distinct when joined together.
     *   - **Note:** We are relying on the specifications of Unicode 15.
     * - `'grapheme-ascii'` - Any printable ASCII character.
     * - `'binary'` - Any possible code point (except half surrogate pairs), regardless of how it may combine with subsequent code points in the produced string. This unit produces a single code point within the full Unicode range (0000-10FFFF).
     * - `'binary-ascii'` - Any possible ASCII character, including control characters. This unit produces any code point in the range 0000-00FF.
     *
     * @defaultValue 'grapheme-ascii'
     * @remarks Since 3.22.0
     */
    unit?:
        | 'grapheme'
        | 'grapheme-composite'
        | 'grapheme-ascii'
        | 'binary'
        | 'binary-ascii'
        | Arbitrary<string>;
};

Constraints to be applied on arbitrary string
Remarks
Since 3.22.0
Modifiers
- @public

type StringMatchingConstraints

type StringMatchingConstraints = {
    /**
     * Upper bound of the generated string length (included)
     * @defaultValue 0x7fffffff
     * @remarks Since 4.6.0
     */
    maxLength?: number;
    /**
     * Define how large the generated values should be (at max)
     * @remarks Since 3.10.0
     */
    size?: SizeForArbitrary;
};

Constraints to be applied on the arbitrary stringMatching
Remarks
Since 3.10.0
Modifiers
- @public

type UniqueArrayConstraints

type UniqueArrayConstraints<T, U> =
    | UniqueArrayConstraintsRecommended<T, U>
    | UniqueArrayConstraintsCustomCompare<T>
    | UniqueArrayConstraintsCustomCompareSelect<T, U>;

Constraints implying known and optimized comparison function to be applied on uniqueArray
The defaults relies on the defaults specified by UniqueArrayConstraintsRecommended
Remarks
Since 2.23.0
Modifiers
- @public

type UniqueArrayConstraintsCustomCompare

type UniqueArrayConstraintsCustomCompare<T> = UniqueArraySharedConstraints & {
    /**
     * The operator to be used to compare the values after having applied the selector (if any)
     * @remarks Since 2.23.0
     */
    comparator: (a: T, b: T) => boolean;
    /**
     * How we should project the values before comparing them together
     * @remarks Since 2.23.0
     */
    selector?: undefined;
};

Constraints implying a fully custom comparison function to be applied on uniqueArray
WARNING - Imply an extra performance cost whenever you want to generate large arrays
Remarks
Since 2.23.0
Modifiers
- @public

type UniqueArrayConstraintsCustomCompareSelect

type UniqueArrayConstraintsCustomCompareSelect<T, U> =
    UniqueArraySharedConstraints & {
        /**
         * The operator to be used to compare the values after having applied the selector (if any)
         * @remarks Since 2.23.0
         */
        comparator: (a: U, b: U) => boolean;
        /**
         * How we should project the values before comparing them together
         * @remarks Since 2.23.0
         */
        selector: (v: T) => U;
    };

Constraints implying fully custom comparison function and selector to be applied on uniqueArray
WARNING - Imply an extra performance cost whenever you want to generate large arrays
Remarks
Since 2.23.0
Modifiers
- @public

type UniqueArrayConstraintsRecommended

type UniqueArrayConstraintsRecommended<T, U> = UniqueArraySharedConstraints & {
    /**
     * The operator to be used to compare the values after having applied the selector (if any):
     * - SameValue behaves like `Object.is` — {@link https://tc39.es/ecma262/multipage/abstract-operations.html#sec-samevalue}
     * - SameValueZero behaves like `Set` or `Map` — {@link https://tc39.es/ecma262/multipage/abstract-operations.html#sec-samevaluezero}
     * - IsStrictlyEqual behaves like `===` — {@link https://tc39.es/ecma262/multipage/abstract-operations.html#sec-isstrictlyequal}
     * - Fully custom comparison function: it implies performance costs for large arrays
     *
     * @defaultValue 'SameValue'
     * @remarks Since 2.23.0
     */
    comparator?: 'SameValue' | 'SameValueZero' | 'IsStrictlyEqual';
    /**
     * How we should project the values before comparing them together
     * @defaultValue (v =&gt; v)
     * @remarks Since 2.23.0
     */
    selector?: (v: T) => U;
};

Constraints implying known and optimized comparison function to be applied on uniqueArray
Remarks
Since 2.23.0
Modifiers
- @public

type UniqueArraySharedConstraints

type UniqueArraySharedConstraints = {
    /**
     * Lower bound of the generated array size
     * @defaultValue 0
     * @remarks Since 2.23.0
     */
    minLength?: number;
    /**
     * Upper bound of the generated array size
     * @defaultValue 0x7fffffff — _defaulting seen as "max non specified" when `defaultSizeToMaxWhenMaxSpecified=true`_
     * @remarks Since 2.23.0
     */
    maxLength?: number;
    /**
     * Define how large the generated values should be (at max)
     * @remarks Since 2.23.0
     */
    size?: SizeForArbitrary;
    /**
     * When receiving a depth identifier, the arbitrary will impact the depth
     * attached to it to avoid going too deep if it already generated lots of items.
     *
     * In other words, if the number of generated values within the collection is large
     * then the generated items will tend to be less deep to avoid creating structures a lot
     * larger than expected.
     *
     * For the moment, the depth is not taken into account to compute the number of items to
     * define for a precise generate call of the array. Just applied onto eligible items.
     *
     * @remarks Since 2.25.0
     */
    depthIdentifier?: DepthIdentifier | string;
};

Shared constraints to be applied on uniqueArray
Remarks
Since 2.23.0
Modifiers
- @public

type WithAsyncToStringMethod

type WithAsyncToStringMethod = {
    [asyncToStringMethod]: () => Promise<string>;
};

Interface to implement for asyncToStringMethod
Remarks
Since 2.17.0
Modifiers
- @public

type WithToStringMethod

type WithToStringMethod = {
    [toStringMethod]: () => string;
};

Interface to implement for toStringMethod
Remarks
Since 2.17.0
Modifiers
- @public

Package Files (1)

lib/fast-check.d.ts

Dependencies (1)

pure-rand

Dev Dependencies (10)

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this oneto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/fast-check.

Markdown

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/fast-check)

HTML

<a href="https://www.jsdocs.io/package/fast-check"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>

Updated 1 second ago.
Package analyzed in 11352 ms.
Missing or incorrect documentation? Open an issue for this package.

fast-check

Install

Overview

Index

Variables

Functions

Classes

Interfaces

Enums

Type Aliases

Namespaces

Variables

variable Arbitrary

variable asyncToStringMethod

Remarks

Modifiers

variable cloneMethod

Remarks

Modifiers

variable T

variable T

variable toStringMethod

Remarks

Modifiers

variable values

Functions

function anything

Remarks

Example 1

Modifiers

Parameter constraints

Remarks

Example 1

Example 2

Modifiers

function array

Parameter arb

Parameter constraints

Remarks

Modifiers

function assert

Parameter property

Parameter params

Remarks

Modifiers

Parameter property

Parameter params

Remarks

Modifiers

Parameter property

Parameter params

Remarks

Modifiers

function asyncDefaultReportMessage

Remarks

Modifiers

function asyncModelRun

Parameter s

Parameter cmds

Remarks

Modifiers

function asyncProperty

Parameter predicate

Remarks

Modifiers

function asyncStringify

Parameter value

Remarks

Modifiers

function base64String

Parameter constraints

Remarks

Modifiers

function bigInt

Remarks

Modifiers

Parameter min

Parameter max

Remarks

Modifiers