Ava Integration
Relevant source files
The following files were used as context for generating this wiki page:The @fast-check/ava package provides a seamless integration layer for using the fast-check property-based testing framework with the AVA test runner. It simplifies the process by exposing a testProp function that wraps fast-check's assertion logic within AVA's test structure, allowing developers to leverage the full power of property-based testing without leaving the AVA ecosystem.
This integration supports AVA's core features, including its execution context, assertions, test modifiers, and hooks. It is designed to work with both synchronous and asynchronous properties, including those involving Promises and Observables.
Sources: packages/ava/README.md:3-6, packages/ava/README.md:21-23
Core Functionality
The primary entry point for this integration is the testProp function. It creates an AVA test that is powered by fast-check's property-based testing engine.
Sources: packages/ava/README.md:16-18
testProp Function
The testProp function mirrors the structure of AVA's test function but is adapted for properties. It accepts a test title, an array of fast-check arbitraries, and a property function to execute. The property function receives AVA's execution context t as its first argument, followed by the values generated by the arbitraries.
A typical testProp call looks like this:
import { testProp, fc } from '@fast-check/ava';
// for all a, b, c strings
// b is a substring of a + b + c
testProp('should detect the substring', [fc.string(), fc.string(), fc.string()], (t, a, b, c) => {
t.true((a + b + c).includes(b));
});
Sources: packages/ava/README.md:16-23
Execution Flow
The diagram below illustrates the execution flow when a test is defined using testProp. The function internally calls AVA's test and then uses fc.assert to run the property, handling test success or failure based on the outcomes of the property executions.
This diagram shows how testProp orchestrates AVA and fast-check to execute a property-based test.
Sources: packages/ava/README.md:16-31
A critical aspect of the integration is that the return value of the property function (true or false) is ignored. Instead, the test's success is determined solely by whether any AVA assertions fail. If no assertions are made, the test will fail, ensuring that properties are meaningful.
Sources: packages/ava/README.md:28-31, packages/ava/test/main.spec.ts:18-23
Advanced Features
@fast-check/ava supports many of AVA's advanced features, providing a consistent testing experience.
Sources: packages/ava/README.md:44-45
AVA Modifiers
All standard AVA test modifiers are available on testProp, allowing for fine-grained control over test execution.
| Modifier | Description |
|---|---|
.only | Runs only this specific test. |
.serial | Ensures the test runs serially. |
.skip | Skips the test. |
.failing | Marks a test that is expected to fail. |
import { testProp, fc } from '@fast-check/ava';
testProp.skip('should be skipped', [fc.string()], (t, text) => {
t.is([...text].length, text.length);
});
Sources: packages/ava/README.md:47-58, packages/ava/CHANGELOG_1.X.md:112-113
fast-check Parameters
Custom fast-check parameters, such as seed or numRuns, can be passed as an optional last argument to testProp. This allows for replaying failed runs or adjusting the number of iterations.
import { testProp, fc } from '@fast-check/ava';
testProp(
'should replay the test for the seed 4242',
[fc.nat(), fc.nat()],
(t, a, b) => {
t.is(a + b, b + a);
},
{ seed: 4242 }, // fast-check parameters
);
Sources: packages/ava/README.md:35-45, packages/ava/test/main.spec.ts:28
Hooks and Custom Context
The integration exposes AVA's before and after hooks, and also mirrors AVA's procedure for customizing the test execution context.
| Feature | Description |
|---|---|
| Hooks | testProp.before and testProp.after can be used to set up and tear down state for property tests. |
| Execution Context | A custom context type can be defined and will be available on t.context inside the property function. |
The following diagram shows the relationship between hooks, context, and the test property.
Sources: packages/ava/README.md:60-80
Packaging and Compatibility
The @fast-check/ava package is distributed as a dual module, supporting both CommonJS (require) and ES Modules (import). This is achieved through conditional exports in package.json.
Sources: packages/ava/package.json:5-18, website/blog/2023-09-04-dual-packages-or-supporting-both-cjs-and-esm/index.md
Module Resolution
The exports field in package.json directs Node.js and bundlers to the correct file based on the import mechanism.
This diagram illustrates the module resolution for CJS and ESM consumers.
Sources: packages/ava/package.json:6-17, packages/ava/CHANGELOG.md:25-26
Compatibility Matrix
The package maintains compatibility with specific versions of ava, fast-check, and Node.js.
| @fast-check/ava | AVA | fast-check | node |
|---|---|---|---|
| 2.x | ^4 || ^5 || ^6 | ^3 || ^4 | ≥12.22.0 |
| 1.x | ^4 || ^5 || ^6 | ^3 | ≥12.22.0 |
Sources: packages/ava/README.md:84-89, packages/ava/package.json:44-47, packages/ava/CHANGELOG.md:7
Versioning and History
The package has evolved over time, with significant updates tracked in its changelog.
- v2.0.0: Introduced a major breaking change by making the ES Module version the default. This aligns with the broader JavaScript ecosystem's move towards ESM.
Sources: packages/ava/CHANGELOG.md:23-26 - v2.0.2: Added support for
fast-checkv4, ensuring compatibility with the latest major version of the core library.
Sources: packages/ava/CHANGELOG.md:7 - v1.2.0: Improved support for pre-condition failures using
fc.pre, allowing tests with unmet preconditions to be handled gracefully without failing the test run.
Sources: packages/ava/CHANGELOG_1.X.md:14-15 - v1.1.0: Aligned the seed computation with
fast-check's core logic for more consistent and predictable test replays.
Sources: packages/ava/CHANGELOG_1.X.md:77-78
Conclusion
@fast-check/ava is a powerful and well-maintained bridge that brings property-based testing to the AVA ecosystem. By wrapping fast-check's capabilities in an API that is idiomatic to AVA users, it provides a low-friction path to adopting this advanced testing methodology. Its support for AVA's core features, modern JavaScript modules, and clear compatibility requirements make it a robust choice for enhancing test suites.
Sources: packages/ava/README.md:3-6