or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced

combinators.mdconcurrency-testing.mdmodel-based-testing.md
configuration.mdindex.md
tile.json

base-classes.mddocs/utilities/

Base Classes and Utilities

Base classes, utility functions, and helper types for advanced usage of fast-check.

Base Classes

Arbitrary

The abstract base class for all arbitraries. Provides methods for generating, shrinking, and transforming values.

abstract class Arbitrary<T> {
  abstract generate(mrng: Random, biasFactor: number | undefined): Value<T>;
  canShrinkWithoutContext(value: unknown): value is T;
  shrink(value: T, context: unknown | undefined): Stream<Value<T>>;
  filter<U extends T>(refinement: (t: T) => t is U): Arbitrary<U>;
  filter(predicate: (t: T) => boolean): Arbitrary<T>;
  map<U>(mapper: (t: T) => U, unmapper?: (u: unknown) => T): Arbitrary<U>;
  chain<U>(chainer: (t: T) => Arbitrary<U>): Arbitrary<U>;
}

Value

Holds an internal value and its associated context for shrinking.

class Value<T> {
  constructor(value_: T, context: unknown, customGetValue?: () => T);
  readonly value: T;
  readonly context: unknown;
  hasToBeCloned: boolean;
}

Random

Random number generator wrapper providing an impure interface.

class Random {
  constructor(internalRng: RandomGenerator);
  next(bits: number): number;
  nextBoolean(): boolean;
  nextInt(min?: number, max?: number): number;
  nextBigInt(min: bigint, max: bigint): bigint;
  nextDouble(): number;
  clone(): Random;
  getState(): readonly number[] | undefined;
}

Stream

Lazy iterable wrapper with functional programming helpers.

class Stream<T> {
  static nil<T>(): Stream<T>;
  static of<T>(...elements: T[]): Stream<T>;
  map<U>(f: (v: T) => U): Stream<U>;
  flatMap<U>(f: (v: T) => IterableIterator<U>): Stream<U>;
  filter(f: (v: T) => boolean): Stream<T>;
  take(n: number): Stream<T>;
  takeWhile(f: (v: T) => boolean): Stream<T>;
  drop(n: number): Stream<T>;
  dropWhile(f: (v: T) => boolean): Stream<T>;
  join(...others: IterableIterator<T>[]): Stream<T>;
  every(f: (v: T) => boolean): boolean;
  has(f: (v: T) => boolean): [boolean, T | null];
  getNthOrLast(nth: number): T | null;
}

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

Arbitrary Modifiers

Modify arbitrary behavior and access utility functions.

function noShrink<T>(arb: Arbitrary<T>): Arbitrary<T>;
function noBias<T>(arb: Arbitrary<T>): Arbitrary<T>;
function limitShrink<T>(arbitrary: Arbitrary<T>, maxShrinks: number): Arbitrary<T>;

Usage Examples:

import { noShrink, noBias, limitShrink, integer } from 'fast-check';

// Disable shrinking (useful for debugging or performance)
const noShrinkInt = noShrink(integer());

// Force uniform distribution
const uniformInt = noBias(integer({ min: 0, max: 100 }));

// Limit shrink attempts (useful for complex generators)
const limitedInt = limitShrink(integer(), 100);

Stringification Utilities

Convert values to string representations for display in failure reports.

/**
 * Convert any value to its fast-check string representation
 * @param value - Value to stringify
 * @returns String representation
 */
function stringify<Ts>(value: Ts): string;

/**
 * Async version that can inspect Promise states
 * @param value - Value to stringify
 * @returns Promise resolving to string representation
 */
function asyncStringify<Ts>(value: Ts): Promise<string>;

/**
 * Check if instance implements custom toString method
 */
function hasToStringMethod<T>(instance: T): instance is T & WithToStringMethod;

/**
 * Check if instance implements custom async toString method
 */
function hasAsyncToStringMethod<T>(instance: T): instance is T & WithAsyncToStringMethod;

// Symbols for custom stringify behavior
const toStringMethod: unique symbol;
const asyncToStringMethod: unique symbol;

interface WithToStringMethod {
  [toStringMethod](): string;
}

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

Usage Example:

import { stringify, toStringMethod } from 'fast-check';

class CustomObject {
  constructor(private data: any) {}

  [toStringMethod](): string {
    return `CustomObject(${JSON.stringify(this.data)})`;
  }
}

const obj = new CustomObject({ foo: 'bar' });
console.log(stringify(obj)); // "CustomObject({\"foo\":\"bar\"})"

Cloning Utilities

Clone values that implement custom clone methods.

