ava

What is ava?

AVA is a test runner for Node.js with a concise API, detailed error output, and process isolation that allows for fast and reliable testing. It supports asynchronous testing, and its design encourages writing tests that run concurrently.

What are ava's main functionalities?

Concurrent Test Execution

AVA runs tests concurrently, which can lead to faster test execution. The example shows two tests, one synchronous and one asynchronous, both of which will run concurrently.

const test = require('ava');

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

test('bar', async t => {
    const bar = Promise.resolve('bar');
    t.is(await bar, 'bar');
});

Snapshot Testing

AVA supports snapshot testing, which allows you to save the output of your tests and compare it to future test runs. This is useful for ensuring that your code's output remains consistent over time.

const test = require('ava');

test('snapshot', t => {
    const obj = {foo: 'bar'};
    t.snapshot(obj);
});

Power Assert

AVA uses power-assert to provide detailed assertion messages, making it easier to understand why a test failed. The example shows a failing test with a clear assertion message.

const test = require('ava');

test('power assert', t => {
    const x = 'foo';
    t.is(x, 'bar');
});

Test Isolation

AVA ensures that each test runs in isolation, preventing side effects from affecting other tests. The example shows how `t.context` can be used to set up data for each test.

const test = require('ava');

test.beforeEach(t => {
    t.context.data = {foo: 'bar'};
});

test('test 1', t => {
    t.context.data.foo = 'baz';
    t.is(t.context.data.foo, 'baz');
});

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

Other packages similar to ava

mocha

Mocha is a feature-rich JavaScript test framework running on Node.js and in the browser, making asynchronous testing simple and fun. It provides a variety of interfaces (e.g., BDD, TDD) and supports both synchronous and asynchronous testing. Compared to AVA, Mocha is more flexible but requires more configuration to achieve similar functionality.

jest

Jest is a delightful JavaScript Testing Framework with a focus on simplicity. It works out of the box for most JavaScript projects and includes features like snapshot testing, a built-in mocking library, and code coverage. Jest is more opinionated than AVA and provides a more integrated experience, especially for React applications.

tape

Tape is a tap-producing test harness for Node.js and browsers. It is minimalistic and focuses on providing a simple API for writing tests. Tape does not include features like test runners or reporters, which makes it less feature-rich compared to AVA but also simpler and more lightweight.

README

Please support our friend Vadim Demedes and the people in Ukraine.

---

AVA is a test runner for Node.js with a concise API, detailed error output, embrace of new language features and htread isolation that lets you develop with confidence 🚀

Watch this repository and follow the Discussions for updates.

Read our contributing guide if you're looking to contribute (issues / PRs / etc).

Translations: Español, Français, Italiano, 日本語, 한국어, Português, Русский, 简体中文

Why AVA?

• Minimal and fast
• Simple test syntax
• Runs tests concurrently
• Enforces writing atomic tests
• No implicit globals
• Includes TypeScript definitions
• Magic assert
• Isolated environment for each test file
• Promise support
• Async function support
• Observable support
• Enhanced assertion messages
• Automatic parallel test runs in CI
• TAP reporter

Usage

To install and set up AVA, run:

npm init ava

Your package.json will then look like this (exact version notwithstanding):

{
	"name": "awesome-package",
	"type": "module",
	"scripts": {
		"test": "ava"
	},
	"devDependencies": {
		"ava": "^5.0.0"
	}
}

Or if you prefer using Yarn:

yarn add ava --dev

Alternatively you can install ava manually:

npm install --save-dev ava

Make sure to install AVA locally. As of AVA 4 it can no longer be run globally.

Don't forget to configure the test script in your package.json as per above.

Create your test file

Create a file named test.js in the project root directory.

Note that AVA's documentation assumes you're using ES modules.

import test from 'ava';

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

test('bar', async t => {
	const bar = Promise.resolve('bar');
	t.is(await bar, 'bar');
});

Running your tests

npm test

Or with npx:

npx ava

Run with the --watch flag to enable AVA's watch mode:

npx ava --watch

Supported Node.js versions

AVA supports the latest release of any major version that is supported by Node.js itself. Read more in our support statement.

Highlights

Magic assert

AVA adds code excerpts and clean diffs for actual and expected values. If values in the assertion are objects or arrays, only a diff is displayed, to remove the noise and focus on the problem. The diff is syntax-highlighted too! If you are comparing strings, both single and multi line, AVA displays a different kind of output, highlighting the added or missing characters.

Clean stack traces

AVA automatically removes unrelated lines in stack traces, allowing you to find the source of an error much faster, as seen above.

Parallel runs in CI

AVA automatically detects whether your CI environment supports parallel builds. Each build will run a subset of all test files, while still making sure all tests get executed. See the ci-parallel-vars package for a list of supported CI environments.

Documentation

Please see the files in the docs directory:

• Writing tests
• Execution context
• Assertions
• Snapshot testing
• Command line (CLI)
• Configuration
• Test timeouts

Common pitfalls

We have a growing list of common pitfalls you may experience while using AVA. If you encounter any issues you think are common, comment in this issue.

Recipes

• Test setup
• TypeScript
• Shared workers
• Watch mode
• When to use t.plan()
• Passing arguments to your test files
• Splitting tests in CI
• Code coverage
• Endpoint testing
• Browser testing
• Testing Vue.js components
• Debugging tests with Chrome DevTools
• Debugging tests with VSCode
• Debugging tests with WebStorm
• Isolated MongoDB integration tests
• Testing web apps using Puppeteer
• Testing web apps using Selenium WebDriverJS

FAQ

How is the name written and pronounced?

AVA, not Ava or ava. Pronounced /ˈeɪvə/: Ay (face, made) V (vie, have) A (comma, ago)

What is the header background?

It's the Andromeda galaxy.

What is the difference between concurrency and parallelism?

Concurrency is not parallelism. It enables parallelism.

Support

• GitHub Discussions

Related

• eslint-plugin-ava — Lint rules for AVA tests
• @ava/typescript — Test TypeScript projects
• @ava/cooperate — Low-level primitives to enable cooperation between test files
• @ava/get-port — Reserve a port while testing

Links

• AVA stickers, t-shirts, etc
• Awesome list
• Do you like AVA? Donate here!
• More…

Team

Mark Wubben	Sindre Sorhus

Former

• Kevin Mårtensson
• James Talmage
• Juan Soto
• Jeroen Engels
• Vadim Demedes