avajs/ava
github.com/avajs/ava ↗ · 935 files · 965 KB
Please support our friend Vadim Demedes and the people in Ukraine.
Overview
AVA 8.0.1 is an ESM Node.js test runner for developers who want explicit test declarations, concurrent execution, detailed assertion diagnostics, and snapshot testing. It coordinates isolated workers per test file, runs hooks and tests inside each worker, and reports structured results through terminal or TAP output. Its distinctive extension surfaces include reusable macros, a negotiated TypeScript provider, shared-worker plugins, and dependency-aware watch mode.
System map
AVA separates CLI orchestration from per-file test execution. The parent process discovers files, prepares providers, schedules workers, and aggregates events; workers own declarations, assertions, hooks, and snapshot state. Persistent artifacts are filesystem snapshots and local scheduling caches. Distribution is an npm package with a manually dispatched release workflow.
- package.json exposes the ava executable through entrypoints/cli.js, declares ESM, and supports Node ^22.20, ^24.12, or >=26.
- The public test entrypoint exports lib/worker/main.js, which checks runnerChain, marks loadedMain, and returns the worker's declaration chain.
- loadCli() loads configuration, normalizes providers and selection options, constructs Api, and chooses a reporter before entering one-shot or watch execution.
- Api.run() discovers tests, applies selection and CI partitioning, compiles providers, and schedules selected files with pMap.
- loadFork() creates either a Worker with workerData or a childProcess.fork with advanced serialization; both forward stdout, stderr, and AVA state messages.
- Runner owns per-file task queues and active runnables; Test owns each runnable's assertions, completion, and teardown.
- Snapshot Manager persists binary snapshots and Markdown reports; scheduler separately stores failing-tests.json in the AVA cache outside CI.
- npm test invokes lint, TypeScript checking, both test suites, and c8 reporting; release.yml validates a supplied ref, publishes npm provenance, and creates a draft GitHub release.
Feature catalog
AVA's user surface combines CLI selection and execution controls with an explicit test API. Tests support modifiers, hooks, macros, asynchronous completion, execution context, and assertions. Snapshot updates, watch interactions, debugging, TAP output, and TypeScript integration extend the development workflow. Shared-worker plugins provide coordination across otherwise isolated test files.
- The default CLI command accepts patterns, directories, and paths with line-number suffixes; --match filters titles, while --serial, --concurrency, --fail-fast, and --no-worker-threads control execution.
- ava debug selects one file and exposes inspector host, port, and break options; ava reset-cache removes entries beneath the project's AVA cache and exits.
- createChain() implements serial, only, skip, failing, todo, skipIf(), and runIf(), plus before/beforeEach/after/afterEach hooks and after-hook always modifiers.
- test.macro() freezes exec/title definitions; parseTestArgs() accepts macro arguments, generates titles, and normalizes title whitespace.
- ExecutionContext supplies log(), plan(), timeout()/timeout.clear(), teardown(), context access, and t.try() results with explicit commit/discard operations.
- Assertions include identity and deep comparisons, sync/async exception expectations, snapshots, truth tests, and regex checks; snapshot assertions are prohibited in hooks.
- Watch mode supports reruns, snapshot updates, glob and title prompts, and dependency-based file selection; CLI watch mode is rejected in CI and during debugging.
- AVA offers terminal/TAP reporting, an optional @ava/typescript provider, and ava/plugin shared workers with publish/subscribe messaging; shared workers require worker threads.
Data flow
Configuration and CLI input become normalized project-relative selectors and transferable worker options. The parent owns file scheduling and run statistics, while each worker owns test execution and assertion state. Structured state events return through thread messaging or child-process IPC to reporters and exit-code logic. Snapshot and scheduling writes feed touched-file events back into watch mode.
- loadConfig() derives projectDir from package configuration, searches config modules up to the repository boundary, and rejects implicit package/file conflicts; an explicit config discards package configuration.
- CLI flags overwrite corresponding configured values; file arguments are resolved from cwd, made relative to projectDir, and split into patterns and line selections.
- findTests() expands globs into absolute paths, filters extensions, and excludes underscore-prefixed files; CLI filtering can additionally select existing files outside discovered matches.
- Provider main.compile() receives all discovered tests; non-null provider state is sent to workers, while provider objects and sortTestFiles functions are removed from transferable options.
- Worker setup installs provider loaders, loads configured modules sequentially, awaits their default functions with arguments, then imports the test file.
- Declaration arguments become metadata-bearing task records; each test gets ContextRef.copy(), whose first access shallow-copies an object value.
- Worker Runner events cross the channel into loadFork(), which attaches testFile; RunStatus updates per-file/global counters and emits copied statistics to reporter subscribers.
- Snapshot assertions map values to title/index entries and Concordance descriptors; saving emits changed/temporary paths, which watch mode records to suppress self-generated reruns.
Behavior traces
Source inspection followed startup, test execution, and snapshot persistence end-to-end, with additional traces for reporting, failures, scheduling, and watch reruns. These are execution-order descriptions from code rather than observed runs. Material conditions include selection, hook failures, CI snapshot policy, and worker shutdown handshakes.
- Startup: entrypoints/cli.js calls loadCli() → loadConfig() → option normalization → new Api() → reporter construction → api.run({filter}); one-shot completion sets process.exitCode and calls reporter.endRun().
- File launch: Api.run() → globs.findTests()/applyTestFileFilter() → scheduler.failingTestsFirst() → provider compile() → pMap() → fork(); serial mode uses one file worker and automatic CI concurrency uses two.
- Worker bootstrap: run(options) constructs Runner and publishes runnerChain → installs providers → loads setup modules → loads testPath; importing ava marks loadedMain, otherwise the worker reports missing-ava-import and exits.
- Primary test action: chain registration schedules Runner.start() on nextTick → readiness wait → before hooks → serial tests → concurrent tests; runTest() executes beforeEach, Test.run(), success-only afterEach, and afterEach.always.
- Runnable completion: Test.run() calls the implementation and awaits a returned promise or observable → finish() clears timeout, verifies plan/assertions, awaits reverse-order teardowns, and inverts the result for failing tests.
- Snapshot persistence: t.snapshot() → Test.compareWithSnapshot() → Runner.compareTestSnapshot() → Manager.compare()/record(); Runner finish triggers saveSnapshotState(), which encodes and atomically writes .snap/.md files before worker-finished.
- Run closure: workers send worker-finished → parent sends free-worker → worker checks unhandled rejections and schedules completion handlers; parent waits for worker/shared-worker cleanup, stores failed-file state, and ends RunStatus.
- Watch rerun: recursive fs.watch() marks dirty paths → debounce waits for tracing and filters touched files → traceToTestFile() selects dependents or unknown changes trigger all tests → plan() yields options → start() calls Api.run() and ends reporting.
Testing signals
Tests and CI were inspected, not executed; no passing results or measured coverage are asserted. AVA uses @ava/test for runtime integration tests, TAP for internal suites, and TypeScript compilation for declaration cases. Inspected coverage includes configuration, worker selection, snapshots, scheduling, watch interactions, and shared-worker lifecycle. The inventory is bounded, and CI contains explicit platform and concurrency accommodations.
- The inspected npm test script runs XO, tsc --noEmit, @ava/test's test-ava command, TAP, and c8 reporting; these commands were read but not executed.
- ava.config.js selects test files while excluding fixtures/helpers; .taprc separately includes TAP unit, reporter, and integration files with a 300-second timeout.
- Integration helpers launch the real CLI through execaNode, set TEST_AVA and TEST_AVA_IMPORT_FROM, capture output, and consume IPC results; worker tests cover default threads and both child-process selection mechanisms.
- Configuration tests exercise package settings, explicit overrides, conflicts, factory returns, defaults, and wrapped errors; TAP Runner cases exercise synchronous declarations and emitted events.
- Snapshot selection tests specify preservation of skipped snapshots/tests and targeted updates by title or lines; scheduler tests specify failure-first ordering and disabled-cache behavior.
- Watch tests exercise instructions, SIGINT, reruns, and snapshot updates, with a Windows output-capture fallback; shared-worker lifecycle tests check availability and teardown output.
- CI defines Node 22/24/26 jobs across Linux, Windows, and macOS, TypeScript 5.9/6.0 checks, lint and lockfile jobs; scripts/ci.sh runs watch tests serially and excludes two reporter suites outside Linux.
- Coverage configuration excludes entrypoints, examples, declarations, and tests; type cases are compile inputs, and shared-worker source explicitly identifies delayed messages after deregistration as difficult to test.
Risk map
The main security-sensitive boundaries are executable configuration, arbitrary test/setup imports, inherited worker environments, inspector access, IPC, and filesystem writes. These are source observations about a developer tool that executes project code, not confirmed vulnerabilities. Additional correctness concerns involve snapshot durability, dependency tracing limits, and an error-handling branch identified by inspection. No runtime reproduction or exhaustive security audit was performed.
- Configuration discovery imports ava.config.js/.mjs and invokes exported factories before test workers exist; automatic upward search means parent-directory configuration can execute in the CLI process.
- Both worker modes inherit process.env and apply configured overrides; worker isolation does not filter inherited environment values, and childProcess.fork launches Node with supplied execArgv.
- Setup modules and test paths execute via dynamic import or provider loaders; dependency setup resolution can write import-from-project.mjs under project node_modules even independently of provider cache selection.
- Debug mode accepts a configurable inspector host and port and calls inspector.open(..., true); the CLI default host is 127.0.0.1 and debugging is rejected in CI.
- Snapshot destinations incorporate source-map source paths or configured locations, while glob discovery follows symlinks; snapshot writes/deletions and temporary cache creation are filesystem boundaries that can extend beyond the checkout.
- Hypothesis: separate concurrent atomic writes for .snap and .md protect each file individually but can leave the pair inconsistent if one write fails; updating also deliberately discards snapshot decoding errors. (inferred)
- Hypothesis: a rejection from globs.findTests() leaves testFiles undefined, after which selectionInsights reads testFiles.length before the later reporting try/catch; this may bypass intended internal-error reporting. (inferred)
- Watch tracing intentionally ignores installed dependencies and non-exact file references, and config modules are not reloaded; observeRun's iterator additionally stops after the first run, with multi-run support marked TODO.
Extension points
AVA exposes several deliberate extension seams rather than one general plugin registry. User macros and setup modules customize test behavior, while providers customize loading and compilation. Shared-worker factories supply cross-file services through a versioned messaging protocol. CLI flags, declaration chains, reporters, and public types form coordinated internal extension surfaces.
- CLI options are centralized in FLAGS and yargs command definitions; adding an execution option also requires mapping it into combined configuration and Api constructor options.
- createChain() uses a WeakMap registry and metadata flags to compose declaration APIs; macros are frozen exec/title records interpreted by parseTestArgs().
- Configuration may export an async factory receiving projectDir; require entries can name setup modules or argument tuples whose default functions are awaited before tests.
- provider-manager imports a provider factory and negotiates ava-8; the negotiated interface supplies AVA version, projectDir, findFiles(), and glob normalization, with @ava/typescript as the registered provider.
- Provider main hooks contribute extensions, update globs, and compile state; worker hooks expose canLoad()/load(), while watcher hooks interpret compilation changes.
- ava/plugin.registerSharedWorker() deduplicates registrations by filename and requires ava-4; its factory interface exposes readiness, broadcasts, subscriptions, connected test workers, and per-worker teardown.
- Reporter classes consume plan.status stateChange events through startRun()/endRun(); experimental observeRun exposes an async event iterator only when observeRunsFromConfig is enabled.
- registerCompletionHandler() adds ordered callbacks scheduled on nextTick without awaiting results; exported declaration files provide the corresponding typed public API surface.
Contributor handoff
Start with the manifest, local test/configuration files, and the source modules governing the behavior being changed. Preserve worker protocol, test ordering, snapshot compatibility, and public declaration semantics across edits. Tests and CI were inspected, not executed, so this brief provides no passing baseline. Under this task's read-only authority, commands below are future validation guidance rather than authorization to run them.
- Read package.json, ava.config.js, .taprc, and scripts/test.sh first to distinguish published runtime entrypoints from the @ava/test and TAP development harnesses.
- For CLI/configuration changes, follow loadCli(), loadConfig(), and existing loader tests; explicit configuration has different conflict semantics from automatically discovered configuration.
- For worker lifecycle changes, read fork.js, worker/base.js, and worker/channel.js together; preserve ready-for-options, worker-finished/free-worker, peer-failed, and channel reference semantics.
- Keep file concurrency distinct from within-file concurrency, and preserve success-only after hooks versus always hooks; fail-fast does not cancel concurrent tests already started within a file.
- Snapshot edits must preserve title/index identity, skipped-block retention, deterministic encoding, and format versioning; the source explicitly requires a major AVA version bump for incompatible encoding changes.
- Update runtime declaration chains and public types together; TypeScript cases are checked by tsc, and examples pin AVA ^6 despite the root package being 8.0.1.
- When execution is separately authorized, use the documented smallest test selection first: npx test-ava test/{file}.js or npx tap test-tap/{file}.js; npm test adds lint, types, and coverage.
- Tests and CI were inspected, not executed; future validation must account for serial watch testing, non-Linux reporter exclusions, and compile-only type cases rather than assuming uniform suite execution.
Languages
| Language | Files | Share of source |
|---|---|---|
| JavaScript | 489 | 93% |
| JSON | 165 | docs/config |
| Markdown | 109 | docs/config |
| TypeScript | 37 | 7% |
| YAML | 3 | docs/config |
| Shell | 2 | 0% |
Start reading here
Probable source entrypoint: lib/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
lib/ (51 files)
Repository structure
| Top-level path | Files |
|---|---|
test/ | 460 |
test-tap/ | 301 |
lib/ | 51 |
examples/ | 33 |
docs/ | 28 |
test-types/ | 14 |
media/ | 11 |
.github/ | 7 |
Docs found: docs/01-writing-tests.mddocs/02-execution-context.mddocs/03-assertions.mddocs/04-snapshot-testing.mddocs/05-command-line.mddocs/06-configuration.mddocs/07-test-timeouts.mddocs/08-common-pitfalls.mddocs/recipes/babel.mddocs/recipes/browser-testing.md
Package
package.json — ava v8.0.1, 55 declared dependencies.
@ava/test@ava/typescript@sindresorhus/tsconfig@types/node@vercel/nftacornacorn-walkansi-escapesansi-stylesarrgvarrifyc8
CI & config entrypoints
.github/workflows/release.yml— GitHub Actions workflow.github/workflows/ci.yml— GitHub Actions workflowpackage.json— npm scripts: testexamples/endpoint-testing/package.json— npm scripts: testexamples/macros/package.json— npm scripts: testexamples/matching-titles/package.json— npm scripts: testexamples/specific-line-numbers/package.json— npm scripts: testexamples/tap-reporter/package.json— npm scripts: testexamples/timeouts/package.json— npm scripts: testexamples/typescript-basic/package.json— npm scripts: test
Structural health signals
Average score 8.6/10 across 96 analyzed source files; 1 hotspot surfaced.
test-tap/assert.js— 1844 lines, score 6.2 (Large file, Long function/block)lib/watcher.js— 839 lines, score 6.7 (Large file, Long function/block)lib/assert.js— 812 lines, score 6.7 (Large file, Long function/block)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
bbfd946322fd2026-05-17 — v8.0.1332fcd7cf9db2026-05-17 — Pre-release updates (#3451)fcaaf432e3c12026-05-16 — Add Node.js 26 support; drop 25 (#3450)a913804496712026-05-14 — Test using AVA 8 (#3440)fe3128673adf2026-04-27 — v8.0.0