AVA Test Runner

Shared workers allow a program to run in a worker thread within AVA's main process, enabling communication with code running in individual test workers. This is useful for managing shared resources (like database connections or port locking) across all test files in a run.

Key characteristics:

• Persistence: In watch mode, shared workers remain loaded across runs.
• Resource Management: They provide opportunities to set up resources before tests start and clean them up after.
• Communication: Test workers and the shared worker communicate via a versioned protocol using message passing.

You can share data between hooks and tests using t.context.

• When a .before() hook modifies t.context, a shallow copy is passed to .beforeEach() hooks and tests.
• For .beforeEach(), .afterEach(), and .afterEach.always(), the context is not shared between different tests, preventing data leakage.
• .after() and .after.always() hooks receive the original context value.

test.beforeEach(t => {
	t.context.data = generateUniqueData();
});

test('context data is foo', t => {
	t.is(t.context.data + 'bar', 'foobar');
});

By default, AVA runs tests concurrently. If your tests modify a shared database (like Mongoose/MongoDB), concurrent execution can cause tests to interfere with each other, leading to unpredictable results.

To ensure tests run one at a time and maintain a predictable state, use test.serial() instead of test().

If you require concurrent testing with a database, you must configure separate Mongoose connections for each test, which is a more complex setup.

In AVA, every test and hook is provided with an execution context object, conventionally named t. This object is unique to each test or hook and provides access to assertions, metadata, and lifecycle management methods. It is the primary interface for interacting with the test runner during execution.

import test from 'ava';

test('my passing test', t => {
	t.pass();
});

AVA natively supports asynchronous testing patterns. A test is treated as asynchronous if you:

1. Return a Promise.
2. Use an async function.
3. Return an Observable (from es-observable).

AVA will wait for the promise to resolve or the observable to complete before ending the test. If a promise rejects, the test fails.

// Promise support
test('resolves with unicorn', t => {
	return somePromise().then(result => {
		t.is(result, 'unicorn');
	});
});

// Async function support
test(async function (t) {
	const value = await promiseFn();
	t.true(value);
});

// Observable support
test('handles observables', t => {
	t.plan(3);
	return Observable.of(1, 2, 3, 4, 5, 6)
		.filter(n => n % 2 === 0)
		.map(() => t.pass());
});

AVA can automatically detect if your CI environment supports parallel builds using the ci-parallel-vars package. When detected, AVA sorts all test files by name and splits them into chunks. Each CI machine is assigned a specific chunk (subset) of tests to run in parallel, optimizing execution time.

To disable this automatic detection and splitting, set utilizeParallelBuilds to false in your AVA configuration.

When using snapshot testing in AVA, the actual snapshot data is saved in a .snap file (e.g., try-snapshot.js.snap). The test report displays the snapshots captured during the run, categorized by how the tests were executed: serial or concurrent.

Each snapshot in the report is identified by a number (e.g., > Snapshot 1) followed by the captured value. This allows you to verify that the expected output matches the recorded snapshot.

## serial

> Snapshot 1

    'hello'

> Snapshot 2

    true

AVA supports snapshot testing for any value via its assertions interface. When a snapshot assertion is executed, AVA creates two files alongside your test file:

1. .snap file: Contains the actual snapshot data and is required for future comparisons.
2. .md file: A snapshot report that can be committed to source control to allow diffing changes.

Storage Locations:

• If tests are in test/ or tests/, snapshots are stored in test/snapshots/ or tests/snapshots/.
• If tests are in __tests__/, snapshots are stored in __snapshots__/.
• If running against precompiled files (e.g., TypeScript), AVA uses source maps to store snapshots next to the original source files.

Example File Structure: If your test is at ~/project/test/main.js, AVA creates:

• ~/project/test/snapshots/main.js.snap
• ~/project/test/snapshots/main.js.md

When setting up test state in AVA, you can use the built-in beforeEach() hook or plain JavaScript setup functions.

Use beforeEach() when:

• You want the same setup applied to all tests in a file.
• You need built-in support for observables.
• You want failure output to be clearly associated with the hook rather than the test.
• You want to use afterEach() or afterEach.always() for automatic cleanup.

Use setup functions when:

• You need different setup requirements for different tests.
• You want to skip setup for specific tests.
• You need to pass parameters to customize the setup (e.g., valid vs. invalid data).
• You want to avoid the "magic" of hooks and keep setup logic explicit within the test body.
• Note: Asynchronous setup functions must use Promises.

Assertion planning via t.plan(n) ensures that a test only passes if exactly n assertions are executed. This prevents tests from exiting early (e.g., due to an unhandled promise or early return) without running all intended checks. It also prevents tests from passing if too many assertions are executed (e.g., inside a loop).

Important Behaviors:

• If you do not specify a plan, AVA will still fail if zero assertions are executed (unless failWithoutAssertions is set to false in your package.json configuration).
• Unlike tap or tape, AVA does not automatically end a test when the planned assertion count is reached.

test('resolves with 3', t => {
	t.plan(1);

	return Promise.resolve(3).then(n => {
		t.is(n, 3);
	});
});