Skip to content

Document common pitfalls #919

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 15 commits into from
Jul 1, 2016
Merged

Document common pitfalls #919

Show file tree
Hide file tree
Changes from 10 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
ba855b6
Document common pitfalls
Jun 14, 2016
0db5273
Fix typo
Jun 14, 2016
129e806
Document AVA and connected client limits
Jun 17, 2016
d663cd6
Update AVA and connected client limits
Jun 19, 2016
a777ffd
Add call for others to contribute
Jun 19, 2016
c9fa25c
Document async operations
Jun 19, 2016
da9c034
Various improvements
Jun 22, 2016
96685ba
Fix wrong word
Jun 23, 2016
349543f
Link from the readme
Jun 25, 2016
6434804
Move common pitfalls link to Tips
Jun 25, 2016
10cb03b
Make common pitfalls link relative
Jun 26, 2016
b79f347
Fix conflicts
Jun 26, 2016
6d71cbe
Attempt to fix more merge conflict stuff
Jun 26, 2016
f4a179c
on => in
Jun 29, 2016
691cecc
Fix spacing
Jun 30, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 42 additions & 0 deletions docs/common-pitfalls.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# Common Pitfalls

## 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 [https://github.com/avajs/ava/issues/751](#751).

AVA uses [is-ci](https://github.com/watson/is-ci) to decide if it's in a CI environment or not using [these variables](https://github.com/watson/is-ci/blob/master/index.js).

## AVA and connected client limits

You may be using a service that only allows a limited number of concurrent connections. For example, many database-as-a-service businesses offer a free plan with a limit on how many clients can be using it at the same time. AVA can hit those limits as it runs multiple processes, but well-written services should emit an error or throttle in those cases. If the one you're using doesn't, the tests will hang.

Use the `concurrency` flag to limit the number of processes ran. For example, if your service plan allows 5 clients, you should run AVA with `concurrency=5` or less.

## Async operations
Copy link
Member

@sindresorhus sindresorhus Jun 29, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I opened an issue about this: avajs/eslint-plugin-ava#122

We should really try to detect this at runtime and in our ESLint plugin too.


You may be running an async operation inside a test and wondering why it's not finishing. If your async operation uses promises, you should return the promise:

```js
test(t => {
return fetch().then(data => {
t.is(data, 'foo');
});
});
```

If it uses callbacks, use [`test.cb`](https://github.com/avajs/ava#callback-support):

```js
test.cb(t => {
fetch((err, data) => {
t.is(data, 'bar');
Copy link
Member

@novemberborn novemberborn Jun 19, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if we should advise promisifying the function. Assertion failures would throw, which depending on the async function's implementation may cause an uncaught exception.

Also you'd need t.end() in this example.

Copy link
Member

@sindresorhus sindresorhus Jun 19, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, we should recommend promisifying, but still show both solutions.

Copy link
Contributor

@jamestalmage jamestalmage Jun 19, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Assertion failures would throw

Our assertions don't throw after being enhanced.

test('foo', t => {
  t.is(1, 2);
  console.log('foo'); // this will get printed.
});

Copy link
Member

@novemberborn novemberborn Jun 20, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, but the next assertion could try to access a property of a null value and it'll still crash.

t.end();
});
});
```

Alternatively, promisify the callback function using something like [pify](https://github.com/sindresorhus/pify).

---

Is your problem not listed here? Submit a pull request or comment on [this issue](https://github.com/avajs/ava/issues/404).
136 changes: 70 additions & 66 deletions readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,13 +68,13 @@ $ ava --init

```json
{
"name": "awesome-package",
"scripts": {
"test": "ava"
},
"devDependencies": {
"ava": "^0.11.0"
}
"name": "awesome-package",
Copy link
Member

@novemberborn novemberborn Jun 26, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you leave the whitespace as it was?

Copy link
Contributor Author

@sotojuan sotojuan Jun 26, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was part of the merge conflict (this part was an old version from whenever I made my fork). Fixed when I merged readme from master.

"scripts": {
"test": "ava"
},
"devDependencies": {
"ava": "^0.11.0"
}
}
```

Expand Down Expand Up @@ -132,33 +132,33 @@ AVA comes with an intelligent watch mode. [Learn more in its recipe](docs/recipe
```console
$ ava --help

Usage
ava [<file|directory|glob> ...]

Options
--init Add AVA to your project
--fail-fast Stop after first test failure
--serial, -s Run tests serially
--require, -r Module to preload (Can be repeated)
--tap, -t Generate TAP output
--verbose, -v Enable verbose output
--no-cache Disable the transpiler cache
--match, -m Only run tests with matching title (Can be repeated)
--watch, -w Re-run tests when tests and source files change
--source, -S Pattern to match source files so tests can be re-run (Can be repeated)
--timeout, -T Set global timeout
--concurrency, -c Maximum number of test files running at the same time (EXPERIMENTAL)

Examples
ava
ava test.js test2.js
ava test-*.js
ava test
ava --init
ava --init foo.js

Default patterns when no arguments:
test.js test-*.js test/**/*.js **/__tests__/**/*.js **/*.test.js
Usage
ava [<file|directory|glob> ...]

Options
--init Add AVA to your project
--fail-fast Stop after first test failure
--serial, -s Run tests serially
--require, -r Module to preload (Can be repeated)
--tap, -t Generate TAP output
--verbose, -v Enable verbose output
--no-cache Disable the transpiler cache
--match, -m Only run tests with matching title (Can be repeated)
--watch, -w Re-run tests when tests and source files change
--source, -S Pattern to match source files so tests can be re-run (Can be repeated)
--timeout, -T Set global timeout
--concurrency, -c Maximum number of test files running at the same time (EXPERIMENTAL)

Examples
ava
ava test.js test2.js
ava test-*.js
ava test
ava --init
ava --init foo.js

Default patterns when no arguments:
test.js test-*.js test/**/*.js **/__tests__/**/*.js **/*.test.js
```

*Note that the CLI will use your local install of AVA when available, even when run globally.*
Expand All @@ -173,27 +173,27 @@ All of the CLI options can be configured in the `ava` section of your `package.j

```json
{
"ava": {
"files": [
"my-test-folder/*.js",
"!**/not-this-file.js"
],
"source": [
"**/*.{js,jsx}",
"!dist/**/*"
],
"match": [
"*oo",
"!foo"
],
"concurrency": 5,
"failFast": true,
"tap": true,
"require": [
"babel-register"
],
"babel": "inherit"
}
"ava": {
"files": [
"my-test-folder/*.js",
"!**/not-this-file.js"
],
"source": [
"**/*.{js,jsx}",
"!dist/**/*"
],
"match": [
"*oo",
"!foo"
],
"concurrency": 5,
"failFast": true,
"tap": true,
"require": [
"babel-register"
],
"babel": "inherit"
}
Copy link
Member

@sindresorhus sindresorhus Jun 29, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't do unrelated changes.

}
```

Expand Down Expand Up @@ -610,14 +610,14 @@ The corresponding Babel config for AVA's setup is as follows:

```json
{
"presets": [
"es2015",
"stage-2"
],
"plugins": [
"espower",
"transform-runtime"
]
"presets": [
"es2015",
"stage-2"
],
"plugins": [
"espower",
"transform-runtime"
]
}
```

Expand Down Expand Up @@ -935,9 +935,9 @@ Will output:

```
t.true(a.test(b) || b === c)
| | | |
| "bar" "bar" "baz"
false
| | | |
| "bar" "bar" "baz"
false
```

## Process isolation
Expand Down Expand Up @@ -966,6 +966,10 @@ You can't use [`istanbul`](https://github.com/gotwarlost/istanbul) for code cove

As of version `5.0.0` it uses source maps to report coverage for your actual code, regardless of transpilation. Make sure that the code you're testing includes an inline source map or references a source map file. If you use `babel-register` you can set the `sourceMaps` option in your Babel config to `inline`.

### Common pitfalls

We have a growing list of [common pitfalls](https://github.com/avajs/ava/blob/master/docs/common-pitfalls.md) you may experience while using AVA. If you encounter any issues you think are common, comment on [this issue](https://github.com/avajs/ava/issues/404).
Copy link
Member

@novemberborn novemberborn Jun 26, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Other links are relative (see Recipes for instance).


## FAQ

### Why not `mocha`, `tape`, `tap`?
Expand Down