ava 0.15.0 → 0.17.0

package/readme.md

@@ -2,20 +2,23 @@
 
 > Futuristic test runner
 
-[![Build Status: Linux](https://travis-ci.org/avajs/ava.svg?branch=master)](https://travis-ci.org/avajs/ava) [![Build status: Windows](https://ci.appveyor.com/api/projects/status/igogxrcmhhm085co/branch/master?svg=true)](https://ci.appveyor.com/project/sindresorhus/ava/branch/master) [![Coverage Status](https://coveralls.io/repos/github/avajs/ava/badge.svg?branch=master)](https://coveralls.io/github/avajs/ava?branch=master) [![Gitter](https://badges.gitter.im/join_chat.svg)](https://gitter.im/avajs/ava)
+[![Build Status: Linux](https://travis-ci.org/avajs/ava.svg?branch=master)](https://travis-ci.org/avajs/ava) [![Build status: Windows](https://ci.appveyor.com/api/projects/status/e7v91mu2m5x48ehx/branch/master?svg=true)](https://ci.appveyor.com/project/ava/ava/branch/master) [![Coverage Status](https://coveralls.io/repos/github/avajs/ava/badge.svg?branch=master)](https://coveralls.io/github/avajs/ava?branch=master) [![Dependency Status](https://dependencyci.com/github/avajs/ava/badge)](https://dependencyci.com/github/avajs/ava) [![XO code style](https://img.shields.io/badge/code_style-XO-5ed9c7.svg)](https://github.com/sindresorhus/xo) [![Gitter](https://badges.gitter.im/join_chat.svg)](https://gitter.im/avajs/ava)
 
 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](https://github.com/sindresorhus/pageres/commit/663be15acb3dd2eb0f71b1956ef28c2cd3fdeed0) 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!
 
+![](media/screenshot-mini-reporter.gif)
+
 *Read our [contributing guide](contributing.md) if you're looking to contribute (issues/PRs/etc).*
 
 Follow the [AVA Twitter account](https://twitter.com/ava__js) for updates.
 
 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)
 
-## Table of Contents
+## Contents
 
 - [Usage](#usage)
 - [CLI Usage](#cli)
+- [Reporters](#reporters)
 - [Configuration](#configuration)
 - [Documentation](#documentation)
 - [API](#api)
@@ -42,8 +45,9 @@ Translations: [Español](https://github.com/avajs/ava-docs/blob/master/es_ES/rea
 - [Async function support](#async-function-support)
 - [Observable support](#observable-support)
 - [Enhanced assertion messages](#enhanced-assertion-messages)
-- [Optional TAP output](#optional-tap-output)
+- [TAP reporter](#tap-reporter)
 - [Clean stack traces](#clean-stack-traces)
+- [Automatic migration from other test runners](https://github.com/avajs/ava-codemods#migrating-to-ava)
 
 ## Test syntax
 
@@ -59,13 +63,15 @@ test(t => {
 
 ### Add AVA to your project
 
-Install AVA globally run with `--init` to add AVA to your `package.json`:
+Install AVA globally and run it with `--init` to add AVA to your `package.json`:
 
 ```console
 $ npm install --global ava
 $ ava --init
 ```
 
+Your `package.json` will then look like this:
+
 ```json
 {
   "name": "awesome-package",
@@ -73,12 +79,12 @@ $ ava --init
     "test": "ava"
   },
   "devDependencies": {
-    "ava": "^0.11.0"
+    "ava": "^0.15.0"
   }
 }
 ```
 
-Any arguments passed after `--init` are added in the `package.json`.
+Any arguments passed after `--init` are added as config to `package.json`.
 
 #### Manual installation
 
@@ -109,8 +115,6 @@ test('bar', async t => {
 });
 ```
 
-<img src="media/screenshot.png" width="150" align="right">
-
 ### Run it
 
 ```console
@@ -127,8 +131,6 @@ AVA comes with an intelligent watch mode. [Learn more in its recipe](docs/recipe
 
 ## CLI
 
-![](media/screenshot-mini-reporter.gif)
-
 ```console
 $ ava --help
 
@@ -139,10 +141,10 @@ $ ava --help
     --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
+    --no-power-assert  Disable Power Assert
     --match, -m        Only run tests with matching title (Can be repeated)
     --watch, -w        Re-run tests when tests and source files change
     --source, -S       Pattern to match source files so tests can be re-run (Can be repeated)
@@ -167,6 +169,39 @@ Directories are recursed, with all `*.js` files being treated as test files. Dir
 
 When using `npm test`, you can pass positional arguments directly `npm test test2.js`, but flags needs to be passed like `npm test -- --verbose`.
 
+## Reporters
+
+### Mini-reporter
+
+The mini-reporter is the default reporter.
+
+<img src="media/screenshot-mini-reporter.gif" width="460">
+
+### Verbose reporter
+
+Use the `--verbose` flag to enable the verbose reporter. This is always used in CI environments unless the [TAP reporter](#tap-reporter) is enabled.
+
+<img src="media/screenshot.png" width="150">
+
+### TAP reporter
+
+AVA supports the TAP format and thus is compatible with [any TAP reporter](https://github.com/sindresorhus/awesome-tap#reporters). Use the `--tap` flag to enable TAP output.
+
+```console
+$ ava --tap | tap-nyan
+```
+
+<img src="media/tap-output.png" width="398">
+
+Please note that the TAP reporter is unavailable when using [watch mode](#watch-it).
+
+### Clean stack traces
+
+AVA automatically removes unrelated lines in stack traces, allowing you to find the source of an error much faster.
+
+<img src="media/stack-traces.png" width="300">
+
+
 ## Configuration
 
 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.
@@ -186,8 +221,10 @@ All of the CLI options can be configured in the `ava` section of your `package.j
       "*oo",
       "!foo"
     ],
+    "concurrency": 5,
     "failFast": true,
     "tap": true,
+    "powerAssert": false,
     "require": [
       "babel-register"
     ],
@@ -210,11 +247,13 @@ If you're unable to use promises or observables, you may enable "callback mode"
 
 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()`](https://nodejs.org/api/process.html#process_process_cwd) is always the same as [`__dirname`](https://nodejs.org/api/globals.html#globals_dirname). You can just use relative paths instead of doing `path.join(__dirname, 'relative/path')`.
+AVA tries to run test files with their current working directory set to the directory that contains your `package.json` file.
 
 ### Creating tests
 
-To create a test you call the `test` function you imported from AVA. Provide the optional title and implementation function. The function will be called when your test is run. It's passed an [execution object](#t) as its first and only argument. By convention this argument is named `t`.
+To create a test you call the `test` function you imported from AVA. Provide the optional title and implementation function. The function will be called when your test is run. It's passed an [execution object](#t) as its first argument.
+
+**Note:** In order for the [enhanced assertion messages](#enhanced-assertion-messages) to behave correctly, the first argument **must** be named `t`.
 
 ```js
 import test from 'ava';
@@ -349,7 +388,7 @@ Match titles that are *exactly* `foo` (albeit case insensitively):
 $ ava --match='foo'
 ```
 
-Watch titles not containing `foo`:
+Match titles not containing `foo`:
 
 ```console
 $ ava --match='!*foo*'
@@ -432,7 +471,7 @@ test.failing('demonstrate some bug', t => {
 
 AVA lets you register hooks that are run before and after your tests. This allows you to run setup and/or teardown code.
 
-`test.before()` registers a hook to be run before the first test in your test file. Similarly `test.after()` registers a hook to be run after the last test. Use `test.after.always()` to register a hook that will **always** run once your tests and other hooks complete. `.always()` hooks run regardless of whether there were earlier failures, so they are ideal for cleanup tasks.
+`test.before()` registers a hook to be run before the first test in your test file. Similarly `test.after()` registers a hook to be run after the last test. Use `test.after.always()` to register a hook that will **always** run once your tests and other hooks complete. `.always()` hooks run regardless of whether there were earlier failures, so they are ideal for cleanup tasks. There are two exceptions to this however. If you use `--fail-fast` AVA will stop testing as soon as a failure occurs, and it won't run any hooks including the `.always()` hooks. Uncaught exceptions will crash your tests, possibly preventing `.always()` hooks from running.
 
 `test.beforeEach()` registers a hook to be run before each test in your test file. Similarly `test.afterEach()` a hook to be run after each test. Use `test.afterEach.always()` to register an after hook that is called even if other test hooks, or the test itself, fail. `.always()` hooks are ideal for cleanup tasks.
 
@@ -512,7 +551,7 @@ test(t => {
 });
 ```
 
-By default `t.context` is an object but you can reassign it:
+The context is not shared between tests, allowing you to set up data in a way where it will not risk leaking to other, subsequent tests. By default `t.context` is an object but you can reassign it:
 
 ```js
 test.beforeEach(t => {
@@ -638,7 +677,7 @@ You can customize how AVA transpiles the test files through the `babel` option i
 
 You can also use the special `"inherit"` keyword. This makes AVA defer to the Babel config in your [`.babelrc` or `package.json` file](https://babeljs.io/docs/usage/babelrc/). This way your test files will be transpiled using the same config as your source files without having to repeat it just for AVA:
 
- ```json
+```json
 {
 	"babel": {
 		"presets": [
@@ -661,11 +700,13 @@ Note that AVA will *always* apply [a few internal plugins](docs/recipes/babelrc.
 
 AVA includes typings for TypeScript. You have to set up 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.
 
+See AVA's [TypeScript recipe](docs/recipes/typescript.md) for a more detailed explanation.
+
 ### Transpiling imported modules
 
 AVA currently only transpiles the tests you ask it to run. *It will not transpile modules you `import` from outside of the test.* This may be unexpected but there are workarounds.
 
-If you use Babel you can use its [require hook](https://babeljs.io/docs/usage/require/) to transpile imported modules on-the-fly. Run AVA with `--require babel-register` (see [CLI](#cli)) or [configure it in your `package.json`](#configuration).
+If you use Babel you can use its [require hook](https://babeljs.io/docs/usage/require/) to transpile imported modules on-the-fly. To add it, [configure it in your `package.json`](#configuration).
 
 You can also transpile your modules in a separate process and refer to the transpiled files rather than the sources from your tests.
 
@@ -738,24 +779,6 @@ test.cb(t => {
 });
 ```
 
-### Optional TAP output
-
-AVA can generate TAP output via `--tap` option for use with any [TAP reporter](https://github.com/sindresorhus/awesome-tap#reporters).
-
-```console
-$ ava --tap | tap-nyan
-```
-
-<img src="media/tap-output.png" width="398">
-
-Please note that the TAP reporter is unavailable when using [watch mode](#watch-it).
-
-### Clean stack traces
-
-AVA automatically removes unrelated lines in stack traces, allowing you to find the source of an error much faster.
-
-<img src="media/stack-traces.png" width="300">
-
 ### Global timeout
 
 A global timeout can be set via the `--timeout` option.
@@ -878,6 +901,10 @@ Assert that `function` doesn't throw an `error` or `promise` resolves.
 
 Assert that `contents` matches `regex`.
 
+### `.notRegex(contents, regex, [message])`
+
+Assert that `contents` does not match `regex`.
+
 ### `.ifError(error, [message])`
 
 Assert that `error` is falsy.
@@ -959,6 +986,10 @@ You can't use [`istanbul`](https://github.com/gotwarlost/istanbul) for code cove
 
 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 Babel config to `inline`.
 
+### Common pitfalls
+
+We have a growing list of [common pitfalls](docs/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).
+
 ## FAQ
 
 ### Why not `mocha`, `tape`, `tap`?
@@ -969,10 +1000,6 @@ Tape and tap are pretty good. AVA is highly inspired by their syntax. They too e
 
 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.
 
-### How can I use custom reporters?
-
-AVA supports the TAP format and thus is compatible with any [TAP reporter](https://github.com/sindresorhus/awesome-tap#reporters). Use the [`--tap` flag](#optional-tap-output) to enable TAP output.
-
 ### How is the name written and pronounced?
 
 AVA, not Ava or ava. Pronounced [`/ˈeɪvə/` ay-və](media/pronunciation.m4a?raw=true).
@@ -995,6 +1022,8 @@ It's the [Andromeda galaxy](https://simple.wikipedia.org/wiki/Andromeda_galaxy).
 - [TypeScript](docs/recipes/typescript.md)
 - [Configuring Babel](docs/recipes/babelrc.md)
 - [Testing React components](docs/recipes/react.md)
+- [JSPM and SystemJS](docs/recipes/jspm-systemjs.md)
+- [Debugging tests with WebStorm](docs/recipes/debugging-with-webstorm.md)
 
 ## Support
 
@@ -1023,9 +1052,9 @@ It's the [Andromeda galaxy](https://simple.wikipedia.org/wiki/Andromeda_galaxy).
 
 ## Team
 
-[![Sindre Sorhus](https://avatars.githubusercontent.com/u/170270?s=130)](http://sindresorhus.com) | [![Vadim Demedes](https://avatars.githubusercontent.com/u/697676?s=130)](https://github.com/vdemedes) | [![James Talmage](https://avatars.githubusercontent.com/u/4082216?s=130)](https://github.com/jamestalmage) | [![Mark Wubben](https://avatars.githubusercontent.com/u/33538?s=130)](https://novemberborn.net) | [![Juan Soto](https://avatars.githubusercontent.com/u/8217766?s=130)](https://juansoto.me)
----|---|---|---|---|---
-[Sindre Sorhus](http://sindresorhus.com) | [Vadim Demedes](https://github.com/vdemedes) | [James Talmage](https://github.com/jamestalmage) | [Mark Wubben](https://novemberborn.net) | [Juan Soto](https://juansoto.me)
+[![Sindre Sorhus](https://avatars.githubusercontent.com/u/170270?s=130)](http://sindresorhus.com) | [![Vadim Demedes](https://avatars.githubusercontent.com/u/697676?s=130)](https://github.com/vdemedes) | [![James Talmage](https://avatars.githubusercontent.com/u/4082216?s=130)](https://github.com/jamestalmage) | [![Mark Wubben](https://avatars.githubusercontent.com/u/33538?s=130)](https://novemberborn.net) | [![Juan Soto](https://avatars.githubusercontent.com/u/8217766?s=130)](https://juansoto.me) | [![Jeroen Engels](https://avatars.githubusercontent.com/u/3869412?s=130)](https://github.com/jfmengels)
+---|---|---|---|---|---|---
+[Sindre Sorhus](http://sindresorhus.com) | [Vadim Demedes](https://github.com/vdemedes) | [James Talmage](https://github.com/jamestalmage) | [Mark Wubben](https://novemberborn.net) | [Juan Soto](http://juansoto.me) | [Jeroen Engels](https://github.com/jfmengels)
 
 ### Former