8000 Clean up documentation in preparation for AVA 4 · avajs/ava@f09742f · GitHub
[go: up one dir, main page]
Skip to content

Commit f09742f

Browse files
novemberbornnovemberborn
authored
Clean up documentation in preparation for AVA 4
1 parent 0187779 commit f09742f

20 files changed

+47
-353
lines changed

‎docs/01-writing-tests.md

Lines changed: 7 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,7 @@ AVA tries to run test files with their current working directory set to the dire
1010

1111
## Test isolation
1212

13-
AVA 3 runs each test file in a separate Node.js process. This allows you to change the global state or overriding a built-in in one test file, without affecting another.
14-
15-
AVA 4 runs each test file in a new worker thread, though you can fall back to AVA 3's behavior of running in separate processes.
13+
Each test file is run in a new worker thread. This is new as of AVA 4, though you can fall back to AVA 3's behavior of running in separate processes.
1614

1715
AVA will set `process.env.NODE_ENV` to `test`, unless the `NODE_ENV` environment variable has been set. This is useful if the code you're testing has test defaults (for example when picking what database to connect to). It may cause your code or its dependencies to behave differently though. Note that `'NODE_ENV' in process.env` will always be `true`.
1816

@@ -91,19 +89,6 @@ test('handles observables', t => {
9189
});
9290
```
9391

94-
## Callback support
95-
96-
*👉 AVA 4 removes support for `test.cb()` and `t.end()`.*
97-
98-
AVA 3 supports using `t.end` as the final callback when using Node.js-style error-first callback APIs. AVA will consider any truthy value passed as the first argument to `t.end` to be an error. Note that `t.end` requires "callback mode", which can be enabled by using the `test.cb` chain.
99-
100-
```js
101-
test.cb('data.txt can be read', t => {
102-
// `t.end` automatically checks for error as first argument
103-
fs.readFile('data.txt', t.end);
104-
});
105-
```
106-
10792
## Running specific tests
10893

10994
During development it can be helpful to only run a few specific tests. This can be accomplished using the `.only` modifier:
@@ -122,8 +107,6 @@ You can use the `.only` modifier with all tests. It cannot be used with hooks or
122107

123108
*Note:* The `.only` modifier applies to the test file it's defined in, so if you run multiple test files, tests in other files will still run. If you want to only run the `test.only` test, provide just that test file to AVA.
124109

125-
In AVA 3, you cannot update snapshots when using `.only()`.
126-
127110
## Skipping tests
128111

129112
Sometimes failing tests can be hard to fix. You can tell AVA to temporarily skip these tests using the `.skip` modifier. They'll still be shown in the output (as having been skipped) but are never run.
@@ -138,8 +121,6 @@ You must specify the implementation function. You can use the `.skip` modifier w
138121

139122
If the test is likely to be failing for a while, use `.failing()` instead.
140123

141-
In AVA 3, you cannot update snapshots when using `.skip()`.
142-
143124
## Test placeholders ("todo")
144125

145126
You can use the `.todo` modifier when you're planning to write a test. Like skipped tests these placeholders are shown in the output. They only require a title; you cannot specify the implementation function.
@@ -277,10 +258,8 @@ Access data about the currently loaded test file run by reading `test.meta`.
277258

278259
Available properties:
279260

280-
* `file`: path to the test file
281-
* `snapshotDirectory`: directory where snapshots are stored
282-
283-
In AVA 4 these are file URL strings.
261+
* `file`: path to the test file, as a file URL string
262+
* `snapshotDirectory`: directory where snapshots are stored, as a file URL string
284263

285264
```js
286265
const test = require('ava');
@@ -294,7 +273,7 @@ console.log('Test file currently being run:', test.meta.file);
294273

295274
Additional arguments passed to the test declaration will be passed to the test implementation. This is useful for creating reusable test macros.
296275

297-
You can use plain functions:
276+
You _could_ use plain functions:
298277

299278
```js
300279
function macro(t, input, expected) {
@@ -305,23 +284,7 @@ test('2 + 2 = 4', macro, '2 + 2', 4);
305284
test('2 * 3 = 6', macro, '2 * 3', 6);
306285
```
307286

