AVA(1)

✨ AVA(1) ✨

okay bestie, welcome to AVA — the test runner for Node.js with a concise API, living in the General Commands Manual. Also there's Translations: Français if that's your vibe 🌸

---

🌈 SYNOPSIS 🌈

ava [<pattern>...]
ava debug [<pattern>...]
ava reset-cache

Commands:
  ava [<pattern>...]        Run tests                                  [default]
  ava debug [<pattern>...]  Activate Node.js inspector and run a single test
                            file
  ava reset-cache           Delete any temporary files and state kept by AVA,
                            then exit

Positionals:
  pattern  Select which test files to run. Leave empty if you want AVA to run
           all test files as per your configuration. Accepts glob patterns,
           directories that (recursively) contain test files, and file paths
           optionally suffixed with a colon and comma-separated numbers and/or
           ranges identifying the 1-based line(s) of specific tests to run
                                                                        [string]

Options:
      --version            Show version number                         [boolean]
      --color              Force color output                          [boolean]
      --config             Specific JavaScript file for AVA to read its config
                           from, instead of using package.json or ava.config.*
                           files
      --help               Show help                                   [boolean]
  -c, --concurrency        Max number of test files running at the same time
                           (default: CPU cores)                         [number]
      --fail-fast          Stop after first test failure               [boolean]
  -m, --match              Only run tests with matching title (can be repeated)
                                                                        [string]
      --no-worker-threads  Don't use worker threads                    [boolean]
      --node-arguments     Additional Node.js arguments for launching worker
                           processes (specify as a single string)       [string]
  -s, --serial             Run tests serially                          [boolean]
  -t, --tap                Generate TAP output                         [boolean]
  -T, --timeout            Set global timeout (milliseconds or human-readable,
                           e.g. 10s, 2m)                                [string]
  -u, --update-snapshots   Update snapshots                            [boolean]
  -v, --verbose            Enable verbose output (default)             [boolean]
  -w, --watch              Re-run tests when files change              [boolean]

Examples:
  ava
  ava test.js
  ava test.js:4,7-9

---

💅 DESCRIPTION 💅

so AVA goes hunting for test files using these patterns, no cap:

• test.js
• src/test.js
• source/test.js
• **/test-*.js
• **/*.spec.js
• **/*.test.js
• **/test/**/*.js
• **/tests/**/*.js
• **/__tests__/**/*.js

Files inside node_modules are always ignored, periodt. Same for files starting with _ or files inside directories that start with a single _. And also, these patterns are ignored by default — unless you configured different patterns:

• **/__tests__/**/__helper__/**/*
• **/__tests__/**/__helpers__/**/*
• **/__tests__/**/__fixture__/**/*
• **/__tests__/**/__fixtures__/**/*
• **/test/**/helper/**/*
• **/test/**/helpers/**/*
• **/test/**/fixture/**/*
• **/test/**/fixtures/**/*
• **/tests/**/helper/**/*
• **/tests/**/helpers/**/*
• **/tests/**/fixture/**/*
• **/tests/**/fixtures/**/*

when you're using npm test, you can pass positional arguments directly like npm test test2.js 🫶 but flags need to be passed like npm test -- --verbose.

---

🎯 Running tests with matching titles

![Open              in              StackBlitz](https://developer.stack‐
blitz.com/img/open_in_stackblitz.svg)

The --match flag lets you run just the tests with a matching title. It works with simple wildcard patterns, and the patterns are case insensitive. Peep matcher for more deets.

Match titles ending with foo:

npx ava --match='*foo'

Match titles starting with foo:

npx ava --match='foo*'

Match titles containing foo:

npx ava --match='*foo*'

Match titles that are exactly foo (albeit case insensitively):

npx ava --match='foo'

Match titles not containing foo:

npx ava --match='!*foo*'

Match titles starting with foo and ending with bar:

npx ava --match='foo*bar'

Match titles starting with foo or ending with bar:

npx ava --match='foo*' --match='*bar'

bestie, important: a match pattern takes precedence over the .only modifier. Only tests with an explicit title get matched. Tests without titles, or whose title is derived from the implementation function, get skipped when --match is used. 💀

Here's what happens when you run AVA with a match pattern of *oo* and the following tests:

test('foo will run', t => {
    t.pass();
});

test('moo will also run', t => {
    t.pass();
});

test.only('boo will run but not exclusively', t => {
    t.pass();
});

// Won't run, no title
test(function (t) {
    t.fail();
});

// Won't run, no explicit title
test(function foo(t) {
    t.fail();
});

---

📍 Running tests at specific line numbers

![Open              in              StackBlitz](https://developer.stack‐
blitz.com/img/open_in_stackblitz.svg)

AVA lets you run tests exclusively by pointing at their line numbers. Target a single line, a range of lines, or both — literally any line number of a test works. 👑

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. iykyk.

🌸 Running a single test

To only run a particular test in a file, append the line number of the test to the path or pattern passed to AVA.

Given the following test file:

test.js
  1: test('unicorn', t => {
  2:   t.pass();
  3: });
  4:
  5: test('rainbow', t => {
  6:  t.fail();
  7: });

Running npx ava test.js:2 for would run the unicorn test. In fact you could use any line number between 1 and 3.

🦋 Running multiple tests

To run multiple tests, either target them one by one or select a range of line numbers. Since line numbers are given per file, you can run multiple files with different line numbers for each file. If the same file is provided multiple times, line numbers are merged and only run once.

✨ Examples

Single line numbers:

npx ava test.js:2,9

Range:

npx ava test.js:4-7

Mix of single line number and range:

npx ava test.js:4,9-12

Different files:

npx ava test.js:3 test2.js:4,7-9

When running a file with and without line numbers, line numbers take precedence.

---

🧹 Resetting AVA's cache

AVA keeps some temporary state around. You can clear this state by running:

npx ava reset-cache

This deletes all files in the node_modules/.cache/ava directory. so satisfying honestly 🧼

---

📢 Reporters

AVA uses a human readable reporter by default: <img src="../media/verbose-reporter.png" width="294">

🌈 TAP reporter

![Open              in              StackBlitz](https://developer.stack‐
blitz.com/img/open_in_stackblitz.svg)

AVA supports the TAP format and thus is compatible with any TAP reporter. Use the --tap flag to enable TAP output.

$ npx ava --tap | npx tap-nyan

<img src="../media/tap-reporter.png" width="420">

Please note that the TAP reporter is unavailable when using watch mode. 😭

---

🧚 Node arguments

The --node-arguments argument may be used to specify additional arguments for launching worker processes. These are combined with the nodeArguments configuration and any arguments passed to the node binary when starting AVA.

Only pass trusted values. 🔥

Specify the arguments as a single string:

npx ava --node-arguments="--throw-deprecation --zero-fill-buffers"

Only pass trusted values. (yes, again, because it matters bestie 💜)

---

okay that's the whole page 🎀 this was AVA 5.3.1, dated November 2023 — mwah, go write some tests, you've got this 💖✨🦋