Skip to content

Commit e253da4

Browse files
novemberbornnovemberborn
committed
Update documentation
1 parent 400bdf7 commit e253da4

10 files changed

+143
-203
lines changed

‎docs/recipes/babel.md

+102
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# Configuring Babel
2+
3+
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](https://github.com/avajs/babel-preset-transform-test-files) to enable [enhanced assertion messages](../../readme#enhanced-assertion-messages) and detect improper use of `t.throws()` assertions.
4+
5+
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 files using your project's Babel configuration.
6+
7+
AVA only looks for Babel configuration files in your project directory. That is, `.babelrc` or `.babelrc.js` files next to your `package.json` file, or the `package.json` file itself.
8+
9+
## Customize how AVA compiles your test files
10+
11+
You can override the default Babel configuration AVA uses for test file compilation in `package.json`. For example, the configuration below adds support for JSX syntax and stage 3 features:
12+
13+
```json
14+
{
15+
"ava": {
16+
"babel": {
17+
"testOptions": {
18+
"plugins": ["@babel/plugin-syntax-jsx"],
19+
"presets": ["@babel/preset-stage-3"]
20+
}
21+
}
22+
}
23+
}
24+
```
25+
26+
All `.babelrc` options are allowed inside the `testOptions` object.
27+
28+
## Make AVA skip your project's Babel options
29+
30+
You may not want AVA to use your project's Babel options, for example if your project is relying on Babel 6. You can set the `babelrc` option to `false`:
31+
32+
```json
33+
{
34+
"ava": {
35+
"babel": {
36+
"testOptions": {
37+
"babelrc": false
38+
}
39+
}
40+
}
41+
}
42+
```
43+
44+
## Disable AVA's stage-4 preset
45+
46+
You can disable AVA's stage-4 preset:
47+
48+
```json
49+
{
50+
"ava": {
51+
"babel": {
52+
"testOptions": {
53+
"presets": [
54+
["module:ava/stage-4", false]
55+
]
56+
}
57+
}
58+
}
59+
}
60+
```
61+
62+
Note that this *does not* stop AVA from compiling your test files using Babel.
63+
64+
## Use Babel polyfills
65+
66+
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.
67+
68+
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.
69+
70+
You can enable the `polyfill` module by adding it to AVA's `require` option:
71+
72+
```json
73+
{
74+
"ava": {
75+
"require": [
76+
"@babel/polyfill"
77+
]
78+
}
79+
}
80+
```
81+
82+
You'll need to install `@babel/polyfill` yourself.
83+
84+
## Compile sources
85+
86+
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.
87+
88+
You can enable the `register` module by adding it to AVA's `require` option:
89+
90+
```json
91+
{
92+
"ava": {
93+
"require": [
94+
"@babel/register"
95+
]
96+
}
97+
}
98+
```
99+
100+
You'll need to install `@babel/register` yourself.
101+
102+
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.

‎docs/recipes/babelrc.md

+3-145
Original file line numberDiff line numberDiff line change
@@ -2,150 +2,8 @@
22

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

5-
There are multiple options for configuring how AVA transpiles your tests using Babel.
5+
This recipe has moved. Please see our [new Babel recipe](babel.md).
66

7-
- [AVA's default transpiler behavior](#avas-default-transpiler-behavior)
8-
- [Customizing how AVA transpiles your tests](#customizing-how-ava-transpiles-your-tests)
9-
- [Transpiling Sources](#transpiling-sources)
10-
- [Transpiling tests and sources the same way](#transpiling-tests-and-sources-the-same-way)
11-
- [Extend your source transpilation configuration](#extend-your-source-transpilation-configuration)
12-
- [Extend an alternate config file (i.e. not `.babelrc`)](#extend-an-alternate-config-file)
7+
---
138

14-
## AVA's default transpiler behavior
15-
16-
AVA lets you use some nifty JavaScript features, like [async functions](https://github.com/avajs/ava#async-function-support). To make this work on older Node.js versions AVA transpiles the tests and helper files using the [`@ava/stage-4`](https://github.com/avajs/babel-preset-stage-4) Babel preset. This is great for projects where you do not use Babel for your source, but do want to use the newest JavaScript features for your tests.
17-
18-
### Using object rest/spread properties
19-
20-
As of Node.js [8.3.0](https://github.com/nodejs/node/blob/v8.3.0/doc/changelogs/CHANGELOG_V8.md#8.3.0) [object rest/spread properties](https://github.com/tc39/proposal-object-rest-spread) is supported directly. This new language feature however has not yet reached [stage 4](http://2ality.com/2015/11/tc39-process.html#stage-4-finished), which means that AVA won't support it by default. That said, if you're using Node.js 8.3.0 or newer, AVA will load the [`syntax-object-rest-spread`](https://www.npmjs.com/package/babel-plugin-syntax-object-rest-spread) plugin for you. This means you *can* use object rest/spread properties in your tests as long as you're not targeting older Node.js versions.
21-
22-
Note that if you customize the Babel configuration you'll have to explicitly specify the `syntax-object-rest-spread` plugin.
23-
24-
## Customizing how AVA transpiles your tests
25-
26-
You can override the default Babel configuration AVA uses for test transpilation in `package.json`. For example, the configuration below adds the Babel `rewire` plugin, and adds the Babel [`stage-3`](http://babeljs.io/docs/plugins/preset-stage-3/) preset.
27-
28-
```json
29-
{
30-
"ava": {
31-
"babel": {
32-
"plugins": ["rewire"],
33-
"presets": ["@ava/stage-4", "stage-3"]
34-
}
35-
}
36-
}
37-
```
38-
39-
Note that this only affects how AVA transpiles your tests. If you use `babel-register` you'll still need to add separate Babel configuration as explained [here](#transpiling-sources).
40-
41-
## Use Babel Polyfills
42-
43-
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 `Array.prototype.includes()` to an underlying Node.js 4 environment.
44-
45-
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.
46-
47-
You can enable `babel-polyfill` by adding it to AVA's `require` option:
48-
49-
```json
50-
{
51-
"ava": {
52-
"require": [
53-
"babel-polyfill"
54-
]
55-
}
56-
}
57-
```
58-
59-
## Transpiling Sources
60-
61-
To transpile your sources, you will need to define a [`babel config` ](http://babeljs.io/docs/usage/babelrc/) in `package.json` or a `.babelrc` file. Also, you will need to tell AVA to load [`babel-register`](http://babeljs.io/docs/usage/require/) in every forked process, by adding it to the `require` section of your AVA config:
62-
63-
`package.json`
64-
65-
```json
66-
{
67-
"ava": {
68-
"require": ["babel-register"]
69-
},
70-
"babel": {
71-
"presets": ["@ava/stage-4"]
72-
}
73-
}
74-
```
75-
76-
Note that loading `babel-register` in every forked process has a non-trivial performance cost. If you have lots of test files, you may want to consider using a build step to transpile 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 [open issue](https://github.com/avajs/ava/issues/577) discussing ways we could make this experience better.
77-
78-
## Transpiling tests and sources the same way
79-
80-
Using the `"inherit"` shortcut will cause your tests to be transpiled the same as your sources (as specified in your [`babelrc`](http://babeljs.io/docs/usage/babelrc/)). AVA will add a few additional [internal plugins](#notes) when transpiling your tests, but they won't affect the behavior of your test code.
81-
82-
`package.json`:
83-
84-
```json
85-
{
86-
"ava": {
87-
"require": "babel-register",
88-
"babel": "inherit"
89-
},
90-
"babel": {
91-
"presets": [
92-
"@ava/stage-4",
93-
"react"
94-
]
95-
}
96-
}
97-
```
98-
99-
In the above example, both tests and sources will be transpiled using the [`@ava/stage-4`](https://github.com/avajs/babel-preset-stage-4) and [`react`](http://babeljs.io/docs/plugins/preset-react/) presets.
100-
101-
AVA will only look for a `.babelrc` file in the same directory as the `package.json` file. If not found then it assumes your Babel config lives in the `package.json` file.
102-
103-
## Extend your source transpilation configuration
104-
105-
When specifying the Babel config for your tests, you can set the `babelrc` option to `true`. This will merge the specified plugins with those from your [`babelrc`](http://babeljs.io/docs/usage/babelrc/).
106-
107-
`package.json`:
108-
109-
```json
110-
{
111-
"ava": {
112-
"require": "babel-register",
113-
"babel": {
114-
"babelrc": true,
115-
"plugins": ["custom-plugin-name"],
116-
"presets": ["custom-preset"]
117-
}
118-
},
119-
"babel": {
120-
"presets": [
121-
"@ava/stage-4",
122-
"react"
123-
]
124-
}
125-
}
126-
```
127-
128-
In the above example, *sources* are compiled use [`@ava/stage-4`](https://github.com/avajs/babel-preset-stage-4) and [`react`](http://babeljs.io/docs/plugins/preset-react/), *tests* use those same plugins, plus the additional `custom` plugins specified.
129-
130-
AVA will only look for a `.babelrc` file in the same directory as the `package.json` file. If not found then it assumes your Babel config lives in the `package.json` file.
131-
132-
## Extend an alternate config file.
133-
134-
If, for some reason, your Babel config is not specified in one of the default locations ([`.babelrc` or `package.json`](http://babeljs.io/docs/usage/babelrc/), you can set the `extends` option to the alternate config you want to use during testing.
135-
136-
`package.json`:
137-
138-
```json
139-
{
140-
"ava": {
141-
"require": "babel-register",
142-
"babel": {
143-
"extends": "./babel-test-config.json",
144-
"plugins": ["custom-plugin-name"],
145-
"presets": ["custom-preset"]
146-
}
147-
}
148-
}
149-
```
150-
151-
The above uses `babel-test-config.json` as the transpilation config for *sources*, and as the base config for *tests*. For *tests*, it extends that base config with the custom plugins and presets specified.
9+
If you're using an older AVA version, please see [version 0.25.0 of this recipe](https://github.com/avajs/ava/blob/v0.25.0/docs/recipes/babelrc.md).

‎docs/recipes/code-coverage.md

+4
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
> **Please note, this recipe has not yet been updated for Babel 7 support in AVA 1.0.**
2+
3+
---
4+
15
# Code coverage
26

37
Translations: [Español](https://github.com/avajs/ava-docs/blob/master/es_ES/docs/recipes/code-coverage.md), [Français](https://github.com/avajs/ava-docs/blob/master/fr_FR/docs/recipes/code-coverage.md), [Italiano](https://github.com/avajs/ava-docs/blob/master/it_IT/docs/recipes/code-coverage.md), [日本語](https://github.com/avajs/ava-docs/blob/master/ja_JP/docs/recipes/code-coverage.md), [Português](https://github.com/avajs/ava-docs/blob/master/pt_BR/docs/recipes/code-coverage.md), [Русский](https://github.com/avajs/ava-docs/blob/master/ru_RU/docs/recipes/code-coverage.md), [简体中文](https://github.com/avajs/ava-docs/blob/master/zh_CN/docs/recipes/code-coverage.md)

‎docs/recipes/jspm-systemjs.md

+4
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
> **Please note, this recipe has not yet been updated for Babel 7 support in AVA 1.0.**
2+
3+
---
4+
15
# JSPM and SystemJS for ES2015
26

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

‎docs/recipes/precompiling-with-webpack.md

+4
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
> **Please note, this recipe has not yet been updated for Babel 7 support in AVA 1.0.**
2+
3+
---
4+
15
## Precompiling source files with webpack
26

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

‎docs/recipes/react.md

+4
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
> **Please note, this recipe has not yet been updated for Babel 7 support in AVA 1.0.**
2+
3+
---
4+
15
# Testing React components
26

37
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)

‎docs/recipes/vue.md

+4
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
> **Please note, this recipe has not yet been updated for Babel 7 support in AVA 1.0.**
2+
3+
---
4+
15
# Testing Vue.js components
26

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

‎lib/babel-config.js

+1-5
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,7 @@ function validate(conf) {
1919
}
2020

2121
if (!conf || typeof conf !== 'object' || !conf.testOptions || typeof conf.testOptions !== 'object' || Array.isArray(conf.testOptions) || Object.keys(conf).length > 1) {
22-
let message = colors.error(figures.cross);
23-
message += ' Unexpected Babel configuration for AVA. ';
24-
message += 'See ' + chalk.underline('https://github.com/avajs/ava#es2017-support') + ' for allowed values.';
25-
26-
throw new Error(message);
22+
throw new Error(`${colors.error(figures.cross)} Unexpected Babel configuration for AVA. See ${chalk.underline('https://github.com/avajs/ava/blob/master/docs/recipes/babel.md')} for allowed values.`);
2723
}
2824

2925
return conf;

0 commit comments

Comments
 (0)