308-
With AVA 3 you can build the test title programmatically by attaching a `title` function to the macro:
309-
310-
```js
311-
function macro(t, input, expected) {
312-
t.is(eval(input), expected);
313-
}
314-
315-
macro.title = (providedTitle = '', input, expected) => `${providedTitle} ${input} = ${expected}`.trim();
316-
317-
test(macro, '2 + 2', 4);
318-
test(macro, '2 * 3', 6);
319-
test('providedTitle', macro, '3 * 3', 9);
320-
```
321-
322-
The `providedTitle` argument defaults to `undefined` if the user does not supply a string title. This means you can use a parameter assignment to set the default value. The example above uses the empty string as the default.
323-
324-
However with AVA 4 the preferred approach is to use the `test.macro()` helper:
287+
However the preferred approach is to use the `test.macro()` helper:
325288

326289
```js
327290
import test from 'ava';
@@ -344,12 +307,12 @@ const macro = test.macro({
344307
},
345308
title(providedTitle = '', input, expected) {
346309
return `${providedTitle} ${input} = ${expected}`.trim();
347-
}
310+
},
348311
});
349312

350313
test(macro, '2 + 2', 4);
351314
test(macro, '2 * 3', 6);
352315
test('providedTitle', macro, '3 * 3', 9);
353316
```
354317

