Futuristic test runner
![Gitter](https://badges.gitter.im/join chat.svg)
Even though JavaScript is single-threaded, IO in Node.js can happen in parallel due to its async nature. AVA takes advantage of this and runs your tests concurrently, which is especially beneficial for IO heavy tests. In addition, test files are run in parallel as separate processes, giving you even better performance and an isolated environment for each test file. Switching from Mocha to AVA in Pageres brought the test time down from 31 sec to 11 sec. Having tests run concurrently forces you to write atomic tests, meaning tests don't depend on global state or the state of other tests, which is a great thing!
Read our contributing guide if you're looking to contribute (issues/PRs/etc).
Follow the AVA Twitter account for updates.
Translations: Español, Français, 日本語, Português
- Minimal and fast
- Simple test syntax
- Runs tests concurrently
- Enforces writing atomic tests
- No implicit globals
- Isolated environment for each test file
- Write your tests in ES2015
- Promise support
- Generator function support
- Async function support
- Observable support
- Enhanced asserts
- Optional TAP output
- Clean stack traces
import test from 'ava';
test(t => {
t.same([1, 2], [1, 2]);
});
Install AVA globally $ npm install --global ava
and run $ ava --init
(with any options) to add AVA to your package.json or create one.
{
"name": "awesome-package",
"scripts": {
"test": "ava"
},
"devDependencies": {
"ava": "^0.11.0"
}
}
Create a file named test.js
in the project root directory:
import test from 'ava';
test('foo', t => {
t.pass();
});
test('bar', async t => {
const bar = Promise.resolve('bar');
t.is(await bar, 'bar');
});
$ npm test
$ ava --help
Usage
ava [<file|folder|glob> ...]
Options
--init Add AVA to your project
--fail-fast Stop after first test failure
--serial, -s Run tests serially
--require, -r Module to preload (Can be repeated)
--tap, -t Generate TAP output
--verbose, -v Enable verbose output
--no-cache Disable the transpiler cache
Examples
ava
ava test.js test2.js
ava test-*.js
ava test
ava --init
ava --init foo.js
Default patterns when no arguments:
test.js test-*.js test/**/*.js
Note that the CLI will use your local install of AVA when available, even when run globally.
Directories are recursive by default. Directories named fixtures
and helpers
are ignored, as well as files starting with _
. This can be useful for having helpers in the same directory as your test files.
When using npm test
, you can pass positional arguments directly npm test test2.js
, but flags needs to be passed like npm test -- --verbose
.
All of the CLI options can be configured in the ava
section of your package.json
. This allows you to modify the default behavior of the ava
command, so you don't have to repeatedly type the same options on the command prompt.
{
"ava": {
"files": [
"my-test-folder/*.js",
"!**/not-this-file.js"
],
"failFast": true,
"tap": true,
"require": [
"babel-register"
]
}
}
Arguments passed to the CLI will always take precedence over the configuration in package.json
.
Tests are run asynchronously and require you to return a supported async object (a promise, or observable). We highly recommend the use of async functions; They make async code concise and readable, and they implicitly return a promise, so you don't have to.
If you don't return one of the supported async objects mentioned above, the test is considered to be synchronous and ended immediately.
If you're unable to use promises or other supported async objects, you may enable "callback mode" by defining your test with test.cb([title], fn)
. Tests declared this way must be manually ended with t.end()
. This mode is mainly intended for testing callback-style APIs.
You must define all tests synchronously. They can't be defined inside setTimeout
, setImmediate
, etc.
Test files are run from their current directory, so process.cwd()
is always the same as __dirname
. You can just use relative paths instead of doing path.join(__dirname, 'relative/path')
.
To create a test, you call the test
function you require
d from AVA and pass in an optional test name and a function containing the test execution. The passed function is given the context as the first argument, where you can call the different AVA methods and assertions.
test('name', t => {
t.pass();
});
Naming a test is optional, but you're recommended to use one if you have more than one test.
test(t => {
t.pass();
});
You can also choose to use a named function instead:
test(function name(t) {
t.pass();
});
An assertion plan can be used to ensure a specific number of assertions are made. In the most common scenario, it validates that the test didn't exit before executing the expected number of assertions. It also fails the test if too many assertions are executed, which can be useful if you have assertions inside callbacks or loops. Be aware that, unlike node-tap & tape, AVA does not auto-end a test when the planned assertion count is reached.
This will result in a passed test:
test(t => {
t.plan(1);
return Promise.resolve(3).then(n => {
t.is(n, 3);
});
});
test.cb(t => {
t.plan(1);
someAsyncFunction(() => {
t.pass();
t.end();
});
});
While concurrency is awesome, there are some things that can't be done concurrently. In these rare cases, you can call test.serial
, which will force those tests to run serially before the concurrent ones.
test.serial(t => {
t.pass();
});
Only-tests enforces only those tests to be run. This can be useful for running only a few tests during development.
test('will not be run', t => {
t.fail();
})
test.only('will be run', t => {
t.pass();
});
Skip-tests are shown in the output as skipped but never run.
test.skip('will not be run', t => {
t.fail();
});
When setup and/or teardown is required, you can use test.before()
and test.after()
,
used in the same manner as test()
. The test function given to test.before()
and test.after()
is called before/after all tests. You can also use test.beforeEach()
and test.afterEach()
if you need setup/teardown for each test. Hooks are run serially in the test file. Add as many of these as you want. You can optionally specify a title that is shown on failure.
If you need to set up some global state between tests using test.beforeEach()
and test.afterEach()
(like spying on console.log
for example), you'll need to make sure the tests are run serially (using either test.serial or --serial
).
test.before(t => {
// this runs before all tests
});
test.before(t => {
// this runs after the above, but before tests
});
test.after('cleanup', t => {
// this runs after all tests
});
test.beforeEach(t => {
// this runs before each test
});
test.afterEach(t => {
// this runs after each test
});
test(t => {
// regular test
});
You may use async functions, return async objects, or enable "callback mode" in any of the hooks.
test.before(async t => {
await promiseFn();
});
test.cb.beforeEach(t => {
setTimeout(t.end);
});
test.afterEach.cb(t => {
setTimeout(t.end);
});
test.after(t => {
return new Promise(/* ... */);
});
The beforeEach
& afterEach
hooks can share context with the test:
test.beforeEach(t => {
t.context.data = generateUniqueData();
});
test(t => {
t.is(t.context.data + 'bar', 'foobar');
});
The context is by default an object, but it can also be directly assigned:
test.beforeEach(t => {
t.context = 'unicorn';
});
test(t => {
t.is(t.context, 'unicorn');
});
You can chain test modifiers together in the following ways:
test.before.skip([title], testFn);
test.skip.after(....);
test.serial.only(...);
test.only.serial(...);
This is especially helpful temporarily using skip
or only
on a test, without losing the information and behavior the other modifiers provide.
You can use any assertion module instead or in addition to the one that comes with AVA, but you won't be able to use the .plan()
method, yet.
import assert from 'assert';
test(t => {
assert(true);
});
AVA comes with builtin support for ES2015 through Babel 6. Just write your tests in ES2015. No extra setup needed. You can use any Babel version in your project. We use our own bundled Babel with the es2015
and stage-2
presets.
AVA includes typings for TypeScript. You have to setup transpilation yourself. When you set module
to commonjs
in your tsconfig.json
file, TypeScript will automatically find the type definitions for AVA. You should set target
to es2015
to use Promises and async functions.
AVA currently only transpiles the tests you ask it to run. It will not transpile modules you import
from outside of the test. While there are valid reasons for taking this approach, it may not be what you expect!
As a simple workaround, you can use Babel's require hook in order to do on-the-fly transpiling of modules that are subsequently imported. Because AVA supports ES2015 module syntax, you can use it to import the require hook itself:
import test from 'ava';
import 'babel-register';
import foo from './foo'; // <-- foo can be written in ES2015!
test('foo bar', t => {
t.same('baz', foo('bar'));
});
#111 is tracking this item as a potential enhancement.
If you return a promise in the test you don't need to explicitly end the test as it will end when the promise resolves.
test(t => {
return somePromise().then(result => {
t.is(result, 'unicorn');
});
});
AVA comes with builtin support for generator functions.
test(function * (t) {
const value = yield generatorFn();
t.true(value);
});
AVA comes with builtin support for async functions (async/await).
test(async function (t) {
const value = await promiseFn();
t.true(value);
});
// async arrow function
test(async t => {
const value = await promiseFn();
t.true(value);
});
AVA comes with builtin support for observables. If you return an observable from a test, AVA will automatically consume it to completion before ending the test.
You do not need to use "callback mode" or call t.end()
.
test(t => {
t.plan(3);
return Observable.of(1, 2, 3, 4, 5, 6)
.filter(n => {
// only even numbers
return n % 2 === 0;
})
.map(() => t.pass());
});
AVA supports using t.end
as the final callback when using node-style error-first callback APIs. AVA will consider any truthy value passed as the first argument to t.end
to be an error. Note that t.end
requires "callback mode", which can be enabled by using the test.cb
chain.
test.cb(t => {
// t.end automatically checks for error as first argument
fs.readFile('data.txt', t.end);
});
AVA can generate TAP output via --tap
option for use with any TAP reporter.
$ ava --tap | tap-nyan
AVA automatically removes unrelated lines in stack traces, allowing you to find the source of an error much faster.
Type: string
Test title.
Type: function
Should contain the actual test.
Passed into the test function and contains the different AVA methods and assertions.
Plan how many assertion there are in the test. The test will fail if the actual assertion count doesn't match planned assertions.
End the test. Only works with test.cb()
.
Assertions are mixed into the test context:
test(t => {
t.ok('unicorn'); // assertion
});
If multiple assertion failures are encountered within a single test, AVA will only display the first one.
Passing assertion.
Failing assertion.
Assert that value
is truthy.
Assert that value
is falsy.
Assert that value
is true
.
Assert that value
is false
.
Assert that value
is equal to expected
.
Assert that value
is not equal to expected
.
Assert that value
is deep equal to expected
.
Assert that value
is not deep equal to expected
.
Assert that function
throws an error or promise
rejects.
error
can be a constructor, regex, error message or validation function.
Assert that function
doesn't throw an error
or promise
resolves.
Assert that contents
matches regex
.
Assert that error
is falsy.
Any assertion can be skipped using the skip
modifier. Skipped assertions are still counted, so there is no need to change your planned assertion count.
test(t => {
t.plan(2);
t.skip.is(foo(), 5); // no need to change your plan count when skipping
t.is(1, 1);
});
AVA comes with power-assert
builtin, giving you more descriptive assertion messages. It reads your test and tries to infer more information from the code.
The following test:
test(t => {
const x = 'foo';
t.ok(x === 'bar');
});
Would normally give the unhelpful output:
false === true
With the enhanced asserts, you'll get:
t.ok(x === 'bar')
|
"foo"
True, you could use t.is()
in this case, and probably should, but this is just a simple example.
Let try a more advanced example:
test(t => {
const a = /foo/;
const b = 'bar';
const c = 'baz';
t.ok(a.test(b) || b === c);
});
And there you go:
t.ok(a.test(b) || b === c)
| | | |
| "bar" "bar" "baz"
false
All the assert methods are enhanced.
Have fun!
Each test file is run in a separate Node.js process. This comes with a lot of benefits. Different test files can no longer affect each other. Like test files mocking with the global environment, overriding builtins, etc. However, it's mainly done for performance reasons. Even though Node.js can run async IO concurrently, that doesn't help much when tests are heavy on synchronous operations, which blocks the main thread. By running tests concurrently and test files in parallel we take full advantage of modern systems.
Running tests concurrently comes with some challenges, doing IO is one. Usually, serial tests just create temp directories in the current test directory and cleans it up at the end. This won't work when you run tests concurrently as tests will conflict with each other. The correct way to do it is to use a new temp directory for each test. The tempfile
and temp-write
modules can be helpful.
AVA runs tests concurrently by default, which is suboptimal when you need to debug something. Instead, run tests serially with the --serial
option:
$ ava --serial
You can't use istanbul
for code coverage as AVA spawns the test files, but you can use nyc
instead, which is basically istanbul
with support for subprocesses.
As of version 5.0.0
it uses source maps to report coverage for your actual code, regardless of transpilation. Make sure that the code you're testing includes an inline source map or references a source map file. If you use babel-register
you can set the sourceMaps
option in your .babelrc
to inline
.
Mocha requires you to use implicit globals like describe
and it
with the default interface (which most people use), too unopinionated, bloated, synchronous by default, unusable programmatic API, serial test execution, and slow. Tape and node-tap are pretty good. AVA is highly inspired by their syntax. However, they both execute tests serially and they've made TAP a first-class citizen which has IMHO made their codebases a bit convoluted and coupled. TAP output is hard to read so you always end up using an external tap reporter. AVA is highly opinionated and concurrent. It comes with a default simple reporter and supports TAP through a CLI flag.
Use the --tap
flag with any TAP reporter.
AVA, not Ava or ava. Pronounced /ˈeɪvə/
ay-və.
Concurrency is not parallelism. It enables parallelism.
- sublime-ava - Snippets for AVA tests
- atom-ava - Snippets for AVA tests
- vscode-ava - Snippets for AVA tests
- eslint-plugin-ava - Lint rules for AVA tests
- gulp-ava - Run tests with gulp
- grunt-ava - Run tests with grunt
- fly-ava - Run tests with fly
- start-ava - Run tests with start
|
|
|
---|---|---|---|---
Sindre Sorhus | Vadim Demedes | James Talmage | Mark Wubben