Specialized Arbitraries
Relevant source files
The following files were used as context for generating this wiki page:- packages/fast-check/src/arbitrary/date.ts
- packages/fast-check/src/arbitrary/uuid.ts
- packages/fast-check/src/arbitrary/webUrl.ts
- packages/fast-check/src/arbitrary/func.ts
- packages/fast-check/src/arbitrary/json.ts
- website/blog/2025-03-10-whats-new-in-fast-check-4-0-0/index.md
- packages/fast-check/MIGRATION_2.X_TO_3.X.md
- website/blog/2024-04-28-whats-new-in-fast-check-3-18-0/index.md
fast-check provides a set of specialized arbitraries designed to generate complex, common data types out-of-the-box. These arbitraries encapsulate the logic for creating values like dates, UUIDs, web URLs, functions, and JSON structures, which would otherwise require significant effort to build from basic building blocks. By offering these high-level generators, fast-check simplifies the process of writing property-based tests for applications that handle these data formats.
This page details the architecture and usage of several key specialized arbitraries, including fc.date, fc.uuid, fc.webUrl, fc.func, and the family of fc.json arbitraries. It covers their configuration options, internal composition, and evolution across different versions of the library.
Sources: packages/fast-check/src/arbitrary/date.ts, packages/fast-check/src/arbitrary/uuid.ts, packages/fast-check/src/arbitrary/webUrl.ts, packages/fast-check/src/arbitrary/func.ts, packages/fast-check/src/arbitrary/json.ts
Date Arbitrary (fc.date)
The fc.date arbitrary is responsible for generating JavaScript Date objects. It internally uses an integer arbitrary to generate a timestamp within a specified range, which is then converted into a Date instance.
A key philosophy of fast-check is to provide "smarter defaults" to uncover more edge cases. In line with this, starting from version 4.0.0, fc.date includes invalid dates in its generated values by default. This helps test how systems handle unexpected or malformed date inputs.
Sources: packages/fast-check/src/arbitrary/date.ts, website/blog/2025-03-10-whats-new-in-fast-check-4-0-0/index.md
Configuration
The behavior of fc.date can be customized through a constraints object.
| Parameter | Type | Description |
|---|---|---|
min | Date | The minimum date to be generated (inclusive). |
max | Date | The maximum date to be generated (inclusive). |
invalidDate | boolean | If true, allows the generation of invalid Date objects. Defaults to true in v4.0.0+. |
Sources: packages/fast-check/src/arbitrary/date.ts:18-25, website/blog/2025-03-10-whats-new-in-fast-check-4-0-0/index.md
Generation Flow
The following diagram illustrates the generation logic for the fc.date arbitrary.
This diagram shows how fc.date uses constraints to define a range for an underlying integer arbitrary, optionally includes invalid date values, and maps the final integer to a Date object.
Sources: packages/fast-check/src/arbitrary/date.ts:28-56
UUID Arbitrary (fc.uuid)
The fc.uuid arbitrary generates universally unique identifiers (UUIDs) as strings. It constructs UUIDs conforming to the standard 8-4-4-4-12 hexadecimal format.
In version 4.0.0, the API was streamlined by deprecating the version-specific uuidV arbitrary and consolidating its functionality into a single, more flexible fc.uuid arbitrary capable of generating various UUID versions.
Sources: packages/fast-check/src/arbitrary/uuid.ts, website/blog/2025-03-10-whats-new-in-fast-check-4-0-0/index.md
Internal Composition
fc.uuid is a composite arbitrary. It combines simpler arbitraries like hexaString (to generate hexadecimal characters) and constant (for fixed parts of the UUID like hyphens and version/variant markers) to build the final string.
The diagram below shows how fc.uuid is composed of smaller building blocks to generate a v4 UUID.
Web URL Arbitrary (fc.webUrl)
The fc.webUrl arbitrary generates valid web URLs. It is a high-level composite arbitrary that assembles a URL from its constituent parts: scheme, authority (domain, port), path, query parameters, and fragment.
To produce realistic and challenging inputs, the underlying fc.webPath arbitrary was improved in version 3.18.0 to generate paths that can start with //, a valid but often overlooked edge case according to RFC-3986.
Sources: packages/fast-check/src/arbitrary/webUrl.ts, website/blog/2024-04-28-whats-new-in-fast-check-3-18-0/index.md
URL Construction Flow
fc.webUrl builds a URL by combining the outputs of several other specialized arbitraries.
This diagram shows the modular construction of a URL from its core components.
Sources: packages/fast-check/src/arbitrary/webUrl.ts:40-52
Configuration
| Parameter | Type | Description |
|---|---|---|
validSchemes | string[] | An array of allowed URL schemes (e.g., 'http', 'https'). |
authority | Arbitrary<string> | A custom arbitrary for the authority part of the URL. |
path | Arbitrary<string> | A custom arbitrary for the path. |
query | Arbitrary<string> | A custom arbitrary for the query string. |
fragment | Arbitrary<string> | A custom arbitrary for the fragment. |
Sources: packages/fast-check/src/arbitrary/webUrl.ts:20-38
Function Arbitrary (fc.func)
The fc.func arbitrary is designed for testing code that accepts functions as arguments, such as callbacks or higher-order functions. It takes an arbitrary for the return value and produces a function that, when called, will provide a value generated by the input arbitrary.
The generated function is also instrumented to behave like a mock, allowing tests to inspect how it was called. It includes properties like calledWith (an array of argument lists for each call) and callCount.
Sources: packages/fast-check/src/arbitrary/func.ts:18-21, 56-61
Interaction Diagram
This sequence diagram shows how a test might use a function generated by fc.func.
JSON Arbitraries (fc.json*)
fast-check provides a family of arbitraries for generating JSON data, either as structured values or as serialized strings. These are recursive arbitraries capable of producing complex, nested data structures.
fc.jsonValue/fc.unicodeJsonValue: Generate any valid JSON value (string,number,boolean,null, an array of JSON values, or an object with string keys and JSON values). Theunicodeversion allows strings to contain unicode characters.fc.json/fc.unicodeJson: Generate a serialized JSON string.
In version 3.0, the older jsonObject and unicodeJsonObject arbitraries were deprecated in favor of the more accurately named jsonValue and unicodeJsonValue.
Sources: packages/fast-check/src/arbitrary/json.ts, packages/fast-check/MIGRATION_2.X_TO_3.X.md
Recursive Structure
The jsonValue arbitrary is defined recursively. It can generate primitive JSON types or recursively call itself to build arrays and objects.
The following diagram illustrates this recursive relationship.
This graph shows that a jsonValue can be one of the primitive types or a collection (array/dictionary) that contains other jsonValue instances.
Sources: packages/fast-check/src/arbitrary/json.ts:113-131
Configuration
JSON arbitraries can be configured to control the complexity of the generated structures.
| Arbitrary | Parameter | Type | Description |
|---|---|---|---|
fc.jsonValue | maxDepth | number | The maximum nesting depth for objects and arrays. |
fc.json | maxDepth | number | The maximum nesting depth for the underlying JSON value. |
Sources: packages/fast-check/src/arbitrary/json.ts:25-30, 106-111
Conclusion
The specialized arbitraries in fast-check are powerful tools that abstract away the complexity of data generation for common types. They enable developers to write concise and effective property-based tests without needing to manually construct complex generators from scratch. The library's commitment to "smarter defaults" ensures that these arbitraries evolve to find more edge cases automatically, enhancing the bug-finding capabilities of the framework.