Sindre Sorhus
c0bc39364c
|
9 years ago | |
---|---|---|
lib | 9 years ago | |
media | 9 years ago | |
test | 9 years ago | |
.editorconfig | 9 years ago | |
.gitattributes | 9 years ago | |
.gitignore | 10 years ago | |
.travis.yml | 9 years ago | |
cli.js | 9 years ago | |
index.js | 9 years ago | |
license | 10 years ago | |
package.json | 9 years ago | |
readme.md | 9 years ago | |
screenshot.png | 9 years ago |
readme.md
Simple concurrent test runner
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. 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 that don't depend on global state or the state of other tests, which is a great thing!
Why AVA?
- Minimal and fast
- Simple test syntax
- Runs test files in parallel
- Runs tests concurrently
- Enforces writing atomic tests
- Write your tests in ES2015
- Promise support
- Generator function support
- Async function support
- No implicit globals
Test syntax
import test from 'ava';
test(t => {
t.same([1, 2], [1, 2]);
t.end();
});
Usage
Initialize
Simply 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.2.0"
}
}
Create your test file
var test = require('ava');
test('foo', function (t) {
t.pass();
t.end();
});
test('bar', function (t) {
t.plan(2)
setTimeout(function () {
t.is('bar', 'bar');
t.same(['a', 'b'], ['a', 'b']);
}, 100);
});
Run it
$ npm test
CLI
$ ava --help
Usage
ava <file|folder|glob> [...]
Options
--init Add AVA to your project
Examples
ava
ava test.js test2.js
ava test-*.js
ava --init
ava --init foo.js
Default patterns when no arguments:
test.js test-*.js test/*.js
Files starting with _
are ignored. This can be useful for having helpers in the same directory as your test files.
Documentation
Test files are just normal Node.js scripts and can be run with $ node test.js
. However, using the CLI is preferred for simplicity, ES2015 support, parallelism, etc.
Tests are run async and require you to either set planned assertions t.plan(1)
, explicitly end the test when done t.end()
, or return a promise.
You have to define all tests synchronously, meaning you can't define a test in the next tick, e.g. inside a setTimeout
.
Test anatomy
To create a test, you just call the test
function you require'd from AVA and pass in an optional test name and a callback function containing the test execution. The passed callback function is given the context as the first argument where you can call the different AVA methods and assertions.
test('name', function (t) {
t.pass();
t.end();
});
Optional test name
Naming a test is optional, but you're recommended to use one if you have more than one test.
test(function (t) {
t.end();
});
You can also choose to use a named function instead:
test(function name(t) {
t.end();
});
Planned assertions
Planned assertions are useful for being able to assert that all async actions happened and catch bugs where too many assertions happen. It also comes with the benefit of not having to manually end the test.
This will result in a passed test:
test(function (t) {
t.plan(1);
setTimeout(function () {
t.pass();
}, 100);
});
And this will result in an error because the code called more assertions than planned:
test(function (t) {
t.plan(1);
t.pass();
setTimeout(function () {
t.pass();
}, 100);
});
Serial test execution
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(function (t) {
t.end();
});
Before/after hooks
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.
test.before(function (t) {
// this test runs before all others
t.end();
});
test.after(function (t) {
// this test runs after all others
t.end();
});
test(function (t) {
// regular test
t.end();
});
Custom assertion module
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.
var assert = require('assert');
test(function (t) {
assert(true);
t.end();
});
ES2015 support
AVA comes with builtin support for ES2015 through Babel.
Just write your tests in ES2015. No extra setup needed.
test(t => {
t.pass();
t.end();
});
You can also use your own local Babel version:
{
"devDependencies": {
"ava": "^0.2.0",
"babel-core": "^5.8.0"
}
}
Promise support
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(function (t) {
return somePromise().then(function (result) {
t.is(result, 'unicorn');
});
});
Generator function support
AVA comes with builtin support for generator functions.
test(function * (t) {
const value = yield generatorFn();
t.end();
});
Async function support
AVA comes with builtin support for async functions (async/await).
test(async function (t) {
const value = await promiseFn();
t.end();
});
// async arrow function
test(async t => {
const value = await promiseFn();
t.end();
});
API
test([name], body)
test.serial([name], body)
test.before(body)
test.after(body)
name
Type: string
Test name.
body(context)
Type: function
Should contain the actual test.
context
Passed into the test function and contains the different AVA methods and assertions.
.plan(count)
Plan how many assertion there are in the test. The test will fail if the actual assertion count doesn't match planned assertions. When planned assertions are used you don't need to explicitly end the test.
Be aware that this doesn't work with custom assert modules. You must then call .end()
explicitly.
.end()
End the test. Use this when plan()
is not used.
Assertions
Assertions are mixed into the test context:
test(function (t) {
t.ok('unicorn'); // assertion
t.end();
});
.pass([message])
Passing assertion.
.fail([message])
Failing assertion.
.ok(value, [message])
Assert that value
is truthy.
.notOk(value, [message])
Assert that value
is falsy.
.true(value, [message])
Assert that value
is true
.
.false(value, [message])
Assert that value
is false
.
.is(value, expected, [message])
Assert that value
is equal to expected
.
.not(value, expected, [message])
Assert that value
is not equal to expected
.
.same(value, expected, [message])
Assert that value
is deep equal to expected
.
.notSame(value, expected, [message])
Assert that value
is not deep equal to expected
.
.throws(function, error, [message])
Assert that function
throws an error.
error
can be a constructor, regex or validation function.
.doesNotThrow(function, [message])
Assert that function
doesn't throw an error
.
.regexTest(regex, contents, [message])
Assert that regex
matches contents
.
.ifError(error, [message])
Assert that error
is falsy.
Tips
Temp files
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.
FAQ
Why not mocha
, tape
, node-tap
?
Mocha requires you to use implicit globals like describe
and it
, too unopinionated, bloated, synchronous by default, 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 will in the future support TAP through a reporter.
How is the name written?
AVA. Not Ava or ava.
What is the header background?
Concurrency vs. parallelism
Concurrency is not parallelism. It enables parallelism. It's about dealing with, while parallelism is about doing, lots of things at once.
Related
Created by
Sindre Sorhus | Kevin Mårtensson | Vadim Demedes |