/**
 * Clone an instance if it implements the clone method
 * @param instance - Instance to clone
 * @returns Cloned instance or original if no clone method
 */
function cloneIfNeeded<T>(instance: T): T;

/**
 * Check if instance implements the clone method
 */
function hasCloneMethod<T>(instance: T | WithCloneMethod<T>): instance is WithCloneMethod<T>;

// Symbol for custom clone behavior
const cloneMethod: unique symbol;

interface WithCloneMethod<T> {
  [cloneMethod](): T;
}

Usage Example:

import { cloneMethod, cloneIfNeeded } from 'fast-check';

class MutableObject {
  constructor(public value: number) {}

  [cloneMethod](): MutableObject {
    return new MutableObject(this.value);
  }
}

const obj = new MutableObject(42);
const cloned = cloneIfNeeded(obj);
cloned.value = 100;

console.log(obj.value); // 42 (original unchanged)
console.log(cloned.value); // 100

Hashing Utility

CRC-32 based hash function used internally.

/**
 * CRC-32 based hash function
 * @param repr - String representation to hash
 * @returns Hash value as number
 */
function hash(repr: string): number;

Report Formatting

Format run details for custom reporting.

/**
 * Format RunDetails using default error reporting format
 * @param out - Run details to format
 * @returns Formatted message or undefined if successful
 */
function defaultReportMessage<Ts>(out: RunDetails<Ts>): string | undefined;

/**
 * Async version of defaultReportMessage that can stringify Promises
 * @param out - Run details to format
 * @returns Promise resolving to formatted message or undefined
 */
function asyncDefaultReportMessage<Ts>(out: RunDetails<Ts>): Promise<string | undefined>;

Usage Example:

import { check, property, integer, defaultReportMessage } from 'fast-check';

const result = check(
  property(integer(), (n) => n < 100),
  { numRuns: 1000 }
);

if (result.failed) {
  const message = defaultReportMessage(result);
  console.error(message);
}

Core Types

// Property types
interface IProperty<Ts> { /* property definition */ }
interface IPropertyWithHooks<Ts> extends IProperty<Ts> {
  beforeEach(hookFunction: PropertyHookFunction): IPropertyWithHooks<Ts>;
  afterEach(hookFunction: PropertyHookFunction): IPropertyWithHooks<Ts>;
}
interface IAsyncProperty<Ts> { /* async property definition */ }
interface IAsyncPropertyWithHooks<Ts> extends IAsyncProperty<Ts> {
  beforeEach(hookFunction: AsyncPropertyHookFunction): IAsyncPropertyWithHooks<Ts>;
  afterEach(hookFunction: AsyncPropertyHookFunction): IAsyncPropertyWithHooks<Ts>;
}
interface IRawProperty<Ts> { /* base property interface */ }

// Configuration
interface Parameters<T> {
  seed?: number;
  randomType?: RandomType;
  numRuns?: number;
  maxSkipsPerRun?: number;
  timeout?: number;
  path?: string;
  unbiased?: boolean;
  verbose?: boolean | VerbosityLevel;
  examples?: T[];
  endOnFailure?: boolean;
  reporter?: (runDetails: RunDetails<T>) => void;
  asyncReporter?: (runDetails: RunDetails<T>) => Promise<void>;
  markInterruptAsFailure?: boolean;
  interruptAfterTimeLimit?: number;
  skipAllAfterTimeLimit?: number;
  skipEqualValues?: boolean;
}

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

interface RunDetailsSuccess<Ts> {
  failed: false;
  numRuns: number;
  numSkips: number;
  numShrinks: number;
  seed: number;
  counterexamplePath: string | null;
  error: null;
  failures: [];
  executionSummary: ExecutionTree<Ts>[];
  verbose: VerbosityLevel;
}

interface RunDetailsFailureProperty<Ts> {
  failed: true;
  numRuns: number;
  numSkips: number;
  numShrinks: number;
  seed: number;
  counterexamplePath: string;
  counterexample: Ts;
  error: string | Error | unknown;
  failures: Ts[];
  executionSummary: ExecutionTree<Ts>[];
  verbose: VerbosityLevel;
}

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

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

// Error class
class PreconditionFailure extends Error {
  readonly interruptExecution: true;
  readonly footprint: string;
}

// Symbols for custom behavior
const cloneMethod: unique symbol;
const toStringMethod: unique symbol;
const asyncToStringMethod: unique symbol;

interface WithCloneMethod<T> {
  [cloneMethod](): T;
}

// Package metadata
const __type: string;
const __version: string;
const __commitHash: string;