Installation & Setup

Relevant source files

The following files were used as context for generating this wiki page:

• package.json
• packages/fast-check/package.json
• packages/jest/package.json
• packages/vitest/package.json
• CONTRIBUTING.md
• website/blog/2023-09-04-dual-packages-or-supporting-both-cjs-and-esm/index.md
• website/package.json
• packages/vitest/CHANGELOG.md
• packages/fast-check/test/e2e/documentation/Docs.md.spec.ts

This document provides a comprehensive guide to installing fast-check, setting up a local development environment, and understanding the project's package structure. fast-check is a property-based testing framework for JavaScript and TypeScript, designed to work seamlessly with various test runners like Jest, Mocha, and Vitest.

The setup process is designed to be straightforward for both end-users consuming the library and developers contributing to the project. The project utilizes a monorepo structure managed by pnpm and publishes dual CommonJS (CJS) and ECMAScript Module (ESM) packages to support modern and legacy JavaScript environments.

Core Package Installation

The primary package for using the framework is fast-check.

Prerequisites

• Node.js: A minimum Node.js version of 12.17.0 is required to use fast-check.
  Sources: packages/fast-check/package.json:61-63

Installation Command

To add fast-check to your project, you can use any standard package manager. The following command uses pnpm, which is also used for developing the fast-check repository itself.

pnpm add fast-check

Sources: CONTRIBUTING.md:25-27

Test Runner Integration

fast-check offers dedicated packages for easier integration with popular test runners.

Vitest Integration

The @fast-check/vitest package simplifies integration with the Vitest test runner. It supports Vitest versions from v2 to v4.

Sources: packages/vitest/CHANGELOG.md:12-14, packages/vitest/CHANGELOG.md:54-56

Jest Integration

While a dedicated @fast-check/jest package exists, the project's own test suites have migrated to Vitest. The fast-check package itself can be used directly within Jest tests without the dedicated integration package.

Sources: website/blog/2023-11-22-whats-new-in-fast-check-3-14-0/index.md:16-18, packages/packaged/CHANGELOG.md:36-38

Development Environment Setup

For contributors, setting up a local development environment involves cloning the repository and using pnpm to manage dependencies and builds.

The following diagram illustrates the initial setup workflow for new contributors.

Key Development Scripts

The repository contains several pnpm scripts to aid in development. The table below lists some of the most important ones.

Script	Description	Source File
pnpm install	Installs all dependencies across the monorepo.	CONTRIBUTING.md
pnpm --filter fast-check build	Compiles the main fast-check package.	CONTRIBUTING.md
pnpm format	Automatically formats code using Prettier.	CONTRIBUTING.md
pnpm lint	Checks the code for linting errors.	CONTRIBUTING.md
pnpm test	Runs tests for a specific package (e.g., in examples directory).	examples/package.json
pnpm start	Starts the Docusaurus development server for the website.	website/package.json

Sources: CONTRIBUTING.md:32-35, examples/package.json:6-7, website/package.json:6-7

Package Structure and Module Support

fast-check is published as a dual-mode package, supporting both CommonJS (require) and ECMAScript Modules (import). This is achieved through a specific project structure and configuration in package.json.

Dual CJS/ESM Architecture

To support both module systems, the project compiles the source code into two different output directories. A nested package.json file within the ESM output directory declares its contents as ES modules.

The diagram below shows the simplified structure for dual module support.

This diagram is a conceptual representation based on the dual-package strategy described in the blog. The actual fast-check package has evolved to set "type": "module" at the root and use a template to create a package.json with "type": "commonjs" in the lib/cjs directory.

Sources: website/blog/2023-09-04-dual-packages-or-supporting-both-cjs-and-esm/index.md, packages/fast-check/package.json:4, packages/fast-check/package.json:46-47

Package Entry Points

The exports field in packages/fast-check/package.json is crucial for directing Node.js and bundlers to the correct file based on the import method.

{
  "exports": {
    "./package.json": "./package.json",
    ".": {
      "require": {
        "types@<5.7": "./lib/cjs/types57/fast-check.d.ts",
        "types": "./lib/cjs/types/fast-check.d.ts",
        "default": "./lib/cjs/fast-check.js"
      },
      "import": {
        "types@<5.7": "./lib/types57/fast-check.d.ts",
        "types": "./lib/types/fast-check.d.ts",
        "default": "./lib/fast-check.js"
      }
    }
  }
}

Sources: packages/fast-check/package.json:6-21

This configuration ensures that:

• require('fast-check') resolves to the CommonJS version (./lib/cjs/fast-check.js).
• import ... from 'fast-check' resolves to the ESM version (./lib/fast-check.js).
• TypeScript receives the correct type definitions (.d.ts files) for each module format, with conditional types for older TypeScript versions.

Sources: website/blog/2023-09-04-dual-packages-or-supporting-both-cjs-and-esm/index.md:73-86, packages/fast-check/package.json:23-29

Website and Documentation

The project's official website and documentation, available at fast-check.dev, are built using Docusaurus.

Website Setup

The website is a Docusaurus project located in the /website directory. It can be run locally for development.

• Framework: Docusaurus
• Key Dependencies: @docusaurus/core, react, sandpack-react (for live playgrounds).
• Local Development: Run pnpm start in the root directory, which executes the start script in website/package.json.

Sources: website/blog/2023-05-16-fast-check-loves-docusaurus/index.md:80-83, website/package.json:6, website/package.json:16-23

Documentation Snippet Testing

To ensure the code snippets in the documentation are always correct and up-to-date, the project includes an E2E test that executes them. This test reads markdown files, extracts JavaScript code blocks, runs them, and can optionally update the "Examples of generated values" sections within the documentation.

Sources: packages/fast-check/test/e2e/documentation/Docs.md.spec.ts:13-17, packages/fast-check/test/e2e/documentation/Docs.md.spec.ts:28-36