Required dependencies

npm install concordance is-promise emittery matcher callsites \
  @vercel/nft acorn acorn-walk ansi-styles chalk debug \
  globby ignore-by-default code-excerpt common-path-prefix \
  cbor ci-info ci-parallel-vars cli-truncate figures \
  indent-string is-plain-object plur chunkd arrgv arrify \
  currently-unhandled

No native add-ons, no pod install, no prebuild step. Requires Node.js 18 or later (AVA 8 drops older Node). All source files use ES module syntax (import/export); your project must have "type": "module" in package.json or use .mjs extensions.

Project setup

1. Copy the source/ directory into your project, e.g. src/ava-core/.
2. Ensure "type": "module" is set in your package.json.
3. If using TypeScript, add to tsconfig.json:

   {
     "compilerOptions": {
       "module": "NodeNext",
       "moduleResolution": "NodeNext",
       "allowImportingTsExtensions": false
     }
   }
   

4. No Babel configuration is needed unless you are activating a language provider via provider-manager.js.
5. Set environment variables before spawning workers:
   • NODE_ENV — controls certain runtime paths
   • AVA_PATH — override when embedding AVA in a monorepo tool
   • TEST_AVA=1 — enables interim V8 coverage reports inside the watcher (self-test mode only)
6. The worker entry point is source/worker/main.js. When forking worker threads, set refs.runnerChain on the shared state before that module loads (see worker/state.js).

Public API

AssertionError

import { AssertionError } from './source/assert.js';

class AssertionError extends Error {
  assertion: string | undefined;
  assertionStack: string;
  improperUsage: object | null;
  formattedDetails: Array<{ label: string; formatted: string }>;
  constructor(
    message?: string,
    options?: {
      assertion?: string;
      assertionStack?: string;
      formattedDetails?: Array<{ label: string; formatted: string }>;
      improperUsage?: object | null;
      cause?: unknown;
    }
  );
}

Thrown by every built-in assertion on failure. Inspect formattedDetails to render diffs, assertion for the method name, and assertionStack for the cleaned stack. Use when building custom reporters or assertion wrappers that need to distinguish AVA assertion failures from other errors.

Runner

import Runner from './source/runner.js';

class Runner extends Emittery {
  constructor(options?: {
    experiments?: Record<string, unknown>;
    failFast?: boolean;
    failWithoutAssertions?: boolean;
    file?: string;
    checkSelectedByLineNumbers?: boolean;
    match?: string[];
    projectDir?: string;
    recordNewSnapshots?: boolean;
    serial?: boolean;
    snapshotDir?: string;
    updateSnapshots?: boolean;
  });
  tasks: {
    after: unknown[]; afterAlways: unknown[]; afterEach: unknown[];
    afterEachAlways: unknown[]; before: unknown[]; beforeEach: unknown[];
    concurrent: unknown[]; serial: unknown[]; todo: unknown[];
  };
}

The core per-file test orchestrator. Instantiate one Runner per worker, pass it to create-chain.js to build the test function surface, then call its run methods. It emits lifecycle events (test-passed, test-failed, hook-failed, etc.) consumed by reporters.

available (watcher)

import { available } from './source/watcher.js';

function available(projectDir: string): boolean;

Probes whether the current OS supports recursive fs.watch. Call before enabling watch mode to provide a graceful degradation message instead of a runtime crash. Returns false on Linux kernels without inotify recursive support and on certain container environments.

Working examples

Scenario - Run assertions in isolation

Construct an ExecutionContext-style harness using only assert.js to validate assertion output without spinning up a full worker.

import { AssertionError, checkAssertionMessage } from './source/assert.js';

function runAssertion(value: unknown, expected: unknown) {
  if (value !== expected) {
    throw new AssertionError('Values are not strictly equal', {
      assertion: 'is',
      formattedDetails: [
        { label: 'Actual:', formatted: String(value) },
        { label: 'Expected:', formatted: String(expected) },
      ],
    });
  }
  return true;
}

try {
  runAssertion(1, 2);
} catch (err) {
  if (err instanceof AssertionError) {
    console.error(`Assertion "${err.assertion}" failed: ${err.message}`);
    for (const detail of err.formattedDetails) {
      console.error(`  ${detail.label} ${detail.formatted}`);
    }
  }
}

Scenario - Check watcher availability before enabling watch mode

import { available } from './source/watcher.js';
import path from 'node:path';

const projectDir = path.resolve('.');

if (!available(projectDir)) {
  console.warn(
    'Recursive file watching is not supported on this platform. ' +
    'Watch mode is disabled.'
  );
  process.exit(0);
}

