Primitive Arbitraries
Relevant source files
The following files were used as context for generating this wiki page:- packages/fast-check/src/arbitrary/integer.ts
- packages/fast-check/src/arbitrary/string.ts
- packages/fast-check/src/arbitrary/float.ts
- packages/fast-check/src/arbitrary/bigInt.ts
- packages/fast-check/src/arbitrary/boolean.ts
- packages/fast-check/MIGRATION_2.X_TO_3.X.md
- website/blog/2025-03-10-whats-new-in-fast-check-4-0-0/index.md
- website/blog/2024-04-28-whats-new-in-fast-check-3-18-0/index.md
- website/blog/2023-05-30-whats-new-in-fast-check-3-10-0/index.md
Primitive arbitraries are the foundational building blocks in fast-check for generating basic JavaScript data types. They are responsible for creating random values like numbers, strings, and booleans, which serve as the basis for all other, more complex arbitraries. Understanding these primitives is key to effectively using fast-check for property-based testing.
The design philosophy of these arbitraries has evolved to provide smarter defaults that cover more edge cases automatically, allowing testers to focus on their property logic rather than on manually crafting tricky inputs. This includes generating special numeric values, invalid dates, and objects with null prototypes by default in recent versions.
Sources: website/blog/2025-03-10-whats-new-in-fast-check-4-0-0/index.md:16-23, website/blog/2023-09-17-whats-new-in-fast-check-3-13-0/index.md:10-16
Numeric Arbitraries
Numeric arbitraries generate various types of numbers, from standard integers to floating-point values and BigInts.
fc.integer
Generates 32-bit signed integer values. The range can be constrained using a single options object.
Configuration
| Option | Type | Description |
|---|---|---|
min | number | Minimum integer value to be generated (inclusive). |
max | number | Maximum integer value to be generated (inclusive). |
Sources: packages/fast-check/src/arbitrary/integer.ts:13-16, packages/fast-check/MIGRATION_2.X_TO_3.X.md:31-32
Historically, the signature for this arbitrary was integer(min, max). It was updated to integer({min, max}) to unify signatures across the library and improve extensibility.
Sources: packages/fast-check/MIGRATION_2.X_TO_3.X.md:31-32
fc.bigInt
Generates bigint values within a specified range. Similar to fc.integer, it uses min and max constraints. Version 4.0.0 deprecated older, more specific big{U|}int{N|} arbitraries in favor of this unified version.
Configuration
| Option | Type | Description |
|---|---|---|
min | bigint | Minimum bigint value to be generated (inclusive). |
max | bigint | Maximum bigint value to be generated (inclusive). |
Sources: packages/fast-check/src/arbitrary/bigInt.ts:13-16, website/blog/2025-03-10-whats-new-in-fast-check-4-0-0/index.md:58
fc.float and fc.double
These arbitraries generate 32-bit (float) and 64-bit (double) floating-point numbers. Since version 3.x, their default behavior is to generate from the entire possible range of floating-point values, including special values.
The following diagram illustrates the logic for handling special values in fc.double.
This diagram shows how constraints like noNaN, noDefaultInfinity, and noInteger refine the set of generated floating-point numbers.
Sources: packages/fast-check/MIGRATION_2.X_TO_3.X.md:92-104, website/blog/2024-04-28-whats-new-in-fast-check-3-18-0/index.md:14-22
Key Features & Configuration
- Special Values: By default, these arbitraries can generate
NaN,+Infinity,-Infinity, and-0to catch edge cases. noIntegerOption: An optionnoInteger: truecan be passed to exclude whole numbers from the generated values.- Signature Unification: Like
fc.integer, the signatures were updated fromdouble(min, max)todouble({min, max})for consistency.
Configuration
| Option | Type | Description |
|---|---|---|
min | number | Minimum float value (inclusive). |
max | number | Maximum float value (inclusive). |
noDefaultInfinity | boolean | If true, excludes +Infinity and -Infinity from generation when no min/max is specified. |
noNaN | boolean | If true, NaN will not be generated. |
noInteger | boolean | If true, generated values will not be integers (e.g., 1.0). Added in version 3.18.0. |
Sources: packages/fast-check/src/arbitrary/float.ts:24-30, packages/fast-check/MIGRATION_2.X_TO_3.X.md:92-104, website/blog/2024-04-28-whats-new-in-fast-check-3-18-0/index.md:14-22
String Arbitraries
fc.string
The fc.string arbitrary is the primary tool for generating strings. It is highly configurable and, as of version 4.0.0, has consolidated the functionality of many previously separate string arbitraries.
Configuration
| Option | Type | Description |
|---|---|---|
minLength | number | Minimum length of the generated string (inclusive). |
maxLength | number | Maximum length of the generated string (inclusive). |
Sources: packages/fast-check/src/arbitrary/string.ts:13-16
Evolution of String Arbitraries
The approach to string generation has been significantly streamlined.
- Signature Unification: In version 2.x, signatures for all string-related arbitraries were unified to use a single constraints object, e.g.,
string(minLength, maxLength)becamestring({minLength, maxLength}). - Consolidation in v4.0.0: Version 4.0.0 deprecated and removed many specialized string arbitraries, unifying their functionality into
fc.stringand other core builders. This includes:ascii,asciiStringbase64,base64StringfullUnicode,fullUnicodeStringhexa,hexaStringstring16bitsstringOfunicode,unicodeString
This change simplifies the API, providing a single, powerful arbitrary for most string generation needs. For more complex patterns, fc.stringMatching(/regex/) can be used.
The following diagram shows the consolidation of string arbitraries into a more unified API.
Boolean Arbitrary
fc.boolean
The fc.boolean arbitrary is the simplest primitive. It generates either true or false with equal probability. It does not take any configuration parameters.
Sources: packages/fast-check/src/arbitrary/boolean.ts:11-13
Conclusion
The primitive arbitraries in fast-check form the bedrock of property-based testing with the library. Their evolution reflects a move towards greater power, simplicity, and robustness. By unifying signatures, consolidating redundant arbitraries (especially for strings), and incorporating "smarter" defaults that include edge-case values, fast-check enables developers to uncover more bugs with less boilerplate code. Mastering these primitives is the first step toward leveraging the full potential of fast-check.
Sources: website/blog/2025-03-10-whats-new-in-fast-check-4-0-0/index.md:16-30, packages/fast-check/MIGRATION_2.X_TO_3.X.md:8-14