diff --git a/docs/01-writing-tests.md b/docs/01-writing-tests.md index 7d1a90698..69726f31d 100644 --- a/docs/01-writing-tests.md +++ b/docs/01-writing-tests.md @@ -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`. @@ -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: @@ -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. @@ -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. @@ -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'); @@ -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) { @@ -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'; @@ -344,7 +307,7 @@ const macro = test.macro({ }, title(providedTitle = '', input, expected) { return `${providedTitle} ${input} = ${expected}`.trim(); - } + }, }); test(macro, '2 + 2', 4); @@ -352,4 +315,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. diff --git a/docs/02-execution-context.md b/docs/02-execution-context.md index 834e130d0..5b7937955 100644 --- a/docs/02-execution-context.md +++ b/docs/02-execution-context.md @@ -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. @@ -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.†. 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. -† 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. diff --git a/docs/03-assertions.md b/docs/03-assertions.md index d3ae195ae..a1e3393ca 100644 --- a/docs/03-assertions.md +++ b/docs/03-assertions.md @@ -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. @@ -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?)` @@ -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?)` @@ -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: @@ -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: @@ -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. diff --git a/docs/04-snapshot-testing.md b/docs/04-snapshot-testing.md index ca6fc979b..3ddd42db9 100644 --- a/docs/04-snapshot-testing.md +++ b/docs/04-snapshot-testing.md @@ -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 = () =>

Hello World...!

; - -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().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. @@ -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): diff --git a/docs/05-command-line.md b/docs/05-command-line.md index aa2c0044e..49743ff3d 100644 --- a/docs/05-command-line.md +++ b/docs/05-command-line.md @@ -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] @@ -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: @@ -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` @@ -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 @@ -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 @@ -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: -AVA 3 defaults to a less 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. - ### 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) diff --git a/docs/06-configuration.md b/docs/06-configuration.md index fa5a5ed86..6140ddec3 100644 --- a/docs/06-configuration.md +++ b/docs/06-configuration.md @@ -47,12 +47,12 @@ Arguments passed to the CLI will always take precedence over the CLI options con - `match`: not typically useful in the `package.json` configuration, but equivalent to [specifying `--match` on the CLI](./05-command-line.md#running-tests-with-matching-titles) - `cache`: defaults to `true` to cache compiled files under `node_modules/.cache/ava`. If `false`, files are cached in a temporary directory instead - `concurrency`: max number of test files running at the same time (default: CPU cores) -- `workerThreads`: use worker threads to run tests (requires AVA 4, enabled by default). If `false`, tests will run in child processes (how AVA 3 behaves) +- `workerThreads`: use worker threads to run tests (enabled by default). If `false`, tests will run in child processes - `failFast`: stop running further tests once a test fails - `failWithoutAssertions`: if `false`, does not fail a test if it doesn't run [assertions](./03-assertions.md) - `environmentVariables`: specifies environment variables to be made available to the tests. The environment variables defined here override the ones from `process.env` - `tap`: if `true`, enables the [TAP reporter](./05-command-line.md#tap-reporter) -- `verbose`: if `true`, enables verbose output (no-op in AVA 4) +- `verbose`: if `true`, enables verbose output (though there currently non-verbose output is not supported) - `snapshotDir`: specifies a fixed location for storing snapshot files. Use this if your snapshots are ending up in the wrong location - `extensions`: extensions of test files. Setting this overrides the default `["cjs", "mjs", "js"]` value, so make sure to include those extensions in the list. [Experimentally you can configure how files are loaded](#configuring-module-formats) - `require`: extra modules to require before tests are run. Modules are required in the [worker processes](./01-writing-tests.md#process-isolation) @@ -61,31 +61,24 @@ Arguments passed to the CLI will always take precedence over the CLI options con Note that providing files on the CLI overrides the `files` option. -When using AVA 3, provide the `babel` option (and install [`@ava/babel`](https://github.com/avajs/babel) as an additional dependency) to enable Babel compilation. - Provide the `typescript` option (and install [`@ava/typescript`](https://github.com/avajs/typescript) as an additional dependency) for AVA to run tests written in TypeScript. ## Using `ava.config.*` files Rather than specifying the configuration in the `package.json` file you can use `ava.config.js`, `ava.config.cjs` or `ava.config.mjs` files. -Note: AVA 3 recognizes `ava.config.mjs` files but refuses to load them. They work in AVA 4. - To use these files: 1. Your `package.json` must not contain an `ava` property (or, if it does, it must be an empty object) 2. You must only have one `ava.config.*` file in any directory, so don't mix `ava.config.js` *and* `ava.config.cjs` files -3. AVA 3 requires these files be in the same directory as your `package.json` file -AVA 4 searches your file system for `ava.config.*` files. First, when you run AVA, it finds the closest `package.json`. Starting in that directory it recursively checks the parent directories until it either reaches the file system root or encounters a `.git` file or directory. The first `ava.config.*` file found is selected. This allows you to use a single configuration file in a monorepo setup. +AVA searches your file system for `ava.config.*` files. First, when you run AVA, it finds the closest `package.json`. Starting in that directory it recursively checks the parent directories until it either reaches the file system root or encounters a `.git` file or directory. The first `ava.config.*` file found is selected. This allows you to use a single configuration file in a monorepo setup. ### `ava.config.js` -AVA 4 follows Node.js' behavior, so if you've set `"type": "module"` you must use ESM, and otherwise you must use CommonJS. +AVA follows Node.js' behavior, so if you've set `"type": "module"` you must use ESM, and otherwise you must use CommonJS. -In AVA 3, for `ava.config.js` files you must use `export default`. You cannot use ["module scope"](https://nodejs.org/docs/latest-v12.x/api/modules.html#modules_the_module_scope). You cannot import dependencies. - -The default export can either be a plain object or a factory function which returns a plain object. Starting in AVA 4 you can export or return a promise for a plain object: +The default export can either be a plain object or a factory function which returns a plain object. You can export or return a promise for a plain object: ```js export default { @@ -121,7 +114,7 @@ export default ({projectDir}) => { For `ava.config.cjs` files you must assign `module.exports`. ["Module scope"](https://nodejs.org/docs/latest-v12.x/api/modules.html#modules_the_module_scope) is available. You can `require()` dependencies. -The module export can either be a plain object or a factory function which returns a plain object. Starting in AVA 4 you can export or return a promise for a plain object: +The module export can either be a plain object or a factory function which returns a plain object. You can export or return a promise for a plain object: ```js module.exports = { @@ -155,8 +148,6 @@ module.exports = ({projectDir}) => { ### `ava.config.mjs` -Note that `ava.config.mjs` files are only supported in AVA 4. - The default export can either be a plain object or a factory function which returns a plain object. You can export or return a promise for a plain object: ```js @@ -195,8 +186,6 @@ The [CLI] lets you specify a specific configuration file, using the `--config` f When the `--config` flag is set, the provided file will override all configuration from the `package.json` and `ava.config.js`, `ava.config.cjs` or `ava.config.mjs` files. The configuration is not merged. -Note: In AVA 3 the configuration file *must* be in the same directory as the `package.json` file. This restriction does not apply to AVA 4. - You can use this to customize configuration for a specific test run. For instance, you may want to run unit tests separately from integration tests: `ava.config.cjs`: @@ -255,10 +244,6 @@ export default { Node.js can only load non-standard extension as ES Modules when using [experimental loaders](https://nodejs.org/docs/latest/api/esm.html#esm_experimental_loaders). To use this you'll also have to configure AVA to `import()` your test file. -This is an experimental feature in AVA 3. You can opt in to it by enabling the `configurableModuleFormat` experiment. Afterwards, you'll be able to specify per-extension module formats using an object form. - -This feature is available by default in AVA 4. - As with the array form, you need to explicitly list `js`, `cjs`, and `mjs` extensions. These **must** be set using the `true` value; other extensions are configurable using either `'commonjs'` or `'module'`: `ava.config.js`: diff --git a/docs/08-common-pitfalls.md b/docs/08-common-pitfalls.md index fb32ce765..d38be3651 100644 --- a/docs/08-common-pitfalls.md +++ b/docs/08-common-pitfalls.md @@ -54,20 +54,6 @@ test('fetches foo', async t => { AVA [can't trace uncaught exceptions](https://github.com/avajs/ava/issues/214) back to the test that triggered them. Callback-taking functions may lead to uncaught exceptions that can then be hard to debug. Consider promisifying and using `async`/`await`, as in the above example. This should allow AVA to catch the exception and attribute it to the correct test. -## Why are the enhanced assertion messages not shown? - -Enhanced assertion messages are no longer supported in AVA 4. - -Ensure that the first parameter passed into your test is named `t`. This is a requirement of [`power-assert`](https://github.com/power-assert-js/power-assert), the library that provides the [enhanced messages](./03-assertions.md#enhanced-assertion-messages). - -```js -test('one is one', t => { - t.assert(1 === 1); -}); -``` - -Also make sure to enable [Babel](./recipes/babel.md). - ## Sharing variables between asynchronous tests By default AVA executes tests concurrently. This can cause problems if your tests are asynchronous and share variables. diff --git a/docs/recipes/babel.md b/docs/recipes/babel.md index 1b649febd..32f6da8b1 100644 --- a/docs/recipes/babel.md +++ b/docs/recipes/babel.md @@ -1,8 +1,8 @@ -# Configuring Babel +# Configuring Babel with AVA 3 Translations: [Français](https://github.com/avajs/ava-docs/blob/master/fr_FR/docs/recipes/babel.md) -This is no longer available in AVA 4. +**This is no longer available in AVA 4.** You can enable Babel support by installing `@ava/babel`, and then in AVA's configuration setting `babel` to `true`: diff --git a/docs/recipes/es-modules.md b/docs/recipes/es-modules.md index 35efe952c..6358063bb 100644 --- a/docs/recipes/es-modules.md +++ b/docs/recipes/es-modules.md @@ -1,54 +1,3 @@ # Using ES modules in AVA -Translations: [Français](https://github.com/avajs/ava-docs/blob/master/fr_FR/docs/recipes/es-modules.md) - -As of Node.js 12.17, [ECMAScript Modules](https://nodejs.org/docs/latest/api/esm.html#esm_introduction) are natively supported in Node.js itself. AVA 3.3 supports ESM test files, however support is incomplete. The [ESM support project](https://github.com/orgs/avajs/projects/2) tracks our progress. - -If you use TypeScript with `ts-node` please [see our Typescript recipe for setup instructions](./typescript.md). - -## Using the `esm` package - -If you're using Node.js 10 and AVA 3 and you want to use the ESM syntax, without relying on Node.js' implementation, your best bet is to use the [`esm`](https://github.com/standard-things/esm) package. Make sure to use the `.js` extension and *do not* set `"type": "module"` in `package.json`. - -*Note: The `esm` package is no longer supported in AVA 4.* - -Here's how you get it working with AVA. - -First, install `esm`: - -``` -$ npm install esm -``` - -Configure it in your `package.json` or `ava.config.*` file, and add it to AVA's `"require"` option as well. Make sure to add it as the first item. - -**`package.json`:** - -```json -{ - "ava": { - "require": [ - "esm" - ] - } -} -``` - -You can now use native ES modules with AVA: - -```js -// sum.js -export default function sum(a, b) { - return a + b; -}; -``` - -```js -// test.js -import test from 'ava'; -import sum from './sum'; - -test('2 + 2 = 4', t => { - t.is(sum(2, 2), 4); -}); -``` +AVA 4 supports ES modules out of the box. diff --git a/docs/recipes/react.md b/docs/recipes/react.md index 0208e7f7b..d7a8ee80e 100644 --- a/docs/recipes/react.md +++ b/docs/recipes/react.md @@ -1,7 +1,9 @@ -# Testing React components +# Testing React components with AVA 3 Translations: [Español](https://github.com/avajs/ava-docs/blob/master/es_ES/docs/recipes/react.md), [Français](https://github.com/avajs/ava-docs/blob/master/fr_FR/docs/recipes/react.md) +**AVA 4 no longer has built-in Babel support, and `t.snapshot()` and `t.deepEqual()` no longer recognize React elements either. Therefore this recipe is mostly relevant for AVA 3 users.** + ## Setting up Babel When you [enable Babel](https://github.com/avajs/babel), AVA 3 will automatically extend your regular (project-level) Babel configuration. You should be able to use React in your test files without any additional configuration. diff --git a/docs/recipes/shared-workers.md b/docs/recipes/shared-workers.md index 34e36c96a..976891459 100644 --- a/docs/recipes/shared-workers.md +++ b/docs/recipes/shared-workers.md @@ -4,20 +4,6 @@ Shared workers are a powerful AVA feature. A program can be loaded in a [worker When you use watch mode, shared workers remain loaded across runs. -## Enabling the experiment (only needed with AVA 3) - -Shared workers are available when you use AVA with Node.js 12.17.0 or newer. AVA 3.13.0 or newer is required. It is an experimental feature so you need to enable it in your AVA configuration: - -`ava.config.js`: - -```js -export default { - nonSemVerExperiments: { - sharedWorkers: true - } -}; -``` - ## Available plugins * [`@ava/get-port`](https://github.com/avajs/get-port) works like [`get-port`](https://github.com/sindresorhus/get-port), but ensures the port is locked across all test files. @@ -37,8 +23,6 @@ Plugins communicate with their shared worker using a *protocol*. Protocols are v Plugins can be compatible with multiple protocols. AVA will select the best protocol it supports. If AVA does not support any of the specified protocols it'll throw an error. The selected protocol is available on the returned worker object. -**For AVA 3, substitute `'ava-4'` with `'experimental'`.** - ```js import {registerSharedWorker} from 'ava/plugin'; diff --git a/docs/recipes/typescript.md b/docs/recipes/typescript.md index ae24594be..cc054d5aa 100644 --- a/docs/recipes/typescript.md +++ b/docs/recipes/typescript.md @@ -4,7 +4,7 @@ Translations: [Español](https://github.com/avajs/ava-docs/blob/master/es_ES/doc AVA comes bundled with a TypeScript definition file. This allows developers to leverage TypeScript for writing tests. -This guide assumes you've already set up TypeScript for your project. Note that AVA 3's definition expects at least version 3.7.5. AVA 4 will require at least version 4.4. +This guide assumes you've already set up TypeScript for your project. Note that AVA's definition expects at least version 4.4. ## Enabling AVA's support for TypeScript test files @@ -111,39 +111,7 @@ const hasLength = (t: ExecutionContext, input: string, expected: number) => { test('bar has length 3', hasLength, 'bar', 3); ``` -### AVA 3 - -With AVA 3, in order to be able to assign the `title` property to a macro you need to type the function: - -```ts -import test, {Macro} from 'ava'; - -const macro: Macro<[string, number]> = (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); -``` - -You'll need a different type if you're expecting your macro to be used with an AVA 3 callback test: - -```ts -import test, {CbMacro} from 'ava'; - -const macro: CbMacro<[]> = t => { - t.pass(); - setTimeout(t.end, 100); -}; - -test.cb(macro); -``` - -### AVA 4 - -With AVA 4 you can use the `test.macro()` helper to create macros: +However if you use the `test.macro()` helper you get much better type inference: ```ts import test from 'ava'; @@ -178,13 +146,12 @@ test('providedTitle', macro, '3 * 3', 9); [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/avajs/ava/tree/main/examples/typescript-context?file=source%2Ftest.ts&terminal=test&view=editor) -By default, the type of `t.context` will be the empty object (`{}`). AVA exposes an interface `TestInterface` (in AVA 4 this is `TestFn`) which you can use to apply your own type to `t.context`. This can help you catch errors at compile-time: +By default, the type of `t.context` will be the empty object (`{}`). AVA exposes an interface `TestFn` which you can use to apply your own type to `t.context`. This can help you catch errors at compile-time: ```ts -import anyTest, {TestInterface} from 'ava'; // AVA 3 -// import anyTest, {TestFn as TestInterface} from 'ava'; // AVA 4, usage is the same +import anyTest, {TestFn} from 'ava'; -const test = anyTest as TestInterface<{foo: string}>; +const test = anyTest as TestFn<{foo: string}>; test.beforeEach(t => { t.context = {foo: 'bar'}; @@ -203,28 +170,6 @@ test('an actual test', t => { }); ``` -You can also type the context when creating macros: - -```ts -import anyTest, {Macro, TestInterface} from 'ava'; // AVA 3 - -interface Context { - foo: string -} - -const test = anyTest as TestInterface; - -const macro: Macro<[string], Context> = (t, expected: string) => { - t.is(t.context.foo, expected); -}; - -test.beforeEach(t => { - t.context = {foo: 'bar'}; -}); - -test('foo is bar', macro, 'bar'); -``` - Note that, despite the type cast above, when executing `t.context` is an empty object unless it's assigned. ## Typing `throws` assertions diff --git a/docs/recipes/vue.md b/docs/recipes/vue.md index 6275a6611..7c23c97ad 100644 --- a/docs/recipes/vue.md +++ b/docs/recipes/vue.md @@ -53,8 +53,6 @@ hooks(['vue', 'js']).exclude(({filename}) => filename.match(/\/node_modules\//)) **Note:** If you are using _babel-plugin-webpack-alias-7_, you must also exclude your webpack file - e.g. `filename.includes(/\/node_modules\//) || filename.includes('webpack.config.test.js')` -You can find more information about setting up Babel with AVA 3 in [`@ava/babel`](https://github.com/avajs/babel). - ## Sample snapshot test ```js diff --git a/lib/cli.js b/lib/cli.js index a80d4b1a4..3f9974732 100644 --- a/lib/cli.js +++ b/lib/cli.js @@ -87,7 +87,7 @@ const FLAGS = { verbose: { alias: 'v', coerce: coerceLastValue, - description: 'Enable verbose output (no-op)', + description: 'Enable verbose output (default)', type: 'boolean', }, watch: { diff --git a/media/magic-assert-objects.png b/media/magic-assert-objects.png deleted file mode 100644 index c57d2d17e..000000000 Binary files a/media/magic-assert-objects.png and /dev/null differ diff --git a/media/magic-assert-strings.png b/media/magic-assert-strings.png deleted file mode 100644 index fad67b7a2..000000000 Binary files a/media/magic-assert-strings.png and /dev/null differ diff --git a/media/mini-reporter.gif b/media/mini-reporter.gif deleted file mode 100644 index 27fb20a68..000000000 Binary files a/media/mini-reporter.gif and /dev/null differ diff --git a/media/power-assert.png b/media/power-assert.png deleted file mode 100644 index b6b119ff4..000000000 Binary files a/media/power-assert.png and /dev/null differ diff --git a/readme.md b/readme.md index 882ad882d..682315ce0 100644 --- a/readme.md +++ b/readme.md @@ -6,7 +6,7 @@ Follow the [AVA Twitter account](https://twitter.com/ava__js) for updates. Read our [contributing guide](.github/CONTRIBUTING.md) if you're looking to contribute (issues / PRs / etc). -![](media/mini-reporter.gif) +![](media/verbose-reporter.png) 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) @@ -147,9 +147,7 @@ We have a growing list of [common pitfalls](docs/08-common-pitfalls.md) you may - [When to use `t.plan()`](docs/recipes/when-to-use-plan.md) - [Browser testing](docs/recipes/browser-testing.md) - [TypeScript](docs/recipes/typescript.md) -- [Using ES modules](docs/recipes/es-modules.md) - [Passing arguments to your test files](docs/recipes/passing-arguments-to-your-test-files.md) -- [Testing React components](docs/recipes/react.md) - [Testing Vue.js components](docs/recipes/vue.md) - [Debugging tests with Chrome DevTools](docs/recipes/debugging-with-chrome-devtools.md) - [Debugging tests with VSCode](docs/recipes/debugging-with-vscode.md) @@ -188,7 +186,6 @@ It's the [Andromeda galaxy](https://simple.wikipedia.org/wiki/Andromeda_galaxy). - [eslint-plugin-ava](https://github.com/avajs/eslint-plugin-ava) — Lint rules for AVA tests - [@ava/typescript](https://github.com/avajs/typescript) — Test TypeScript projects -- [@ava/babel](https://github.com/avajs/babel) — Compile test files using Babel, for AVA 3 - [@ava/cooperate](https://github.com/avajs/cooperate) — Low-level primitives to enable cooperation between test files - [@ava/get-port](https://github.com/avajs/get-port) — Reserve a port while testing diff --git a/test-d/macros.ts b/test-d/macros.ts index 28e92a860..9f2404329 100644 --- a/test-d/macros.ts +++ b/test-d/macros.ts @@ -82,6 +82,15 @@ import test, {ExecutionContext} from '..'; test(pass); } +// Without test.macro() +{ + const hasLength = (t: ExecutionContext, input: string, expected: number) => { + t.is(input.length, expected); + }; + + test('bar has length 3', hasLength, 'bar', 3); +} + // Inline function with explicit argument types. test('has length 3', (t: ExecutionContext, input: string, expected: number) => {}, 'bar', 3);