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.

Since 0.0.7

Type Parameters

  • T

Constructors

Methods

  • 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.

    Parameters

    • value: unknown

      Value to be assessed

    Returns value is T

    true if and only if the value could have been generated by this instance

    Since 3.0.0

  • 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

    Type Parameters

    • U

    Parameters

    • chainer: ((t: T) => Arbitrary<U>)

      Chain function, to produce a new Arbitrary using a value from another Arbitrary

    Returns Arbitrary<U>

    New arbitrary of new type

    const arrayAndLimitArbitrary = fc.nat().chain((c: number) => fc.tuple( fc.array(fc.nat(c)), fc.constant(c)));
    

    Since 1.2.0

  • 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

    Type Parameters

    • U

    Parameters

    • refinement: ((t: T) => t is U)

      Predicate, to test each produced element. Return true to keep the element, false otherwise

        • (t): t is U
        • Parameters

          Returns t is U

    Returns Arbitrary<U>

    New arbitrary filtered using predicate

    const integerGenerator: Arbitrary<number> = ...;
    const evenIntegerGenerator: Arbitrary<number> = integerGenerator.filter(e => e % 2 === 0);
    // new Arbitrary only keeps even values

    Since 1.23.0

  • 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

    Parameters

    • predicate: ((t: T) => boolean)

      Predicate, to test each produced element. Return true to keep the element, false otherwise

        • (t): boolean
        • Parameters

          Returns boolean

    Returns Arbitrary<T>

    New arbitrary filtered using predicate

    const integerGenerator: Arbitrary<number> = ...;
    const evenIntegerGenerator: Arbitrary<number> = integerGenerator.filter(e => e % 2 === 0);
    // new Arbitrary only keeps even values

    Since 0.0.1

  • Generate a value of type T along with its context (if any) based on the provided random number generator

    Parameters

    • mrng: Random

      Random number generator

    • biasFactor: undefined | number

      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 Value<T>

    Random value of type T and its context

    Since 0.0.1 (return type changed in 3.0.0)

  • 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

    Type Parameters

    • U

    Parameters

    • mapper: ((t: T) => U)

      Map function, to produce a new element based on an old one

        • (t): U
        • Parameters

          Returns U

    • Optionalunmapper: ((possiblyU: unknown) => T)

      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)

        • (possiblyU): T
        • Parameters

          • possiblyU: unknown

          Returns T

    Returns Arbitrary<U>

    New arbitrary with mapped elements

    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'

    Since 0.0.1

  • 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.

    Parameters

    • value: T

      The value to shrink

    • context: unknown

      Its associated context (the one returned by generate) or undefined if no context but canShrinkWithoutContext(value) === true

    Returns Stream<Value<T>>

    Stream of shrinks for value based on context (if provided)

    Since 3.0.0