ava 0.16.0 → 0.18.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/readme.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  > Futuristic test runner
4
4
 
5
- [![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) [![Gitter](https://badges.gitter.im/join_chat.svg)](https://gitter.im/avajs/ava)
5
+ [![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)
6
6
 
7
7
  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!
8
8
 
@@ -14,15 +14,18 @@ Follow the [AVA Twitter account](https://twitter.com/ava__js) for updates.
14
14
 
15
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
16
 
17
+
17
18
  ## Contents
18
19
 
19
20
  - [Usage](#usage)
20
21
  - [CLI Usage](#cli)
22
+ - [Debugging](#debugging)
21
23
  - [Reporters](#reporters)
22
24
  - [Configuration](#configuration)
23
25
  - [Documentation](#documentation)
24
26
  - [API](#api)
25
27
  - [Assertions](#assertions)
28
+ - [Snapshot testing](#snapshot-testing)
26
29
  - [Tips](#tips)
27
30
  - [FAQ](#faq)
28
31
  - [Recipes](#recipes)
@@ -31,6 +34,7 @@ Translations: [Español](https://github.com/avajs/ava-docs/blob/master/es_ES/rea
31
34
  - [Links](#links)
32
35
  - [Team](#team)
33
36
 
37
+
34
38
  ## Why AVA?
35
39
 
36
40
  - Minimal and fast
@@ -38,15 +42,18 @@ Translations: [Español](https://github.com/avajs/ava-docs/blob/master/es_ES/rea
38
42
  - Runs tests concurrently
39
43
  - Enforces writing atomic tests
40
44
  - No implicit globals
45
+ - Includes TypeScript & Flow type definitions
46
+ - [Magic assert](#magic-assert)
41
47
  - [Isolated environment for each test file](#process-isolation)
42
- - [Write your tests in ES2015](#es2015-support)
48
+ - [Write your tests in ES2017](#es2017-support)
43
49
  - [Promise support](#promise-support)
44
50
  - [Generator function support](#generator-function-support)
45
51
  - [Async function support](#async-function-support)
46
52
  - [Observable support](#observable-support)
47
53
  - [Enhanced assertion messages](#enhanced-assertion-messages)
48
54
  - [TAP reporter](#tap-reporter)
49
- - [Clean stack traces](#clean-stack-traces)
55
+ - [Automatic migration from other test runners](https://github.com/avajs/ava-codemods#migrating-to-ava)
56
+
50
57
 
51
58
  ## Test syntax
52
59
 
@@ -62,7 +69,15 @@ test(t => {
62
69
 
63
70
  ### Add AVA to your project
64
71
 
65
- Install AVA globally and run it with `--init` to add AVA to your `package.json`:
72
+ Install AVA globally and run it with `--init` to add AVA to your `package.json`. [Yarn](https://yarnpkg.com/) currently provides significant speed improvements over npm during the installation process. Consider [using Yarn](https://yarnpkg.com/en/docs/install) if the installation is too slow for your needs.
73
+
74
+
75
+ ```console
76
+ $ yarn global add ava
77
+ $ ava --init
78
+ ```
79
+
80
+ If you prefer using npm:
66
81
 
67
82
  ```console
68
83
  $ npm install --global ava
@@ -78,7 +93,7 @@ Your `package.json` will then look like this:
78
93
  "test": "ava"
79
94
  },
80
95
  "devDependencies": {
81
- "ava": "^0.15.0"
96
+ "ava": "^0.18.0"
82
97
  }
83
98
  }
84
99
  ```
@@ -89,12 +104,17 @@ Any arguments passed after `--init` are added as config to `package.json`.
89
104
 
90
105
  You can also install AVA directly:
91
106
 
107
+ ```console
108
+ $ yarn add --dev ava
109
+ ```
110
+
111
+ Alternatively using npm:
112
+
92
113
  ```console
93
114
  $ npm install --save-dev ava
94
115
  ```
95
116
 
96
- You'll have to configure the `test` script in your `package.json` to use `ava`
97
- (see above).
117
+ You'll have to configure the `test` script in your `package.json` to use `ava` (see above).
98
118
 
99
119
  ### Create your test file
100
120
 
@@ -114,8 +134,6 @@ test('bar', async t => {
114
134
  });
115
135
  ```
116
136
 
117
- <img src="media/screenshot.png" width="150" align="right">
118
-
119
137
  ### Run it
120
138
 
121
139
  ```console
@@ -139,18 +157,19 @@ $ ava --help
139
157
  ava [<file|directory|glob> ...]
140
158
 
141
159
  Options
142
- --init Add AVA to your project
143
- --fail-fast Stop after first test failure
144
- --serial, -s Run tests serially
145
- --require, -r Module to preload (Can be repeated)
146
- --tap, -t Generate TAP output
147
- --verbose, -v Enable verbose output
148
- --no-cache Disable the transpiler cache
149
- --match, -m Only run tests with matching title (Can be repeated)
150
- --watch, -w Re-run tests when tests and source files change
151
- --source, -S Pattern to match source files so tests can be re-run (Can be repeated)
152
- --timeout, -T Set global timeout
153
- --concurrency, -c Maximum number of test files running at the same time (EXPERIMENTAL)
160
+ --init Add AVA to your project
161
+ --fail-fast Stop after first test failure
162
+ --serial, -s Run tests serially
163
+ --tap, -t Generate TAP output
164
+ --verbose, -v Enable verbose output
165
+ --no-cache Disable the transpiler cache
166
+ --no-power-assert Disable Power Assert
167
+ --no-color Disable color output
168
+ --match, -m Only run tests with matching title (Can be repeated)
169
+ --watch, -w Re-run tests when tests and source files change
170
+ --timeout, -T Set global timeout
171
+ --concurrency, -c Maximum number of test files running at the same time (EXPERIMENTAL)
172
+ --update-snapshots, -u Update snapshots
154
173
 
155
174
  Examples
156
175
  ava
@@ -170,6 +189,21 @@ Directories are recursed, with all `*.js` files being treated as test files. Dir
170
189
 
171
190
  When using `npm test`, you can pass positional arguments directly `npm test test2.js`, but flags needs to be passed like `npm test -- --verbose`.
172
191
 
192
+
193
+ ## Debugging
194
+
195
+ AVA runs tests in child processes, so to debug tests, you need to do this workaround:
196
+
197
+ ```console
198
+ $ node --inspect node_modules/ava/profile.js some/test/file.js
199
+ ```
200
+
201
+ ### Debugger-specific tips
202
+
203
+ - [Chrome DevTools](docs/recipes/debugging-with-chrome-devtools.md)
204
+ - [WebStorm](docs/recipes/debugging-with-webstorm.md)
205
+
206
+
173
207
  ## Reporters
174
208
 
175
209
  ### Mini-reporter
@@ -196,11 +230,15 @@ $ ava --tap | tap-nyan
196
230
 
197
231
  Please note that the TAP reporter is unavailable when using [watch mode](#watch-it).
198
232
 
199
- ### Clean stack traces
233
+ ### Magic assert
234
+
235
+ 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.
200
236
 
201
- AVA automatically removes unrelated lines in stack traces, allowing you to find the source of an error much faster.
237
+ ![](media/magic-assert-combined.png)
202
238
 
203
- <img src="media/stack-traces.png" width="300">
239
+ ### Clean stack traces
240
+
241
+ AVA automatically removes unrelated lines in stack traces, allowing you to find the source of an error much faster, as seen above.
204
242
 
205
243
 
206
244
  ## Configuration
@@ -225,6 +263,7 @@ All of the CLI options can be configured in the `ava` section of your `package.j
225
263
  "concurrency": 5,
226
264
  "failFast": true,
227
265
  "tap": true,
266
+ "powerAssert": false,
228
267
  "require": [
229
268
  "babel-register"
230
269
  ],
@@ -235,7 +274,7 @@ All of the CLI options can be configured in the `ava` section of your `package.j
235
274
 
236
275
  Arguments passed to the CLI will always take precedence over the configuration in `package.json`.
237
276
 
238
- See the [ES2015 support](#es2015-support) section for details on the `babel` option.
277
+ See the [ES2017 support](#es2017-support) section for details on the `babel` option.
239
278
 
240
279
  ## Documentation
241
280
 
@@ -243,15 +282,17 @@ Tests are run concurrently. You can specify synchronous and asynchronous tests.
243
282
 
244
283
  We *highly* recommend the use of [async functions](#async-function-support). They make asynchronous code concise and readable, and they implicitly return a promise so you don't have to.
245
284
 
246
- If you're unable to use promises or observables, 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.
285
+ If you're unable to use promises or observables, 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. However, we would strongly recommend [promisifying](https://github.com/sindresorhus/pify) callback-style APIs instead of using "callback mode", as this results in more correct and readable tests.
247
286
 
248
287
  You must define all tests synchronously. They can't be defined inside `setTimeout`, `setImmediate`, etc.
249
288
 
250
- 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')`.
289
+ AVA tries to run test files with their current working directory set to the directory that contains your `package.json` file.
251
290
 
252
291
  ### Creating tests
253
292
 
254
- 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`.
293
+ 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.
294
+
295
+ **Note:** In order for the [enhanced assertion messages](#enhanced-assertion-messages) to behave correctly, the first argument **must** be named `t`.
255
296
 
256
297
  ```js
257
298
  import test from 'ava';
@@ -317,7 +358,7 @@ test(t => {
317
358
  for (let i = 0; i < 3; i++) {
318
359
  t.true(i < 3);
319
360
  }
320
- }); // fails, 3 assertions are executed which is too many
361
+ }); // Fails, 3 assertions are executed which is too many
321
362
 
322
363
  test(t => {
323
364
  t.plan(1);
@@ -325,14 +366,14 @@ test(t => {
325
366
  someAsyncFunction(() => {
326
367
  t.pass();
327
368
  });
328
- }); // fails, the test ends synchronously before the assertion is executed
369
+ }); // Fails, the test ends synchronously before the assertion is executed
329
370
  ```
330
371
 
331
372
  ### Running tests serially
332
373
 
333
374
  By default tests are run concurrently, which is awesome. Sometimes though you have to write tests that cannot run concurrently.
334
375
 
335
- In these rare cases you can use the `.serial` modifier. It'll force those tests to run serially *before* the concurrent ones.
376
+ In these rare cases you can use the `.serial` modifier. It will force those tests to run serially *before* the concurrent ones.
336
377
 
337
378
  ```js
338
379
  test.serial(t => {
@@ -386,7 +427,7 @@ Match titles that are *exactly* `foo` (albeit case insensitively):
386
427
  $ ava --match='foo'
387
428
  ```
388
429
 
389
- Watch titles not containing `foo`:
430
+ Match titles not containing `foo`:
390
431
 
391
432
  ```console
392
433
  $ ava --match='!*foo*'
@@ -421,12 +462,12 @@ test.only('boo will run but not exclusively', t => {
421
462
  t.pass();
422
463
  });
423
464
 
424
- // won't run, no title
465
+ // Won't run, no title
425
466
  test(function (t) {
426
467
  t.fail();
427
468
  });
428
469
 
429
- // won't run, no explicit title
470
+ // Won't run, no explicit title
430
471
  test(function foo(t) {
431
472
  t.fail();
432
473
  });
@@ -461,7 +502,7 @@ This allows you to merge `.failing` tests before a fix is implemented without br
461
502
  ```js
462
503
  // See: github.com/user/repo/issues/1234
463
504
  test.failing('demonstrate some bug', t => {
464
- t.fail(); // test will count as passed
505
+ t.fail(); // Test will count as passed
465
506
  });
466
507
  ```
467
508
 
@@ -481,35 +522,35 @@ Like `test()` these methods take an optional title and a callback function. The
481
522
 
482
523
  ```js
483
524
  test.before(t => {
484
- // this runs before all tests
525
+ // This runs before all tests
485
526
  });
486
527
 
487
528
  test.before(t => {
488
- // this runs after the above, but before tests
529
+ // This runs after the above, but before tests
489
530
  });
490
531
 
491
532
  test.after('cleanup', t => {
492
- // this runs after all tests
533
+ // This runs after all tests
493
534
  });
494
535
 
495
536
  test.after.always('guaranteed cleanup', t => {
496
- // this will always run, regardless of earlier failures
537
+ // This will always run, regardless of earlier failures
497
538
  });
498
539
 
499
540
  test.beforeEach(t => {
500
- // this runs before each test
541
+ // This runs before each test
501
542
  });
502
543
 
503
544
  test.afterEach(t => {
504
- // this runs after each test
545
+ // This runs after each test
505
546
  });
506
547
 
507
548
  test.afterEach.always(t => {
508
- // this runs after each test and other test hooks, even if they failed
549
+ // This runs after each test and other test hooks, even if they failed
509
550
  });
510
551
 
511
552
  test(t => {
512
- // regular test
553
+ // Regular test
513
554
  });
514
555
  ```
515
556
 
@@ -549,7 +590,7 @@ test(t => {
549
590
  });
550
591
  ```
551
592
 
552
- By default `t.context` is an object but you can reassign it:
593
+ 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:
553
594
 
554
595
  ```js
555
596
  test.beforeEach(t => {
@@ -638,21 +679,17 @@ test(t => {
638
679
  });
639
680
  ```
640
681
 
641
- ### ES2015 support
682
+ ### ES2017 support
642
683
 
643
- AVA comes with built-in support for ES2015 through [Babel 6](https://babeljs.io). 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`](https://babeljs.io/docs/plugins/preset-es2015/) and [`stage-2`](https://babeljs.io/docs/plugins/preset-stage-2/) presets, as well as the [`espower`](https://github.com/power-assert-js/babel-plugin-espower) and [`transform-runtime`](https://babeljs.io/docs/plugins/transform-runtime/) plugins.
684
+ AVA comes with built-in support for ES2017 through [Babel 6](https://babeljs.io). Just write your tests in ES2017. No extra setup needed. You can use any Babel version in your project. We use our own bundled Babel with our [`@ava/stage-4`](https://github.com/avajs/babel-preset-stage-4) and [`stage-2`](https://babeljs.io/docs/plugins/preset-stage-2/) preset, as well as [custom transforms](https://github.com/avajs/babel-preset-transform-test-files) for test and helper files.
644
685
 
645
686
  The corresponding Babel config for AVA's setup is as follows:
646
687
 
647
688
  ```json
648
689
  {
649
690
  "presets": [
650
- "es2015",
651
- "stage-2"
652
- ],
653
- "plugins": [
654
- "espower",
655
- "transform-runtime"
691
+ "@ava/stage-4",
692
+ "@ava/transform-test-files"
656
693
  ]
657
694
  }
658
695
  ```
@@ -661,15 +698,15 @@ You can customize how AVA transpiles the test files through the `babel` option i
661
698
 
662
699
  ```json
663
700
  {
664
- "ava": {
665
- "babel": {
666
- "presets": [
667
- "es2015",
668
- "stage-0",
669
- "react"
670
- ]
671
- }
672
- },
701
+ "ava": {
702
+ "babel": {
703
+ "presets": [
704
+ "es2015",
705
+ "stage-0",
706
+ "react"
707
+ ]
708
+ }
709
+ }
673
710
  }
674
711
  ```
675
712
 
@@ -677,16 +714,16 @@ You can also use the special `"inherit"` keyword. This makes AVA defer to the Ba
677
714
 
678
715
  ```json
679
716
  {
680
- "babel": {
681
- "presets": [
682
- "es2015",
683
- "stage-0",
684
- "react"
685
- ]
686
- },
687
- "ava": {
688
- "babel": "inherit"
689
- },
717
+ "babel": {
718
+ "presets": [
719
+ "es2015",
720
+ "stage-0",
721
+ "react"
722
+ ]
723
+ },
724
+ "ava": {
725
+ "babel": "inherit"
726
+ }
690
727
  }
691
728
  ```
692
729
 
@@ -702,9 +739,9 @@ See AVA's [TypeScript recipe](docs/recipes/typescript.md) for a more detailed ex
702
739
 
703
740
  ### Transpiling imported modules
704
741
 
705
- 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.
742
+ AVA currently only transpiles the tests you ask it to run, as well as test helpers (files starting with `_` or in `helpers` directory) inside the test directory. *It will not transpile modules you `import` from outside of the test.* This may be unexpected but there are workarounds.
706
743
 
707
- 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).
744
+ 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).
708
745
 
709
746
  You can also transpile your modules in a separate process and refer to the transpiled files rather than the sources from your tests.
710
747
 
@@ -741,7 +778,7 @@ test(async function (t) {
741
778
  t.true(value);
742
779
  });
743
780
 
744
- // async arrow function
781
+ // Async arrow function
745
782
  test(async t => {
746
783
  const value = await promiseFn();
747
784
  t.true(value);
@@ -759,7 +796,7 @@ test(t => {
759
796
  t.plan(3);
760
797
  return Observable.of(1, 2, 3, 4, 5, 6)
761
798
  .filter(n => {
762
- // only even numbers
799
+ // Only even numbers
763
800
  return n % 2 === 0;
764
801
  })
765
802
  .map(() => t.pass());
@@ -772,7 +809,7 @@ AVA supports using `t.end` as the final callback when using node-style error-fir
772
809
 
773
810
  ```js
774
811
  test.cb(t => {
775
- // t.end automatically checks for error as first argument
812
+ // `t.end` automatically checks for error as first argument
776
813
  fs.readFile('data.txt', t.end);
777
814
  });
778
815
  ```
@@ -785,7 +822,7 @@ AVA resets a timer after each test, forcing tests to quit if no new test results
785
822
 
786
823
  You can set timeouts in a human-readable way:
787
824
 
788
- ```
825
+ ```console
789
826
  $ ava --timeout=10s # 10 seconds
790
827
  $ ava --timeout=2m # 2 minutes
791
828
  $ ava --timeout=100 # 100 milliseconds
@@ -837,7 +874,7 @@ Assertions are mixed into the [execution object](#t) provided to each test imple
837
874
 
838
875
  ```js
839
876
  test(t => {
840
- t.truthy('unicorn'); // assertion
877
+ t.truthy('unicorn'); // Assertion
841
878
  });
842
879
  ```
843
880
 
@@ -877,23 +914,52 @@ Assert that `value` is not equal to `expected`.
877
914
 
878
915
  ### `.deepEqual(value, expected, [message])`
879
916
 
880
- Assert that `value` is deep equal to `expected`.
917
+ Assert that `value` is deep equal to `expected`. This is based on [Lodash' `isEqual()`](https://lodash.com/docs/4.17.4#isEqual):
918
+
919
+ > Performs a deep comparison between two values to determine if they are equivalent.
920
+ >
921
+ > *Note*: This method supports comparing arrays, array buffers, booleans, date objects, error objects, maps, numbers, `Object` objects, regexes, sets, strings, symbols, and typed arrays. `Object` objects are compared by their own, not inherited, enumerable properties. Functions and DOM nodes are compared by strict equality, i.e. `===`.
881
922
 
882
923
  ### `.notDeepEqual(value, expected, [message])`
883
924
 
884
- Assert that `value` is not deep equal to `expected`.
925
+ Assert that `value` is not deep equal to `expected`. The inverse of `.deepEqual()`.
885
926
 
886
927
  ### `.throws(function|promise, [error, [message]])`
887
928
 
888
929
  Assert that `function` throws an error, or `promise` rejects with an error.
889
930
 
890
- `error` can be a constructor, regex, error message or validation function.
931
+ `error` can be an error constructor, error message, regex matched against the error message, or validation function.
932
+
933
+ Returns the error thrown by `function` or a promise for the rejection reason of the specified `promise`.
934
+
935
+ Example:
936
+
937
+ ```js
938
+ const fn = () => {
939
+ throw new TypeError('🦄');
940
+ };
941
+
942
+ test('throws', t => {
943
+ const error = t.throws(() => {
944
+ fn();
945
+ }, TypeError);
946
+
947
+ t.is(error.message, '🦄');
948
+ });
949
+ ```
950
+
951
+ ```js
952
+ const promise = Promise.reject(new TypeError('🦄'));
891
953
 
892
- Returns the error thrown by `function` or the rejection reason of `promise`.
954
+ test('rejects', async t => {
955
+ const error = await t.throws(promise);
956
+ t.is(error.message, '🦄');
957
+ });
958
+ ```
893
959
 
894
960
  ### `.notThrows(function|promise, [message])`
895
961
 
896
- Assert that `function` doesn't throw an `error` or `promise` resolves.
962
+ Assert that `function` does not throw an error or that `promise` does not reject with an error.
897
963
 
898
964
  ### `.regex(contents, regex, [message])`
899
965
 
@@ -907,6 +973,62 @@ Assert that `contents` does not match `regex`.
907
973
 
908
974
  Assert that `error` is falsy.
909
975
 
976
+ ### `.snapshot(contents, [message])`
977
+
978
+ Make a snapshot of the stringified `contents`.
979
+
980
+ ## Snapshot testing
981
+
982
+ Snapshot testing comes as another kind of assertion and uses [jest-snapshot](https://facebook.github.io/jest/blog/2016/07/27/jest-14.html) under the hood.
983
+
984
+ When used with React, it looks very similar to Jest:
985
+
986
+ ```js
987
+ // Your component
988
+ const HelloWorld = () => <h1>Hello World...!</h1>;
989
+
990
+ export default HelloWorld;
991
+ ```
992
+
993
+ ```js
994
+ // Your test
995
+ import test from 'ava';
996
+ import render from 'react-test-renderer';
997
+
998
+ import HelloWorld from '.';
999
+
1000
+ test('HelloWorld component', t => {
1001
+ const tree = render.create(<HelloWorld />).toJSON();
1002
+ t.snapshot(tree);
1003
+ });
1004
+ ```
1005
+
1006
+ The first time you run this test, a snapshot file will be created in `__snapshots__` folder looking something like this:
1007
+
1008
+ ```js
1009
+ exports[`HelloWorld component 1`] = `
1010
+ <h1>
1011
+ Hello World...!
1012
+ </h1>
1013
+ `;
1014
+ ```
1015
+
1016
+ These snapshots should be committed together with your code so that everyone on the team shares current state of the app.
1017
+
1018
+ Every time you run this test afterwards, it will check if the component render has changed. If it did, it will fail the test.
1019
+
1020
+ <img src="media/snapshot-testing.png" width="814">
1021
+
1022
+ Then you will have the choice to check your code - and if the change was intentional, you can use the `--update-snapshots` (or `-u`) flag to update the snapshots into their new version.
1023
+
1024
+ That might look like this:
1025
+
1026
+ ```console
1027
+ $ ava --update-snapshots
1028
+ ```
1029
+
1030
+ Note that snapshots can be used for much more than just testing components - you can equally well test any other (data) structure that you can stringify.
1031
+
910
1032
  ### Skipping assertions
911
1033
 
912
1034
  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.
@@ -914,7 +1036,7 @@ Any assertion can be skipped using the `skip` modifier. Skipped assertions are s
914
1036
  ```js
915
1037
  test(t => {
916
1038
  t.plan(2);
917
- t.skip.is(foo(), 5); // no need to change your plan count when skipping
1039
+ t.skip.is(foo(), 5); // No need to change your plan count when skipping
918
1040
  t.is(1, 1);
919
1041
  });
920
1042
  ```
@@ -970,14 +1092,6 @@ Running tests concurrently comes with some challenges, doing file IO is one.
970
1092
 
971
1093
  Usually, serial tests create temp directories in the current test directory and clean them 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`](https://github.com/sindresorhus/tempfile) and [`temp-write`](https://github.com/sindresorhus/temp-write) modules can be helpful.
972
1094
 
973
- ### Debugging
974
-
975
- AVA runs tests concurrently by default, which is suboptimal when you need to debug something. Instead, run tests serially with the `--serial` option:
976
-
977
- ```console
978
- $ ava --serial
979
- ```
980
-
981
1095
  ### Code coverage
982
1096
 
983
1097
  You can't use [`istanbul`](https://github.com/gotwarlost/istanbul) for code coverage as AVA [spawns the test files](#process-isolation). You can use [`nyc`](https://github.com/bcoe/nyc) instead, which is basically `istanbul` with support for subprocesses.
@@ -1021,6 +1135,8 @@ It's the [Andromeda galaxy](https://simple.wikipedia.org/wiki/Andromeda_galaxy).
1021
1135
  - [Configuring Babel](docs/recipes/babelrc.md)
1022
1136
  - [Testing React components](docs/recipes/react.md)
1023
1137
  - [JSPM and SystemJS](docs/recipes/jspm-systemjs.md)
1138
+ - [Debugging tests with Chrome DevTools](docs/recipes/debugging-with-chrome-devtools.md)
1139
+ - [Debugging tests with WebStorm](docs/recipes/debugging-with-webstorm.md)
1024
1140
 
1025
1141
  ## Support
1026
1142
 
@@ -1030,28 +1146,26 @@ It's the [Andromeda galaxy](https://simple.wikipedia.org/wiki/Andromeda_galaxy).
1030
1146
 
1031
1147
  ## Related
1032
1148
 
1149
+ - [eslint-plugin-ava](https://github.com/avajs/eslint-plugin-ava) - Lint rules for AVA tests
1033
1150
  - [sublime-ava](https://github.com/avajs/sublime-ava) - Snippets for AVA tests
1034
1151
  - [atom-ava](https://github.com/avajs/atom-ava) - Snippets for AVA tests
1035
1152
  - [vscode-ava](https://github.com/samverschueren/vscode-ava) - Snippets for AVA tests
1036
- - [eslint-plugin-ava](https://github.com/avajs/eslint-plugin-ava) - Lint rules for AVA tests
1037
1153
  - [gulp-ava](https://github.com/avajs/gulp-ava) - Run tests with gulp
1038
1154
  - [grunt-ava](https://github.com/avajs/grunt-ava) - Run tests with grunt
1039
- - [fly-ava](https://github.com/pine/fly-ava) - Run tests with fly
1040
- - [start-ava](https://github.com/start-runner/ava) - Run tests with start
1041
-
1042
- [More...](https://github.com/avajs/awesome-ava#packages)
1155
+ - [More…](https://github.com/avajs/awesome-ava#packages)
1043
1156
 
1044
1157
  ## Links
1045
1158
 
1046
1159
  - [Buy AVA stickers](https://www.stickermule.com/user/1070705604/stickers)
1047
1160
  - [Awesome list](https://github.com/avajs/awesome-ava)
1048
- - [JavaScript Air podcast episode](http://jsair.io/ava)
1161
+ - [AVA Casts](http://avacasts.com)
1162
+ - [More…](https://github.com/avajs/awesome-ava)
1049
1163
 
1050
1164
  ## Team
1051
1165
 
1052
- [![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)
1053
- ---|---|---|---|---|---
1054
- [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)
1166
+ [![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/vadimdemedes) | [![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)
1167
+ ---|---|---|---|---|---|---
1168
+ [Sindre Sorhus](http://sindresorhus.com) | [Vadim Demedes](https://github.com/vadimdemedes) | [James Talmage](https://github.com/jamestalmage) | [Mark Wubben](https://novemberborn.net) | [Juan Soto](http://juansoto.me) | [Jeroen Engels](https://github.com/jfmengels)
1055
1169
 
1056
1170
  ### Former
1057
1171