Guide · Open source
How to use AVA: install, write and run tests in Node.js
Updated · written with AI from the project's own documentation and checked against our catalogue data
AVA is an open-source test runner for JavaScript code that runs on Node.js. This guide shows you how to install it in a project, write a small test file, run the tests and read the results. By the end you will know how to set up AVA and run it locally or in watch mode.
AVAavajs/ava · ★ 20.8k · MIT Install options & downloads Quick start
- 1Install AVA. Run npm init ava in your project, or install ava locally with npm install --save-dev ava or yarn add ava --dev.
- 2Set the test script. Make sure package.json has a test script set to ava.
- 3Create test.js. Add a file named test.js in the project root with one or more test() calls.
- 4Write an assertion. Use t.pass() or t.is(actual, expected) inside each test function.
- 5Run the tests. Run npm test or npx ava from the terminal.
- 6Use watch mode. Run npx ava --watch to rerun tests as files change.
Install AVA in your Node.js project
AVA is installed locally in a project, because the README says it cannot be run globally. The recommended route is to let AVA set itself up with a single command. You can also install it manually with npm or Yarn.
Make sure you have Node.js and npm or Yarn available. The README does not give a specific Node.js version; it says AVA supports the latest release of any major version that Node.js itself supports.
- Recommended: run npm init ava in your project.
- Manual with npm: install ava as a dev dependency.
- With Yarn: add ava as a dev dependency.
npm init ava
npm install --save-dev ava
yarn add ava --devConfigure the test script and package.json
After setup, your package.json should include a test script that runs AVA and ava as a dev dependency. The README's example uses a version range for ava; your installed version may differ.
The README notes that AVA's documentation assumes you are using ES modules, which is why the example sets the type field to module.
- Set "type": "module" to use ES modules.
- Set the test script to ava so that npm test runs AVA.
{
"name": "awesome-package",
"type": "module",
"scripts": {
"test": "ava"
},
"devDependencies": {
"ava": "^5.0.0"
}
}Write your first test file
Create a file named test.js in the project root. Each test is a function you pass to test(). The function receives an object, here called t, that provides assertions such as t.pass() and t.is().
Tests can be async. The second example awaits a Promise and then checks its value with t.is().
- t.pass() marks a test as passing.
- t.is(actual, expected) checks that two values are equal.
- Async tests use an async function and await.
import test from 'ava';
test('foo', t => {
t.pass();
});
test('bar', async t => {
const bar = Promise.resolve('bar');
t.is(await bar, 'bar');
});Run your tests and read the output
Run the tests with npm test, or run npx ava directly. AVA reports which checks passed or failed. When a comparison fails, its magic assert shows code excerpts and a diff of the expected and actual values. For objects and arrays it shows only the diff, and for strings it highlights added or missing characters.
To rerun tests automatically as you edit, add the --watch flag. The README links to a watch mode recipe for more detail.
- npm test runs the test script.
- npx ava runs AVA directly.
- npx ava --watch reruns tests when files change.
npm test
npx ava
npx ava --watchRun tests in CI
AVA detects whether your CI environment supports parallel builds. When it does, each build runs a subset of all test files, and AVA still makes sure every test is executed. The README points to the ci-parallel-vars package for a list of supported CI environments.
- Parallel splitting happens automatically in supported CI environments.
- Each build runs a different subset of test files.
- Every test still runs across the full set of builds.
What people use it for
- Testing a Node.js library's functions with small, focused test files.
- Writing async tests that await Promises before checking results.
- Running the same test suite in parallel across CI builds.
- Using built-in TypeScript definitions in a TypeScript-based Node.js project.
Frequently asked questions
Is AVA free to use?
Yes. The repository is licensed under the MIT licence, as listed on its page. The README also mentions a donation link through Open Collective, but donating is optional.
How do I install AVA?
Run npm init ava in your project for the recommended setup. You can also run npm install --save-dev ava or yarn add ava --dev. AVA must be installed locally, not globally.
What Node.js version does AVA need?
The README does not name a specific version. It says AVA supports the latest release of any major version that Node.js itself supports, so use a currently supported Node.js release.
Can AVA be installed globally?
No. The README states that AVA cannot be run globally and must be installed in each project.
How does AVA compare to Jest, Mocha or Vitest?
AVA focuses on a concise API, concurrent test runs and isolated environments for each test file. The source does not include a feature comparison with these tools, so check their documentation for a direct comparison.
Can AVA test browser code?
Browser testing is not a core feature. The README lists it only as a recipe, so you would need to follow that recipe to set it up.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
AVA suits Node.js developers who want a small, straightforward test runner with ES module support, TypeScript definitions and automatic parallel splitting in CI. If you need browser-only testing, or you want a tool that runs globally, pick a different option. Check the README for your Node.js version before adopting it.
Install options & downloads