ava

library0.1.1427870901jsnpmunverified

AVA is a minimalist and fast Node.js test runner, currently at stable version 7.0.0. It distinguishes itself by running tests concurrently in isolated environments (worker threads or child processes), enforcing the writing of atomic tests, and providing a concise API without implicit globals. AVA ships with TypeScript definitions and emphasizes developer experience with "magic assert" for enhanced assertion messages, clean stack traces that remove irrelevant lines, and automatic parallel test runs in CI environments. It generally follows Node.js's release schedule for supported versions, aligning with major Node.js updates, and has a frequent release cadence, as indicated by its version history.

testing

npm install ava

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AVA

ava

testingjavascriptv0.1.1427870901

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

test

✓ import test from 'ava';

✗ const test = require('ava');

AVA's documentation assumes ES modules and `test` is the default export for defining tests. CommonJS `require` is not the recommended approach.

TestFn

✓ import type { TestFn } from 'ava';

For TypeScript users, `TestFn` is a type definition for the test callback function. AVA ships with its own TypeScript types.

ExecutionContext

✓ import type { ExecutionContext } from 'ava';

For TypeScript users, `ExecutionContext` is a type definition for the `t` object passed to test functions, providing type safety for assertions and other test utilities.

This quickstart demonstrates how to define basic synchronous and asynchronous tests with AVA, including an example of serial execution for resources that can't be tested concurrently, which is a common pattern given AVA's concurrent nature.

import test from 'ava'; test('my synchronous test', t => { t.pass('This assertion should pass.'); }); test('my asynchronous test', async t => { const result = await Promise.resolve('foo'); t.is(result, 'foo', 'The promise should resolve to foo.'); }); test.serial('a test requiring serial execution', async t => { // Simulate an operation that should not run concurrently const tempResource = await createResource(); t.truthy(tempResource); await cleanupResource(tempResource); }); async function createResource() { // In a real scenario, this might be a database connection or file handle console.log('Resource created.'); return 'resource-id-123'; } async function cleanupResource(id) { console.log(`Resource ${id} cleaned up.`); }

ava --version

Debug

Known issues

breakingAVA v7.0.0 removed official support for Node.js 18 and 23. You must upgrade to Node.js 20.19 or newer, 22.20 or newer, or 24.12 or newer.

fix

Upgrade your Node.js environment to a supported version. Update your `engines.node` field in `package.json` accordingly.

affects: >=7.0.0

breakingIn v7.0.0, the internal `strip-ansi` dependency was replaced with Node.js's built-in `node:util.stripVTControlCharacters`. If your test setup directly or indirectly relied on the specific `strip-ansi` package, this change might impact your project.

fix

Review dependencies and ensure no direct reliance on `strip-ansi`. Test your application thoroughly after upgrading.

affects: >=7.0.0

gotchaSince AVA v6.1.0, test code is expected to clean up gracefully, allowing the test environment (worker thread or child process) to exit. Failure to do so will result in a 'Test timed out' error.

fix

Use `t.teardown()` for asynchronous cleanup or `registerCompletionHandler()` for global cleanup logic to ensure all operations are complete and resources are freed before the test environment exits.

affects: >=6.1.0

gotchaAVA must be installed locally as a development dependency and cannot be run globally. Attempting to run `ava` without local installation or `npx` will result in a 'command not found' error.

fix

Always install AVA using `npm install --save-dev ava` or `yarn add ava --dev`. Run tests via `npm test` (if configured in `package.json`) or `npx ava`.

affects: All versions

gotchaAVA's documentation assumes you are using ES modules. While CommonJS can be configured, using `type: "module"` in your `package.json` is the recommended and best-supported approach, especially for features like TypeScript integration.

fix

Ensure your `package.json` includes `"type": "module"`. If using CommonJS, explicit configuration might be necessary, and some features may require additional setup or not be fully compatible without transpilation.

affects: All versions

Errors

Common errors & fixes

command not found: ava

AVA is not installed locally or is not in the system's PATH, and `npx` is not being used.

fix

Install AVA locally (`npm install --save-dev ava`) and run tests using `npx ava` or by defining a `"test": "ava"` script in `package.json` and running `npm test`.

ReferenceError: test is not defined

The `test` function, AVA's primary test definition utility, was not imported.

fix

Ensure `import test from 'ava';` is present at the top of your test file.

Test timed out.

An asynchronous operation (e.g., a Promise, Observable, or I/O) did not complete within the configured timeout, or the test environment did not exit cleanly after tests finished.

fix

Ensure all promises are `await`ed, observables are completed, and resources are cleaned up. Use `t.teardown()` or `registerCompletionHandler()` for proper asynchronous cleanup. Adjust the timeout with `--timeout` flag if necessary.

Error [ERR_REQUIRE_ESM]: require() of ES Module [...] not supported. Instead change the require of [...] to a dynamic import()

Attempting to use `require()` to import an ES Module within a CommonJS context, or `ava` itself encountering a mixed module issue. AVA primarily operates with ES Modules.

fix

Configure your project for ES Modules by setting `"type": "module"` in your `package.json`. If you must use CommonJS, ensure proper transpilation or dynamic `import()` calls where necessary, or structure your project to avoid mixing module systems.

Your current Node.js version (vX.Y.Z) is not supported by AVA.

The Node.js version being used is not compatible with the installed AVA version. AVA v7.0.0, for example, dropped support for Node.js 18 and 23.

fix

Update your Node.js environment to a version officially supported by your AVA release. Check AVA's release notes or `package.json` `engines.node` field for supported versions.

Upgrade

Version history

0.1.1427870901latest on npm

Audit

Dependencies

@ava/typescriptoptionalProvides enhanced TypeScript integration, including type definitions for AVA's test context and utilities.

Agent activity

19 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/avajs/ava ↗

packagehttps://www.npmjs.com/package/ava ↗

homepagehttps://avajs.dev ↗