UNPKG

9.55 kBMarkdownView Raw
1# <img src="media/header.png" title="AVA" alt="AVA logo" width="530">
2
3[![Build Status](https://travis-ci.org/avajs/ava.svg?branch=master)](https://travis-ci.org/avajs/ava) [![Coverage Status](https://codecov.io/gh/avajs/ava/branch/master/graph/badge.svg)](https://codecov.io/gh/avajs/ava/branch/master) [![XO code style](https://img.shields.io/badge/code_style-XO-5ed9c7.svg)](https://github.com/xojs/xo) [![Join the community on Spectrum](https://withspectrum.github.io/badge/badge.svg)](https://spectrum.chat/ava)
4[![Mentioned in Awesome Node.js](https://awesome.re/mentioned-badge.svg)](https://github.com/sindresorhus/awesome-nodejs)
5
6Testing can be a drag. AVA helps you get it done. AVA is a test runner for Node.js with a concise API, detailed error output, embrace of new language features and process isolation that let you write tests more effectively. So you can ship more awesome code. 🚀
7
8Follow the [AVA Twitter account](https://twitter.com/ava__js) for updates.
9
10Read our [contributing guide](.github/CONTRIBUTING.md) if you're looking to contribute (issues / PRs / etc).
11
12![](media/mini-reporter.gif)
13
14
15Translations: [Español](https://github.com/avajs/ava-docs/blob/master/es_ES/readme.md), [Français](https://github.com/avajs/ava-docs/blob/master/fr_FR/readme.md), [Italiano](https://github.com/avajs/ava-docs/blob/master/it_IT/readme.md), [日本語](https://github.com/avajs/ava-docs/blob/master/ja_JP/readme.md), [한국어](https://github.com/avajs/ava-docs/blob/master/ko_KR/readme.md), [Português](https://github.com/avajs/ava-docs/blob/master/pt_BR/readme.md), [Русский](https://github.com/avajs/ava-docs/blob/master/ru_RU/readme.md), [简体中文](https://github.com/avajs/ava-docs/blob/master/zh_CN/readme.md)
16
17
18## Why AVA?
19
20- Minimal and fast
21- Simple test syntax
22- Runs tests concurrently
23- Enforces writing atomic tests
24- No implicit globals
25- Includes TypeScript definitions
26- [Magic assert](#magic-assert)
27- [Isolated environment for each test file](./docs/01-writing-tests.md#process-isolation)
28- [Write your tests using the latest JavaScript syntax](https://github.com/avajs/babel)
29- [Promise support](./docs/01-writing-tests.md#promise-support)
30- [Async function support](./docs/01-writing-tests.md#async-function-support)
31- [Observable support](./docs/01-writing-tests.md#observable-support)
32- [Enhanced assertion messages](./docs/03-assertions.md#enhanced-assertion-messages)
33- [Automatic parallel test runs in CI](#parallel-runs-in-ci)
34- [TAP reporter](./docs/05-command-line.md#tap-reporter)
35
36
37## Usage
38
39To install and set up AVA, run:
40
41```console
42npm init ava
43```
44
45Your `package.json` will then look like this (exact version notwithstanding):
46
47```json
48{
49 "name": "awesome-package",
50 "scripts": {
51 "test": "ava"
52 },
53 "devDependencies": {
54 "ava": "^1.0.0"
55 }
56}
57```
58
59Or if you prefer using Yarn:
60
61```console
62yarn add ava --dev
63```
64
65Alternatively you can install `ava` manually:
66
67```console
68npm install --save-dev ava
69```
70
71Don't forget to configure the `test` script in your `package.json` as per above.
72
73### Create your test file
74
75Create a file named `test.js` in the project root directory:
76
77```js
78const test = require('ava');
79
80test('foo', t => {
81 t.pass();
82});
83
84test('bar', async t => {
85 const bar = Promise.resolve('bar');
86 t.is(await bar, 'bar');
87});
88```
89
90### Running your tests
91
92```console
93npm test
94```
95
96Or with `npx`:
97
98```console
99npx ava
100```
101
102Run with the `--watch` flag to enable AVA's [watch mode](docs/recipes/watch-mode.md):
103
104```console
105npx ava --watch
106```
107
108## Supported Node.js versions
109
110AVA supports the latest release of any major version that [is supported by Node.js itself](https://github.com/nodejs/Release#release-schedule). Read more in our [support statement](docs/support-statement.md).
111
112## Highlights
113
114### Magic assert
115
116AVA 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.
117
118![](media/magic-assert-combined.png)
119
120### Clean stack traces
121
122AVA automatically removes unrelated lines in stack traces, allowing you to find the source of an error much faster, as seen above.
123
124### Parallel runs in CI
125
126AVA 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`](https://www.npmjs.com/package/ci-parallel-vars) package for a list of supported CI environments.
127
128## Documentation
129
130Please see the [files in the `docs` directory](./docs):
131
132* [Writing tests](./docs/01-writing-tests.md)
133* [Execution context](./docs/02-execution-context.md)
134* [Assertions](./docs/03-assertions.md)
135* [Snapshot testing](./docs/04-snapshot-testing.md)
136* [Command line (CLI)](./docs/05-command-line.md)
137* [Configuration](./docs/06-configuration.md)
138* [Test timeouts](./docs/07-test-timeouts.md)
139
140### Common pitfalls
141
142We have a growing list of [common pitfalls](docs/08-common-pitfalls.md) you may experience while using AVA. If you encounter any issues you think are common, comment in [this issue](https://github.com/avajs/ava/issues/404).
143
144### Recipes
145
146- [Test setup](docs/recipes/test-setup.md)
147- [Code coverage](docs/recipes/code-coverage.md)
148- [Watch mode](docs/recipes/watch-mode.md)
149- [Endpoint testing](docs/recipes/endpoint-testing.md)
150- [When to use `t.plan()`](docs/recipes/when-to-use-plan.md)
151- [Browser testing](docs/recipes/browser-testing.md)
152- [TypeScript](docs/recipes/typescript.md)
153- [Flow](docs/recipes/flow.md)
154- [Configuring Babel](https://github.com/avajs/babel)
155- [Using ES modules](docs/recipes/es-modules.md)
156- [Passing arguments to your test files](docs/recipes/passing-arguments-to-your-test-files.md)
157- [Testing React components](docs/recipes/react.md)
158- [Testing Vue.js components](docs/recipes/vue.md)
159- [Debugging tests with Chrome DevTools](docs/recipes/debugging-with-chrome-devtools.md)
160- [Debugging tests with VSCode](docs/recipes/debugging-with-vscode.md)
161- [Debugging tests with WebStorm](docs/recipes/debugging-with-webstorm.md)
162- [Isolated MongoDB integration tests](docs/recipes/isolated-mongodb-integration-tests.md)
163- [Testing web apps using Puppeteer](docs/recipes/puppeteer.md)
164- [Testing web apps using Selenium WebDriverJS](docs/recipes/testing-with-selenium-webdriverjs.md)
165
166## FAQ
167
168### Why not `mocha`, `tape`, `tap`?
169
170Mocha requires you to use implicit globals like `describe` and `it` with the default interface (which most people use). It's not very opinionated and executes tests serially without process isolation, making it slow.
171
172Tape and tap are pretty good. AVA is highly inspired by their syntax. They too execute tests serially. Their default [TAP](https://testanything.org) output isn't very user-friendly though so you always end up using an external tap reporter.
173
174In contrast AVA is highly opinionated and runs tests concurrently, with a separate process for each test file. Its default reporter is easy on the eyes and yet AVA still supports TAP output through a CLI flag.
175
176### How is the name written and pronounced?
177
178AVA, not Ava or ava. Pronounced [`/ˈeɪvə/`](media/pronunciation.m4a?raw=true): Ay (f**a**ce, m**a**de) V (**v**ie, ha**v**e) A (comm**a**, **a**go)
179
180### What is the header background?
181
182It's the [Andromeda galaxy](https://simple.wikipedia.org/wiki/Andromeda_galaxy).
183
184### What is the difference between concurrency and parallelism?
185
186[Concurrency is not parallelism. It enables parallelism.](https://stackoverflow.com/q/1050222)
187
188## Support
189
190- [Stack Overflow](https://stackoverflow.com/questions/tagged/ava)
191- [Spectrum](https://spectrum.chat/ava)
192- [Twitter](https://twitter.com/ava__js)
193
194## Related
195
196- [eslint-plugin-ava](https://github.com/avajs/eslint-plugin-ava) - Lint rules for AVA tests
197- [sublime-ava](https://github.com/avajs/sublime-ava) - Snippets for AVA tests
198- [atom-ava](https://github.com/avajs/atom-ava) - Snippets for AVA tests
199- [vscode-ava](https://github.com/samverschueren/vscode-ava) - Snippets for AVA tests
200- [gulp-ava](https://github.com/avajs/gulp-ava) - Run tests with gulp
201- [grunt-ava](https://github.com/avajs/grunt-ava) - Run tests with grunt
202- [More…](https://github.com/avajs/awesome-ava#packages)
203
204## Links
205
206- [AVA stickers, t-shirts, etc](https://www.redbubble.com/people/sindresorhus/works/30330590-ava-logo)
207- [Awesome list](https://github.com/avajs/awesome-ava)
208- [AVA Casts](http://avacasts.com)
209- [Do you like AVA? Donate here!](https://opencollective.com/ava)
210- [More…](https://github.com/avajs/awesome-ava)
211
212## Team
213
214[![Mark Wubben](https://github.com/novemberborn.png?size=100)](https://github.com/novemberborn) | [![Sindre Sorhus](https://github.com/sindresorhus.png?size=100)](https://github.com/sindresorhus) | [![Vadim Demedes](https://github.com/vadimdemedes.png?size=100)](https://github.com/vadimdemedes)
215---|---|---
216[Mark Wubben](https://novemberborn.net) | [Sindre Sorhus](https://sindresorhus.com) | [Vadim Demedes](https://github.com/vadimdemedes)
217
218###### Former
219
220- [Kevin Mårtensson](https://github.com/kevva)
221- [James Talmage](https://github.com/jamestalmage)
222- [Juan Soto](https://github.com/sotojuan)
223- [Jeroen Engels](https://github.com/jfmengels)
224
225
226<div align="center">
227 <br>
228 <br>
229 <br>
230 <a href="https://avajs.dev">
231 <img src="media/logo.svg" width="200" alt="AVA">
232 </a>
233 <br>
234 <br>
235</div>