355-
We encourage you to use macros instead of building your own test generators ([here is an example](https://github.com/avajs/ava-codemods/blob/47073b5b58aa6f3fb24f98757be5d3f56218d160/test/ok-to-truthy.js#L7-L9) of code that should be replaced with a macro). Macros are designed to perform static analysis of your code, which can lead to better performance, IDE integration, and linter rules.
318+
The `providedTitle` argument defaults to `undefined` if the user does not supply a string title. This means you can use a parameter assignment to set the default value. The example above uses the empty string as the default.

‎docs/02-execution-context.md

Lines changed: 1 addition & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -26,10 +26,6 @@ Contains shared state from hooks.
2626

2727
When used in `test.afterEach()` or `test.afterEach.always()` hooks this tells you whether the test has passed. When used in a test itself (including teardown functions) this remains `true` until an assertion fails, the test has ended with an error, or a teardown function caused an error. This value has no meaning in other hooks.
2828

29-
## `t.end()`
30-
31-
End the test. Only works with `test.cb()`. Removed in AVA 4.
32-
3329
## `t.log(...values)`
3430

3531
Log values contextually alongside the test result instead of immediately printing them to `stdout`. Behaves somewhat like `console.log`, but without support for placeholder tokens.
@@ -40,36 +36,12 @@ Plan how many assertions there are in the test. The test will fail if the actual
4036

4137
## `t.teardown(fn)`
4238

43-
Registers the `fn` function to be run after the test has finished. You can register multiple functions. In AVA 3 the functions are called in order, but in AVA 4 they'll run in _reverse_ order.<sup>†</sup>. You can use asynchronous functions: only one will run at a time.
39+
Registers the `fn` function to be run after the test has finished. You can register multiple functions. They'll run in reverse order, so the most last registered function is run first. You can use asynchronous functions: only one will run at a time.
4440

4541
You cannot perform assertions using the `t` object or register additional functions from inside `fn`.
4642

4743
You cannot use `t.teardown()` in hooks either.
4844

49-
<sup>†</sup> You can opt in to this behavior in AVA 3 by enabling the `reverseTeardowns` experiment.
50-
51-
**`package.json`**:
52-
53-
```json
54-
{
55-
"ava": {
56-
"nonSemVerExperiments": {
57-
"reverseTeardowns": true
58-
}
59-
}
60-
}
61-
```
62-
63-
**`ava.config.js`**:
64-
65-
```js
66-
export default {
67-
nonSemVerExperiments: {
68-
reverseTeardowns: true
69-
}
70-
}
71-
```
72-
7345
## `t.timeout(ms)`
7446

7547
Set a timeout for the test, in milliseconds. The test will fail if this timeout is exceeded. The timeout is reset each time an assertion is made.

‎docs/03-assertions.md

Lines changed: 4 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -75,69 +75,6 @@ test('skip assertion', t => {
7575
});
7676
```
7777

78-
## Enhanced assertion messages
79-
80-
With AVA 3, enabling [Babel](./recipes/babel.md) will also enable [`power-assert`](https://github.com/power-assert-js/power-assert), giving you more descriptive assertion messages.
81-
82-
Let's take this example, using Node's standard [`assert` library](https://nodejs.org/api/assert.html):
83-
84-
```js
85-
const a = /foo/;
86-
const b = 'bar';
87-
const c = 'baz';
88-
require('assert').ok(a.test(b) || b === c);
89-
```
90-
91-
If you paste that into a Node REPL it'll return:
92-
93-
```
94-
AssertionError: false == true
95-
```
96-
97-
With AVA's `assert` assertion however, this test:
98-
99-
```js
100-
test('enhanced assertions', t => {
101-
const a = /foo/;
102-
const b = 'bar';
103-
const c = 'baz';
104-
t.assert(a.test(b) || b === c);
105-
});
106-
```
107-
108-
Will output:
109-
110-
```
111-
6: const c = 'baz';
112-
7: t.assert(a.test(b) || b === c);
113-
8: });
114-
115-
Value is not truthy:
116-
117-
false
118-
119-
a.test(b) || b === c
120-
=> false
121-
122-
b === c
123-
=> false
124-
125-
c
126-
=> 'baz'
127-
128-
b
129-
=> 'bar'
130-
131-
a.test(b)
132-
=> false
133-
134-
b
135-
=> 'bar'
136-
137-
a
138-
=> /foo/
139-
```
140-
14178
## Custom assertions
14279

14380
You can use any assertion library instead of or in addition to the built-in one, provided it throws exceptions when the assertion fails.
@@ -166,7 +103,7 @@ Failing assertion. Returns a boolean indicating whether the assertion passed.
166103

167104
### `.assert(value, message?)`
168105

169-
Asserts that `value` is truthy. This is [`power-assert`](#enhanced-assertion-messages) enabled. Returns a boolean indicating whether the assertion passed.
106+
Asserts that `value` is truthy. Returns a boolean indicating whether the assertion passed.
170107

171108
### `.truthy(value, message?)`
172109

@@ -194,7 +131,7 @@ Assert that `value` is not the same as `expected`. This is based on [`Object.is(
194131

195132
### `.deepEqual(value, expected, message?)`
196133

197-
Assert that `value` is deeply equal to `expected`. See [Concordance](https://github.com/concordancejs/concordance) for details. In AVA 3 this works with [React elements and `react-test-renderer`](https://github.com/concordancejs/react).
134+
Assert that `value` is deeply equal to `expected`. See [Concordance](https://github.com/concordancejs/concordance) for details.
198135

199136
### `.notDeepEqual(value, expected, message?)`
200137

@@ -239,7 +176,7 @@ Assert that an error is thrown. `fn` must be a function which should throw. The
239176
* `name`: the expected `.name` value of the thrown error
240177
* `code`: the expected `.code` value of the thrown error
241178

242-
`expectation` does not need to be specified. If you don't need it but do want to set an assertion message you have to specify `undefined`. (AVA 3 also allows you to specify `null`. This will be removed in AVA 4. You can opt into this change early by enabling the `disableNullExpectations` experiment.)
179+
`expectation` does not need to be specified. If you don't need it but do want to set an assertion message you have to specify `undefined`.
243180

244181
Example:
245182

@@ -271,7 +208,7 @@ The thrown value *must* be an error. It is returned so you can run more assertio
271208
* `name`: the expected `.name` value of the thrown error
272209
* `code`: the expected `.code` value of the thrown error
273210

274-
`expectation` does not need to be specified. If you don't need it but do want to set an assertion message you have to specify `undefined`. (AVA 3 also allows you to specify `null`. This will be removed in AVA 4. You can opt into this change early by enabling the `disableNullExpectations` experiment.)
211+
`expectation` does not need to be specified. If you don't need it but do want to set an assertion message you have to specify `undefined`.
275212

276213
Example:
277214

@@ -322,10 +259,6 @@ Assert that `contents` does not match `regex`. Returns a boolean indicating whet
322259

323260
Compares the `expected` value with a previously recorded snapshot. Snapshots are stored for each test, so ensure you give your tests unique titles.
324261

325-
AVA 3 supports an `options` object that lets you select a specific snapshot, for instance `{id: 'my snapshot'}`. This is buggy and will be removed in AVA 4.
326-
327-
In AVA 3, you cannot update snapshots while using `t.snapshot.skip()`.
328-
329262
### `.try(title?, implementation | macro, ...args?)`
330263

331264
`.try()` allows you to *try* assertions without causing the test to fail.

‎docs/04-snapshot-testing.md

Lines changed: 2 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -2,28 +2,7 @@
22

33
Translations: [Français](https://github.com/avajs/ava-docs/blob/master/fr_FR/docs/04-snapshot-testing.md)
44

5-
AVA supports snapshot testing, [as introduced by Jest](https://facebook.github.io/jest/docs/snapshot-testing.html), through its [Assertions](./03-assertions.md) interface. You can snapshot any value. In AVA 3 you can also snapshot React elements:
6-
7-
```js
8-
// Your component
9-
const HelloWorld = () => <h1>Hello World...!</h1>;
10-
11-
export default HelloWorld;
12-
```
13-
14-
```js
15-
// Your test
16-
const test = require('ava');
17-
const render = require('react-test-renderer');
18-
const HelloWorld = require('.');
19-
20-
test('HelloWorld component', t => {
21-
const tree = render.create(<HelloWorld/>).toJSON();
22-
t.snapshot(tree);
23-
});
24-
```
25-
26-
[Try it out in this example project.](https://github.com/avajs/ava-snapshot-example)
5+
AVA supports snapshot testing, [as introduced by Jest](https://facebook.github.io/jest/docs/snapshot-testing.html), through its [Assertions](./03-assertions.md) interface. You can snapshot any value.
276

287
Snapshots are stored alongside your test files. If your tests are in a `test` or `tests` folder the snapshots will be stored in a `snapshots` folder. If your tests are in a `__tests__` folder then they they'll be stored in a `__snapshots__` folder.
298

@@ -44,7 +23,7 @@ You can then check your code. If the change was intentional you can use the `--u
4423
$ ava --update-snapshots
4524
```
4625

47-
In AVA 4, if you need to update snapshots for only a particular test, you can use `--update-snapshots` together with e.g. `--match` or `.only()` to select the test.
26+
If you need to update snapshots for only a particular test, you can use `--update-snapshots` together with e.g. `--match` or `.only()` to select the test.
4827

4928
You can specify a fixed location for storing the snapshot files in AVA's [`package.json` configuration](./06-configuration.md):
5029

‎docs/05-command-line.md

Lines changed: 5 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ Options:
2929
--help Show help [boolean]
3030
--concurrency, -c Max number of test files running at the same time
3131
(default: CPU cores) [number]
32-
--no-worker-threads Don't use worker threads [boolean] (AVA 4 only)
32+
--no-worker-threads Don't use worker threads [boolean]
3333
--fail-fast Stop after first test failure [boolean]
3434
--match, -m Only run tests with matching title (can be repeated)
3535
[string]
@@ -40,7 +40,7 @@ Options:
4040
--timeout, -T Set global timeout (milliseconds or human-readable,
4141
e.g. 10s, 2m) [string]
4242
--update-snapshots, -u Update snapshots [boolean]
43-
--verbose, -v Enable verbose output (no-op in AVA 4) [boolean]
43+
--verbose, -v Enable verbose output (default) [boolean]
4444
--watch, -w Re-run tests when files change [boolean]
4545

4646
Examples:
@@ -49,8 +49,6 @@ Examples:
4949
ava test.js:4,7-9
5050
```
5151

52-
*Note that, for AVA 3, the CLI will use your local install of AVA when available, even when run globally. AVA 4 cannot be run globally.*
53-
5452
AVA searches for test files using the following patterns:
5553

5654
* `test.js`
@@ -164,7 +162,7 @@ AVA lets you run tests exclusively by referring to their line numbers. Target a
164162

165163
The format is a comma-separated list of `[X|Y-Z]` where `X`, `Y` and `Z` are integers between `1` and the last line number of the file.
166164

167-
This feature is only available from the command line. It won't work if you use tools like `ts-node/register` or `@babel/register`, and it does not currently work with `@ava/babel` (available for AVA 3) and `@ava/typescript`.
165+
This feature is only available from the command line.
168166

169167
### Running a single test
170168

@@ -220,7 +218,7 @@ When running a file with and without line numbers, line numbers take precedence.
220218

221219
## Resetting AVA's cache
222220

223-
AVA 3 itself does not cache files unless used with our [`@ava/babel`](https://github.com/avajs/babel) provider. If it seems like your latest changes aren't being picked up by AVA you can try resetting the cache by running:
221+
AVA maintains some temporary state. You can clear this state by running:
224222

225223
```console
226224
npx ava reset-cache
@@ -230,16 +228,10 @@ This deletes all files in the `node_modules/.cache/ava` directory.
230228

231229
## Reporters
232230

233-
AVA 4 uses a human readable reporter:
231+
AVA uses a human readable reporter by default:
234232

235233
<img src="../media/verbose-reporter.png" width="294">
236234

237-
AVA 3 defaults to a less verbose reporter:
238-
239-
<img src="../media/mini-reporter.gif" width="460">
240-
241-
Use the `--verbose` flag to enable the verbose reporter. This is always used in CI environments unless the [TAP reporter](#tap-reporter) is enabled.
242-
243235
### TAP reporter
244236

245237
[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/avajs/ava/tree/main/examples/tap-reporter?file=test.js&terminal=test&view=editor)

0 commit comments

Comments
 (0)
0