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 |
|
6 | AVA is a test runner for Node.js with a concise API, detailed error output, embrace of new language features and process isolation that lets you develop with confidence 🚀
|
7 |
|
8 | Follow the [AVA Twitter account](https://twitter.com/ava__js) for updates.
|
9 |
|
10 | Read our [contributing guide](.github/CONTRIBUTING.md) if you're looking to contribute (issues / PRs / etc).
|
11 |
|
12 | ![](media/mini-reporter.gif)
|
13 |
|
14 |
|
15 | Translations: [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 |
|
39 | To install and set up AVA, run:
|
40 |
|
41 | ```console
|
42 | npm init ava
|
43 | ```
|
44 |
|
45 | Your `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 |
|
59 | Or if you prefer using Yarn:
|
60 |
|
61 | ```console
|
62 | yarn add ava --dev
|
63 | ```
|
64 |
|
65 | Alternatively you can install `ava` manually:
|
66 |
|
67 | ```console
|
68 | npm install --save-dev ava
|
69 | ```
|
70 |
|
71 | Don't forget to configure the `test` script in your `package.json` as per above.
|
72 |
|
73 | ### Create your test file
|
74 |
|
75 | Create a file named `test.js` in the project root directory:
|
76 |
|
77 | ```js
|
78 | const test = require('ava');
|
79 |
|
80 | test('foo', t => {
|
81 | t.pass();
|
82 | });
|
83 |
|
84 | test('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
|
93 | npm test
|
94 | ```
|
95 |
|
96 | Or with `npx`:
|
97 |
|
98 | ```console
|
99 | npx ava
|
100 | ```
|
101 |
|
102 | Run with the `--watch` flag to enable AVA's [watch mode](docs/recipes/watch-mode.md):
|
103 |
|
104 | ```console
|
105 | npx ava --watch
|
106 | ```
|
107 |
|
108 | ## Supported Node.js versions
|
109 |
|
110 | AVA 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 |
|
116 | 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.
|
117 |
|
118 | ![](media/magic-assert-combined.png)
|
119 |
|
120 | ### Clean stack traces
|
121 |
|
122 | AVA 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 |
|
126 | 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`](https://www.npmjs.com/package/ci-parallel-vars) package for a list of supported CI environments.
|
127 |
|
128 | ## Documentation
|
129 |
|
130 | Please 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 |
|
142 | We 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 |
|
170 | Mocha 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 |
|
172 | Tape 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 |
|
174 | In 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 |
|
178 | AVA, 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 |
|
182 | It'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)
|
215 | ---|---
|
216 | [Mark Wubben](https://novemberborn.net) | [Sindre Sorhus](https://sindresorhus.com)
|
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 | - [Vadim Demedes](https://github.com/vadimdemedes)
|
225 |
|
226 |
|
227 | <div align="center">
|
228 | <br>
|
229 | <br>
|
230 | <br>
|
231 | <a href="https://avajs.dev">
|
232 | <img src="media/logo.svg" width="200" alt="AVA">
|
233 | </a>
|
234 | <br>
|
235 | <br>
|
236 | </div>
|