diff options
Diffstat (limited to 'node_modules/ava/readme.md')
| -rw-r--r-- | node_modules/ava/readme.md | 63 |
1 files changed, 49 insertions, 14 deletions
diff --git a/node_modules/ava/readme.md b/node_modules/ava/readme.md index 239f257a4..825e83253 100644 --- a/node_modules/ava/readme.md +++ b/node_modules/ava/readme.md @@ -2,7 +2,7 @@ > Futuristic test runner -[](https://travis-ci.org/avajs/ava) [](https://ci.appveyor.com/project/ava/ava/branch/master) [](https://coveralls.io/github/avajs/ava?branch=master) [](https://dependencyci.com/github/avajs/ava) [](https://github.com/sindresorhus/xo) [](https://gitter.im/avajs/ava) +[](https://travis-ci.org/avajs/ava) [](https://ci.appveyor.com/project/ava/ava/branch/master) [](https://coveralls.io/github/avajs/ava?branch=master) [](https://dependencyci.com/github/avajs/ava) [](https://github.com/sindresorhus/xo) [](https://gitter.im/avajs/ava) [](https://github.com/sindresorhus/awesome-nodejs) Even though JavaScript is single-threaded, IO in Node.js can happen in parallel due to its async nature. AVA takes advantage of this and runs your tests concurrently, which is especially beneficial for IO heavy tests. In addition, test files are run in parallel as separate processes, giving you even better performance and an isolated environment for each test file. [Switching](https://github.com/sindresorhus/pageres/commit/663be15acb3dd2eb0f71b1956ef28c2cd3fdeed0) from Mocha to AVA in Pageres brought the test time down from 31 to 11 seconds. Having tests run concurrently forces you to write atomic tests, meaning tests don't depend on global state or the state of other tests, which is a great thing! @@ -69,18 +69,18 @@ test(t => { ### Add AVA to your project -Install AVA globally and run it with `--init` to add AVA to your `package.json`. [Yarn](https://yarnpkg.com/) currently provides significant speed improvements over npm during the installation process. Consider [using Yarn](https://yarnpkg.com/en/docs/install) if the installation is too slow for your needs. +Install AVA globally and run it with `--init` to add AVA to your `package.json`. ```console -$ yarn global add ava +$ npm install --global ava $ ava --init ``` -If you prefer using npm: +If you prefer using Yarn: ```console -$ npm install --global ava +$ yarn global add ava $ ava --init ``` @@ -105,13 +105,13 @@ Any arguments passed after `--init` are added as config to `package.json`. You can also install AVA directly: ```console -$ yarn add --dev ava +$ npm install --save-dev ava ``` -Alternatively using npm: +Alternatively using Yarn: ```console -$ npm install --save-dev ava +$ yarn add --dev ava ``` You'll have to configure the `test` script in your `package.json` to use `ava` (see above). @@ -169,7 +169,7 @@ $ ava --help --match, -m Only run tests with matching title (Can be repeated) --watch, -w Re-run tests when tests and source files change --timeout, -T Set global timeout - --concurrency, -c Maximum number of test files running at the same time (EXPERIMENTAL) + --concurrency, -c Max number of test files running at the same time (Default: CPU cores) --update-snapshots, -u Update snapshots Examples @@ -277,7 +277,20 @@ All of the CLI options can be configured in the `ava` section of your `package.j Arguments passed to the CLI will always take precedence over the configuration in `package.json`. -See the [ES2017 support](#es2017-support) section for details on the `babel` option. +### Options + +- `files`: file & directory paths and glob patterns that select which files AVA will run tests from. Only files with a `.js` extension are used. Files with an underscore prefix are ignored. All `.js` files in selected directories are run +- `source`: files that, when changed, cause tests to be re-run 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](#running-tests-with-matching-titles) +- `failFast`: stop running further tests once a test fails +- `failWithoutAssertions`: if `false`, does not fail a test if it doesn't run [assertions](#assertions) +- `tap`: if `true`, enables the [TAP reporter](#tap-reporter) +- `snapshotDir`: specifies a fixed location for storing snapshot files. Use this if your snapshots are ending up in the wrong location +- `powerAssert`: if `false`, disables [power-assert](https://github.com/power-assert-js/power-assert) which otherwise helps provide more descriptive error messages +- `require`: extra modules to require before tests are run. Modules are required in the [worker processes](#process-isolation) +- `babel`: test file specific Babel options. See [ES2017 support](#es2017-support) for more details + +Note that providing files on the CLI overrides the `files` option. If you've configured a glob pattern, for instance `test/**/*.test.js`, you may want to repeat it when using the CLI: `ava 'test/integration/*.test.js'`. ## Documentation @@ -400,7 +413,7 @@ test.only('will be run', t => { }); ``` -`.only` applies across all test files, so if you use it in one file, no tests from the other file will run. +*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. ### Running tests with matching titles @@ -513,10 +526,12 @@ test.failing('demonstrate some bug', t => { AVA lets you register hooks that are run before and after your tests. This allows you to run setup and/or teardown code. -`test.before()` registers a hook to be run before the first test in your test file. Similarly `test.after()` registers a hook to be run after the last test. Use `test.after.always()` to register a hook that will **always** run once your tests and other hooks complete. `.always()` hooks run regardless of whether there were earlier failures, so they are ideal for cleanup tasks. There are two exceptions to this however. If you use `--fail-fast` AVA will stop testing as soon as a failure occurs, and it won't run any hooks including the `.always()` hooks. Uncaught exceptions will crash your tests, possibly preventing `.always()` hooks from running. +`test.before()` registers a hook to be run before the first test in your test file. Similarly `test.after()` registers a hook to be run after the last test. Use `test.after.always()` to register a hook that will **always** run once your tests and other hooks complete. `.always()` hooks run regardless of whether there were earlier failures or if all tests were skipped, so they are ideal for cleanup tasks. There are two exceptions to this however. If you use `--fail-fast` AVA will stop testing as soon as a failure occurs, and it won't run any hooks including the `.always()` hooks. Uncaught exceptions will crash your tests, possibly preventing `.always()` hooks from running. `test.beforeEach()` registers a hook to be run before each test in your test file. Similarly `test.afterEach()` a hook to be run after each test. Use `test.afterEach.always()` to register an after hook that is called even if other test hooks, or the test itself, fail. `.always()` hooks are ideal for cleanup tasks. +If a test is skipped with the `.skip` modifier, the respective `.beforeEach()` and `.afterEach()` hooks are not run. Likewise, if all tests in a test file are skipped `.before()` and `.after()` hooks for the file are not run. Hooks modified with `.always()` will always run, even if all tests are skipped. + **Note**: If the `--fail-fast` flag is specified, AVA will stop after the first test failure and the `.always` hook will **not** run. Like `test()` these methods take an optional title and a callback function. The title is shown if your hook fails to execute. The callback is called with an [execution object](#t). @@ -875,6 +890,10 @@ Plan how many assertion there are in the test. The test will fail if the actual End the test. Only works with `test.cb()`. +###### `t.log(message)` + +Print a log message contextually alongside the test result instead of immediately printing it to `stdout` like `console.log`. + ## Assertions Assertions are mixed into the [execution object](#t) provided to each test implementation: @@ -975,7 +994,7 @@ Assert that `function` does not throw an error or that `promise` does not reject Like the `.throws()` assertion, when testing a promise you must wait for the assertion to complete: ```js -test('rejects', async t => { +test('resolves', async t => { await t.notThrows(promise); }); ``` @@ -1041,6 +1060,20 @@ You can then check your code. If the change was intentional you can use the `--u $ ava --update-snapshots ``` +You can specify a fixed location for storing the snapshot files in AVA's [`package.json` configuration](#configuration): + +```json +{ + "ava": { + "snapshotDir": "custom-directory" + } +} +``` + +The snapshot files will be saved in a directory structure that mirrors that of your test files. + +If you are running AVA against precompiled test files, AVA will try and use source maps to determine the location of the original files. Snapshots will be stored next to these files, following the same rules as if AVA had executed the original files directly. This is great if you're writing your tests in TypeScript (see our [TypeScript recipe](docs/recipes/typescript.md)). + ### Skipping assertions Any assertion can be skipped using the `skip` modifier. Skipped assertions are still counted, so there is no need to change your planned assertion count. @@ -1096,6 +1129,8 @@ t.true(a.test(b) || b === c) 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`. + ## Tips ### Temp files @@ -1178,7 +1213,7 @@ It's the [Andromeda galaxy](https://simple.wikipedia.org/wiki/Andromeda_galaxy). ## Team -[](http://sindresorhus.com) | [](https://github.com/vadimdemedes) | [](https://github.com/jamestalmage) | [](https://novemberborn.net) | [](https://juansoto.me) | [](https://github.com/jfmengels) +[](https://github.com/sindresorhus) | [](https://github.com/vadimdemedes) | [](https://github.com/jamestalmage) | [](https://github.com/novemberborn) | [](https://github.com/sotojuan) | [](https://github.com/jfmengels) ---|---|---|---|---|--- [Sindre Sorhus](http://sindresorhus.com) | [Vadim Demedes](https://github.com/vadimdemedes) | [James Talmage](https://github.com/jamestalmage) | [Mark Wubben](https://novemberborn.net) | [Juan Soto](http://juansoto.me) | [Jeroen Engels](https://github.com/jfmengels) |