Skip to content

Commit

Permalink
Clean up documentation in preparation for AVA 4
Browse files Browse the repository at this point in the history
  • Loading branch information
@novemberborn
novemberborn authored Jan 3, 2022
1 parent 0187779 commit f09742f
Show file tree
Hide file tree
Showing 20 changed files with 47 additions and 353 deletions.
51 changes: 7 additions & 44 deletions docs/01-writing-tests.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,7 @@ AVA tries to run test files with their current working directory set to the dire

## Test isolation

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.

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.
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.

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`.

Expand Down Expand Up @@ -91,19 +89,6 @@ test('handles observables', t => {
});
```

## Callback support

*👉 AVA 4 removes support for `test.cb()` and `t.end()`.*

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.

```js
test.cb('data.txt can be read', t => {
// `t.end` automatically checks for error as first argument
fs.readFile('data.txt', t.end);
});
```

## Running specific tests

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

*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.

In AVA 3, you cannot update snapshots when using `.only()`.

## Skipping tests

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.
Expand All @@ -138,8 +121,6 @@ You must specify the implementation function. You can use the `.skip` modifier w

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

In AVA 3, you cannot update snapshots when using `.skip()`.

## Test placeholders ("todo")

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.
Expand Down Expand Up @@ -277,10 +258,8 @@ Access data about the currently loaded test file run by reading `test.meta`.

Available properties:

* `file`: path to the test file
* `snapshotDirectory`: directory where snapshots are stored

In AVA 4 these are file URL strings.
* `file`: path to the test file, as a file URL string
* `snapshotDirectory`: directory where snapshots are stored, as a file URL string

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

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

You can use plain functions:
You _could_ use plain functions:

```js
function macro(t, input, expected) {
Expand All @@ -305,23 +284,7 @@ test('2 + 2 = 4', macro, '2 + 2', 4);
test('2 * 3 = 6', macro, '2 * 3', 6);
```

With AVA 3 you can build the test title programmatically by attaching a `title` function to the macro:

```js
function macro(t, input, expected) {
t.is(eval(input), expected);
}

macro.title = (providedTitle = '', input, expected) => `${providedTitle} ${input} = ${expected}`.trim();

test(macro, '2 + 2', 4);
test(macro, '2 * 3', 6);
test('providedTitle', macro, '3 * 3', 9);
```

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.

However with AVA 4 the preferred approach is to use the `test.macro()` helper:
However the preferred approach is to use the `test.macro()` helper:

```js
import test from 'ava';
Expand All @@ -344,12 +307,12 @@ const macro = test.macro({
},
title(providedTitle = '', input, expected) {
return `${providedTitle} ${input} = ${expected}`.trim();
}
},
});

test(macro, '2 + 2', 4);
test(macro, '2 * 3', 6);
test('providedTitle', macro, '3 * 3', 9);
```

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.
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.
30 changes: 1 addition & 29 deletions docs/02-execution-context.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,10 +26,6 @@ Contains shared state from hooks.

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.

## `t.end()`

End the test. Only works with `test.cb()`. Removed in AVA 4.

## `t.log(...values)`

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.
Expand All @@ -40,36 +36,12 @@ Plan how many assertions there are in the test. The test will fail if the actual

## `t.teardown(fn)`

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.
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.

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

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

<sup>†</sup> You can opt in to this behavior in AVA 3 by enabling the `reverseTeardowns` experiment.

**`package.json`**:

```json
{
"ava": {
"nonSemVerExperiments": {
"reverseTeardowns": true
}
}
}
```

**`ava.config.js`**:

```js
export default {
nonSemVerExperiments: {
reverseTeardowns: true
}
}
```

## `t.timeout(ms)`

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.
75 changes: 4 additions & 71 deletions docs/03-assertions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -75,69 +75,6 @@ test('skip assertion', t => {
});
```

## Enhanced assertion messages

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.

Let's take this example, using Node's standard [`assert` library](https://nodejs.org/api/assert.html):

```js
const a = /foo/;
const b = 'bar';
const c = 'baz';
require('assert').ok(a.test(b) || b === c);
```

If you paste that into a Node REPL it'll return:

```
AssertionError: false == true
```

With AVA's `assert` assertion however, this test:

```js
test('enhanced assertions', t => {
const a = /foo/;
const b = 'bar';
const c = 'baz';
t.assert(a.test(b) || b === c);
});
```

Will output:

```
6: const c = 'baz';
7: t.assert(a.test(b) || b === c);
8: });
Value is not truthy:
false
a.test(b) || b === c
=> false
b === c
=> false
c
=> 'baz'
b
=> 'bar'
a.test(b)
=> false
b
=> 'bar'
a
=> /foo/
```

## Custom assertions

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

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

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

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

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

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

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).
Assert that `value` is deeply equal to `expected`. See [Concordance](https://github.com/concordancejs/concordance) for details.

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

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

`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.)
`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`.

Example:

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

`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.)
`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`.

Example:

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

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

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.

In AVA 3, you cannot update snapshots while using `t.snapshot.skip()`.

### `.try(title?, implementation | macro, ...args?)`

`.try()` allows you to *try* assertions without causing the test to fail.
Expand Down
25 changes: 2 additions & 23 deletions docs/04-snapshot-testing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,28 +2,7 @@

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

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:

```js
// Your component
const HelloWorld = () => <h1>Hello World...!</h1>;

export default HelloWorld;
```

```js
// Your test
const test = require('ava');
const render = require('react-test-renderer');
const HelloWorld = require('.');

test('HelloWorld component', t => {
const tree = render.create(<HelloWorld/>).toJSON();
t.snapshot(tree);
});
```

[Try it out in this example project.](https://github.com/avajs/ava-snapshot-example)
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.

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.

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

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.
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.

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

Expand Down
18 changes: 5 additions & 13 deletions docs/05-command-line.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ Options:
--help Show help [boolean]
--concurrency, -c Max number of test files running at the same time
(default: CPU cores) [number]
--no-worker-threads Don't use worker threads [boolean] (AVA 4 only)
--no-worker-threads Don't use worker threads [boolean]
--fail-fast Stop after first test failure [boolean]
--match, -m Only run tests with matching title (can be repeated)
[string]
Expand All @@ -40,7 +40,7 @@ Options:
--timeout, -T Set global timeout (milliseconds or human-readable,
e.g. 10s, 2m) [string]
--update-snapshots, -u Update snapshots [boolean]
--verbose, -v Enable verbose output (no-op in AVA 4) [boolean]
--verbose, -v Enable verbose output (default) [boolean]
--watch, -w Re-run tests when files change [boolean]

Examples:
Expand All @@ -49,8 +49,6 @@ Examples:
ava test.js:4,7-9
```

*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.*

AVA searches for test files using the following patterns:

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

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.

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`.
This feature is only available from the command line.

### Running a single test

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

## Resetting AVA's cache

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:
AVA maintains some temporary state. You can clear this state by running:

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

## Reporters

AVA 4 uses a human readable reporter:
AVA uses a human readable reporter by default:

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

AVA 3 defaults to a less verbose reporter:

<img src="../media/mini-reporter.gif" width="460">

Use the `--verbose` flag to enable the verbose reporter. This is always used in CI environments unless the [TAP reporter](#tap-reporter) is enabled.

### TAP reporter

[![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)
Expand Down
Loading

0 comments on commit f09742f

Please sign in to comment.