Skip to content

Commit

Permalink
Update documentation to reflect the removal of built-in Babel
Browse files Browse the repository at this point in the history
  • Loading branch information
@novemberborn
novemberborn committed Dec 24, 2019
1 parent 97a818d commit 29924f0
Show file tree
Hide file tree
Showing 13 changed files with 31 additions and 361 deletions.
1 change: 0 additions & 1 deletion contributing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,6 @@ The [`question` label](https://github.com/avajs/ava/labels/question) is a good p

You can use issue labels to discover issues you could help out with:

* [`babel` issues](https://github.com/avajs/ava/labels/babel) relate to our Babel infrastructure
* [`blocked` issues](https://github.com/avajs/ava/labels/blocked) need help getting unstuck
* [`bug` issues](https://github.com/avajs/ava/labels/bug) are known bugs we'd like to fix
* [`enhancement` issues](https://github.com/avajs/ava/labels/enhancement) are features we're open to including
Expand Down
2 changes: 1 addition & 1 deletion docs/01-writing-tests.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ AVA tries to run test files with their current working directory set to the dire

Each test file is run 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. It's also great for performance on modern multi-core processors, allowing multiple test files to execute in parallel.

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, or environment-specific Babel options). It may cause your code or its dependencies to behave differently though. Note that `'NODE_ENV' in process.env` will always be `true`.
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`.

## Declaring tests

Expand Down
8 changes: 7 additions & 1 deletion docs/05-command-line.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -133,7 +133,13 @@ test(function foo(t) {

## Resetting AVA's cache

AVA caches the compiled test and helper files. It automatically recompiles these files when you change them. AVA tries its best to detect changes to your Babel configuration files, plugins and presets. If it seems like your latest Babel configuration isn't being applied, however, you can run AVA with the `--reset-cache` flag to reset AVA's cache. If set, all files in the `node_modules/.cache/ava` directory are deleted. Run AVA as normal to apply your new Babel configuration.
AVA may cache certain files, especially when you use 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 reset the cache by running:

```console
npx ava reset-cache
```

This deletes all files in the `node_modules/.cache/ava` directory.

## Reporters

Expand Down
24 changes: 7 additions & 17 deletions docs/06-configuration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,25 +26,16 @@ To ignore files, prefix the pattern with an `!` (exclamation mark).
"*oo",
"!foo"
],
"cache": true,
"concurrency": 5,
"failFast": true,
"failWithoutAssertions": false,
"environmentVariables": {
"MY_ENVIRONMENT_VARIABLE": "some value"
},
"tap": true,
"verbose": true,
"compileEnhancements": false,
"require": [
"@babel/register"
],
"babel": {
"extensions": ["js", "jsx"],
"testOptions": {
"babelrc": false
}
}
"./my-helper-module.js"
]
}
}
```
Expand All @@ -53,8 +44,8 @@ Arguments passed to the CLI will always take precedence over the CLI options con

## Options

- `files`: an array of glob patterns to select test files. Files with an underscore prefix are ignored. By default only selects files with `js` extensions, even if the pattern matches other files. Specify `extensions` and `babel.extensions` to allow other file extensions
- `helpers`: an array of glob patterns to select helper files. Files matched here are never considered as tests. By default only selects files with `js` extensions, even if the pattern matches other files. Specify `extensions` and `babel.extensions` to allow other file extensions
- `files`: an array of glob patterns to select test files. Files with an underscore prefix are ignored. By default only selects files with `js` extensions, even if the pattern matches other files. Specify `extensions` to allow other file extensions
- `helpers`: an array of glob patterns to select helper files. Files matched here are never considered as tests. By default only selects files with `js` extensions, even if the pattern matches other files. Specify `extensions` to allow other file extensions
- `sources`: an array of glob patterns to match files that, when changed, cause tests to be re-run (when in watch mode). See the [watch mode recipe for details](https://github.com/avajs/ava/blob/master/docs/recipes/watch-mode.md#source-files-and-test-files)
- `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`: cache compiled test and helper files under `node_modules/.cache/ava`. If `false`, files are cached in a temporary directory instead
Expand All @@ -64,15 +55,14 @@ Arguments passed to the CLI will always take precedence over the CLI options con
- `tap`: if `true`, enables the [TAP reporter](./05-command-line.md#tap-reporter)
- `verbose`: if `true`, enables verbose output
- `snapshotDir`: specifies a fixed location for storing snapshot files. Use this if your snapshots are ending up in the wrong location
- `compileEnhancements`: if `false`, disables [`power-assert`](./03-assertions.md#enhanced-assertion-messages) — which otherwise helps provide more descriptive error messages — and detection of improper use of the `t.throws()` assertion
- `extensions`: extensions of test files that are not precompiled using AVA's Babel presets. Note that files are still compiled to enable `power-assert` and other features, so you may also need to set `compileEnhancements` to `false` if your files are not valid JavaScript. Setting this overrides the default `"js"` value, so make sure to include that extension in the list, as long as it's not included in `babel.extensions`
- `extensions`: extensions of test files. Setting this overrides the default `"js"` value, so make sure to include that extension in the list
- `require`: extra modules to require before tests are run. Modules are required in the [worker processes](./01-writing-tests.md#process-isolation)
- `babel`: test file specific Babel options. See our [Babel recipe](./recipes/babel.md#configuring-babel) for more details
- `babel.extensions`: extensions of test files that will be precompiled using AVA's Babel presets. Setting this overrides the default `"js"` value, so make sure to include that extension in the list
- `timeout`: Timeouts in AVA behave differently than in other test frameworks. AVA resets a timer after each test, forcing tests to quit if no new test results were received within the specified timeout. This can be used to handle stalled tests. See our [timeout documentation](./07-test-timeouts.md) for more options.

Note that providing files on the CLI overrides the `files` option.

Provide the `babel` option (and install [`@ava/babel`](https://github.com/avajs/babel) as an additional dependency) to enable Babel compilation.

## Using `ava.config.js`

To use an `ava.config.js` file:
Expand Down
8 changes: 0 additions & 8 deletions docs/08-common-pitfalls.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,6 @@ Translations: [Français](https://github.com/avajs/ava-docs/blob/master/fr_FR/do

If you use [ESLint](http://eslint.org/), you can install [eslint-plugin-ava](https://github.com/avajs/eslint-plugin-ava). It will help you use AVA correctly and avoid some common pitfalls.

## Transpiling imported modules

AVA currently only transpiles test and helper files. *It will not transpile modules you `import` from outside of the test.* This may be unexpected but there are workarounds.

If you use Babel you can use its [require hook](https://babeljs.io/docs/usage/require/) to transpile imported modules on-the-fly. To add it, [configure it in your `package.json`](./06-configuration.md).

You can also transpile your modules in a separate process and refer to the transpiled files rather than the sources from your tests.

## AVA in Docker

If you run AVA in Docker as part of your CI, you need to fix the appropriate environment variables. Specifically, adding `-e CI=true` in the `docker exec` command. See [#751](https://github.com/avajs/ava/issues/751).
Expand Down
275 changes: 4 additions & 271 deletions docs/recipes/babel.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,285 +2,18 @@

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

AVA uses [Babel 7](https://babeljs.io) so you can use the latest JavaScript syntax in your tests. We do this by compiling test and helper files using our [`@ava/stage-4`](https://github.com/avajs/babel-preset-stage-4) preset. We also use a [second preset, `@ava/transform-test-files`](https://github.com/avajs/babel-preset-transform-test-files) to enable [enhanced assertion messages](../03-assertions.md#enhanced-assertion-messages) and detect improper use of `t.throws()` assertions.
**The upcoming AVA 3 release removes built-in Babel support. See the [AVA 2](https://github.com/avajs/ava/blob/v2.4.0/docs/recipes/babel.md) documentation instead.**

By default our Babel pipeline is applied to test and helper files ending in `.js`. If your project uses Babel then we'll automatically compile these files using your project's Babel configuration. The `@ava/transform-helper-files` preset is applied first, and the `@ava/stage-4` last.

If you are using Babel for your source files then you must also [configure source compilation](#compile-sources).

## Customize how AVA compiles your test files

You can override the default Babel configuration AVA uses for test file compilation in `package.json` or `ava.config.js`. For example, the configuration below adds support for JSX syntax and stage 3 features.

**`package.json`:**

```json
{
"ava": {
"babel": {
"testOptions": {
"plugins": ["@babel/plugin-syntax-jsx"],
"presets": ["@babel/preset-stage-3"]
}
}
}
}
```

All [Babel options] are allowed inside the `testOptions` object.

## Reset AVA's cache

AVA caches the compiled test and helper files. It automatically recompiles these files when you change them. AVA tries its best to detect changes to your Babel configuration files, plugins and presets. If it seems like your latest Babel configuration isn't being applied, however, you can reset AVA's cache:

```console
$ npx ava --reset-cache
```

## Add additional extensions

You can configure AVA to recognize additional file extensions and compile those test & helper files using Babel.

**`package.json`:**

```json
{
"ava": {
"babel": {
"extensions": [
"js",
"jsx"
]
}
}
}
```

See also AVA's [`extensions` option](../06-configuration.md#options).

## Make AVA skip your project's Babel options

You may not want AVA to use your project's Babel options, for example if your project is relying on Babel 6. Set the `babelrc` and `configFile` options to `false`.

**`package.json`:**

```json
{
"ava": {
"babel": {
"testOptions": {
"babelrc": false,
"configFile": false
}
}
}
}
```

## Disable AVA's stage-4 preset

You can disable AVA's stage-4 preset.

**`package.json`:**

```json
{
"ava": {
"babel": {
"testOptions": {
"presets": [
["module:ava/stage-4", false]
]
}
}
}
}
```

Note that this *does not* stop AVA from compiling your test files using Babel.

If you want, you can disable the preset in your project's Babel configuration.

## Preserve ES module syntax

By default AVA's stage-4 preset will convert ES module syntax to CommonJS. This can be disabled.

**`package.json`:**

```json
{
"ava": {
"babel": {
"testOptions": {
"presets": [
["module:ava/stage-4", {"modules": false}]
]
}
}
}
}
```

You'll have to use the [`esm`](https://github.com/standard-things/esm) module so that AVA can still load your test files. [See our recipe for details](./es-modules.md).

## Disable AVA's Babel pipeline

You can completely disable AVA's use of Babel.

**`package.json`:**

```json
{
"ava": {
"babel": false,
"compileEnhancements": false
}
}
```

## Experimental feature: No Babel out of the box

A future release of AVA will not use Babel out of the box. You can opt in to this feature. **This feature may change or be removed at any time**:

**`package.json`:**

```js
{
"ava": {
"nonSemVerExperiments": {
"noBabelOutOfTheBox": true
}
}
}
```

This disables AVA's Babel pipeline, though you can still enable it by configuring it as described above.

`compileEnhancements` can no longer be configured on the top-level AVA configuration. It must be configured in AVA's `babel` configuration instead. It defaults to `true`.

**`package.json`:**

```json
{
"ava": {
"nonSemVerExperiments": {
"noBabelOutOfTheBox": true
},
"babel": {
"compileEnhancements": false
}
}
}
```

You can disable the non-enhancement compilation of your test files by setting `testOptions` to `false`.

```json
{
"ava": {
"nonSemVerExperiments": {
"noBabelOutOfTheBox": true
},
"babel": {
"testOptions": false
}
}
}
```

## Use Babel polyfills

AVA lets you write your tests using new JavaScript syntax, even on Node.js versions that otherwise wouldn't support it. However, it doesn't add or modify built-ins of your current environment. Using AVA would, for example, not provide modern features such as `Object.entries()` to an underlying Node.js 6 environment.

By loading [Babel's `polyfill` module](https://babeljs.io/docs/usage/polyfill/) you can opt in to these features. Note that this will modify the environment, which may influence how your program behaves.

You can enable the `polyfill` module by adding it to AVA's `require` option.

**`package.json`:**

```json
{
"ava": {
"require": [
"@babel/polyfill"
]
}
}
```

You'll need to install `@babel/polyfill` yourself.

## Compile sources

AVA does not currently compile source files. You'll have to load [Babel's `register` module](http://babeljs.io/docs/usage/require/), which will compile source files as needed.

You can enable the `register` module by adding it to AVA's `require` option.
You can enable Babel support by installing `@ava/babel`, and then in AVA's configuration setting `babel` to `true`:

**`package.json`:**

```json
{
"ava": {
"require": [
"@babel/register"
]
}
}
```

You'll need to install `@babel/register` yourself.

`@babel/register` will *also* process your test and helper files. For most use cases this is unnecessary. If you create a new file that requires `@babel/register` you can tell it which file paths to ignore. For instance in your `test` directory create `_register.js`:

```js
// test/_register.js:
require('@babel/register')({
// These patterns are relative to the project directory (where the `package.json` file lives):
ignore: ['node_modules/*', 'test/*']
});
```

Now instead of requiring `@babel/register`, require `./test/_register` instead.

**`package.json`:**

```json
{
"ava": {
"require": [
"./test/_register.js"
]
}
}
```

Note that loading `@babel/register` in every worker process has a non-trivial performance cost. If you have lots of test files, you may want to consider using a build step to compile your sources *before* running your tests. This isn't ideal, since it complicates using AVA's watch mode, so we recommend using `@babel/register` until the performance penalty becomes too great. Setting up a precompilation step is out of scope for this document, but we recommend you check out one of the many [build systems that support Babel](http://babeljs.io/docs/setup/). There is an [issue](https://github.com/avajs/ava/issues/577) discussing ways we could make this experience better.

## Webpack aliases

[Webpack aliases](https://webpack.js.org/configuration/resolve/#resolve-alias) can be used to provide a shortcut to deeply nested or otherwise inconvenient paths. If you already use aliases in your source files, you'll need to make sure you can use the same aliases in your test files.

Install `babel-plugin-webpack-alias-7` as a dev-dependency. Then add the plugin to AVA's Babel config:

`package.json`:

```json
{
"ava": {
"babel": {
"testOptions": {
"plugins": [
[
"babel-plugin-webpack-alias-7",
{
"config": "./path/to/webpack.config.test.js"
}
]
]
}
}
"babel": true
}
}
```

[Babel options]: https://babeljs.io/docs/en/options
Find out more in [`@ava/babel`](https://github.com/avajs/babel).
Loading

0 comments on commit 29924f0

Please sign in to comment.