console.log('Watch mode is available. Starting watcher...');
// proceed to instantiate and configure the watcher

Scenario - Instantiate a Runner and register tasks programmatically

import Runner from './source/runner.js';

const runner = new Runner({
  file: new URL('./fixtures/example.js', import.meta.url).toString(),
  projectDir: process.cwd(),
  failFast: false,
  serial: false,
  failWithoutAssertions: true,
});

runner.on('test-passed', event => {
  console.log('PASS', event.title);
});

runner.on('test-failed', event => {
  console.error('FAIL', event.title, event.err?.message);
});

// Runner.tasks is populated by the chain created via create-chain.js
// when the test file is imported inside a worker.
console.log('Runner created. Tasks will populate after test file import.');

File walkthrough

• plugin-support/shared-worker-loader.js — Bootstraps the shared worker thread and routes messages to registered plugins.
• plugin-support/shared-workers.js — Main-thread side: registers and manages shared worker lifecycle.
• reporters/beautify-stack.js — Strips AVA-internal frames from stack traces before display.
• reporters/colors.js — Terminal color constants used across all reporters.
• reporters/default.js — Full-featured TTY reporter with spinners, diffs, and summary.
• reporters/format-serialized-error.js — Converts IPC-transported error objects into renderable strings.
• reporters/improper-usage-messages.js — Human-readable messages for API misuse errors.
• reporters/prefix-title.js — Prepends file path to test titles in multi-file runs.
• reporters/tap.js — TAP 13 reporter for CI and tooling integration.
• worker/base.js — Abstract base for worker communication, sets up IPC listeners.
• worker/channel.js — Typed message channel between worker and main process.
• worker/completion-handlers.js — Registers process exit / unhandledRejection guards.
• worker/guard-environment.js — Asserts required environment variables are present before any test code runs.
• worker/line-numbers.js — Parses and applies line-number filters inside the worker.
• worker/main.js — Worker entry point; exports refs.runnerChain as default.
• worker/options.js — Deserializes run options sent from the main process via IPC.
• worker/plugin.js — Worker-side plugin host; bridges shared-worker messages.
• worker/state.js — Shared mutable state (flags, refs) and waitForReady promise.
• worker/utils.js — Small worker-scoped utilities (e.g. structured-clone helpers).

Common pitfalls and fixes

• ESM-only source on a CJS project: Add "type": "module" to package.json or rename all source files to .mjs; mixing require() and these files will throw ERR_REQUIRE_ESM.
• refs.runnerChain is falsy when worker/main.js loads: Set refs.runnerChain in worker/state.js before dynamically importing worker/main.js; the entry point asserts it synchronously.
• fs.watch recursive not available on Linux: Call watcher.available(projectDir) and gate watch mode behind it; do not assume recursive watch works in Docker or WSL1 environments.
• Snapshot version mismatch after updating AVA: Delete .snap files and re-run with --update-snapshots; VersionMismatchError is thrown from snapshot-manager.js and is not auto-healed.
• concordance peer version skew: This source pins concordance internally; installing a conflicting top-level version can produce silent diff rendering errors — keep a single resolved version.
• AssertionError swallowed as generic Error: Always check err instanceof AssertionError (imported from assert.js) before falling back to err instanceof Error; the name property alone is unreliable across module graph duplicates.

Vibe-coding prompt template

I have copied the AVA 8 test runner core library into `src/ava-core/` in my
project. The integration guide is in `USAGE.md`. The upstream package is
`user@example.com`.

Please help me integrate this source into my project step by step:

1. Read `USAGE.md` fully before writing any code.
2. Install all dependencies listed in the "Required dependencies" section.
3. Confirm my `package.json` has `"type": "module"` and my `tsconfig.json`
   uses `"module": "NodeNext"`.
4. Show me how to import `Runner` from `src/ava-core/runner.js` and set up
   a minimal per-file test runner that logs passed/failed events to the console.
5. Show me how to import `AssertionError` from `src/ava-core/assert.js` and
   write a custom assertion wrapper that re-throws with formatted details.
6. Show me how to use `available()` from `src/ava-core/watcher.js` to guard
   watch mode activation.
7. Point out any ESM/CJS interop issues specific to my project setup and
   provide fixes.

Do not invent any exports. Use only the symbols documented in `USAGE.md`.

License and credit

AVA is released under the MIT License. See source/LICENSE if present, or refer to the upstream repository for the canonical license text. This block is derived from user@example.com published on npm by the AVA core team.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完全なインストールガイドと統合プロンプトは購入後に解放されます。