Tags annotate tests and suites with arbitrary string labels. The

[`--experimental-test-tag-filter`][] CLI flag (or the `testTagFilters`

option on [`run()`][]) selects tests by a boolean expression over those

labels.

Tags are an alternative to encoding metadata into test names. They are

useful for cross-cutting axes such as subsystem, speed bucket, flakiness,

});

Tag values must be non-empty strings that contain no whitespace, no

operator characters (`& | ! ( ) *`), and are not the reserved words

`'and'`, `'or'`, or `'not'` in any casing. Tags are matched

case-insensitively; the canonical form is lowercase. Duplicates within a

single `tags` array are collapsed on the lowercased form, preserving the

first-seen declaration order.

Hooks (`before`, `after`, `beforeEach`, `afterEach`) do not declare their

own tags. They run as part of their owning suite, which carries the

suite's tags.

The filter expression supports:

* Identifiers—any non-whitespace, non-operator characters. A literal

identifier matches a tag of the same value (case-insensitive).

* `*` wildcards inside an identifier match any sequence of characters.

A bare `*` matches any tagged test.

* Boolean operators with two equivalent forms:

* `and` / `&&`

* `or` / `||`

* `not` / `!`

* Parentheses for grouping.

The word forms (`and`, `or`, `not`) require whitespace separation; the

punctuation forms do not.

The expression is evaluated with the standard precedence

`not > and > or`. Binary operators are left-associative.

| Expression | Equivalent grouping |

| -------------- | ------------------- |

| `a or b and c` | `a or (b and c)` |

| `not a and b` | `(not a) and b` |

Use parentheses to override:

| Expression | Selects |

| ------------------------------ | ------------------------------------------ |

| `(unit or smoke) and not slow` | unit-or-smoke tests that are not also slow |

| `db && !flaky` | db tests that are not flaky |

| `*` | every tagged test |

Untagged tests behave as if they have an empty tag set. As a result:

| Filter expression | Untagged test | Why |

| ------------------------ | ------------- | ------------------------------------------------ |

| `db` | excluded | Positive match against an empty tag set is false |

| `*` | excluded | The bare wildcard requires at least one tag |

| `db or unit` | excluded | Both branches are false against an empty tag set |

| `not flaky` | included | Negation against an empty tag set is true |

| `not flaky and not slow` | included | Both negations are true against an empty tag set |

| `db or not flaky` | included | The negated branch is true |

For example, `--experimental-test-tag-filter='not flaky'` runs every test

that is not tagged `flaky`, including all untagged tests.

[`--experimental-test-tag-filter`][] may be specified more than once on the

command line. Multiple expressions compose by AND—a test must satisfy

every expression to run. The same applies to passing an array to

`testTagFilters` on [`run()`][]. The tag filter is also AND'd with

[`--test-name-pattern`][], [`--test-skip-pattern`][], and `.only`

filtering.

The [`TestContext`][] object exposes the test's tags as a frozen array

through [`context.tags`][], so tests can branch on their own metadata.

A tag value that violates the validation rules above throws

`ERR_INVALID_ARG_VALUE` at the registration site, before any test runs.

A non-array `tags` value throws `ERR_INVALID_ARG_TYPE`. A malformed

filter expression on the CLI causes the test runner to exit with a

non-zero status before running any test files.

* `--test` - Prevented to avoid recursive test execution

* `--experimental-test-coverage` - Managed by the test runner

* `--experimental-test-tag-filter` - Filter expressions are validated by the parent

process and re-emitted to child processes

* `--watch` - Watch mode is handled at the parent level

* `--experimental-default-config-file` - Config file loading is handled by the parent

For each test that is executed, any corresponding test hooks, such as

`beforeEach()`, are also run.

**Default:** `undefined`.

* `testTagFilters` {string|string\[]} A boolean expression, or an array of

boolean expressions, used to filter tests by their declared tags.

Multiple expressions compose by AND. Equivalent to passing

[`--experimental-test-tag-filter`][] on the command line. See

[Test tags][]. **Default:** `undefined`.

* `timeout` {number} A number of milliseconds the test execution will

fail after.

If unspecified, subtests inherit this value from their parent.

Enable module mocking in the test runner.

This feature requires \fB--allow-worker\fR if used with the Permission Model.

.It Fl -experimental-test-tag-filter Ns = Ns Ar '<expr>'

Run only tests that match the provided boolean tag-filter expression. Tests

declare tags via the \fBtags\fR option on \fBtest()\fR, \fBit()\fR, \fBsuite()\fR, or

\fBdescribe()\fR. Tags inherit from suites to nested tests by union.

The expression supports boolean operators (\fBand\fR/\fB&&\fR, \fBor\fR/\fB||\fR,

\fBnot\fR/\fB!\fR), parentheses for grouping, and \fB*\fR wildcards inside identifiers.

Standard precedence applies: \fBnot\fR binds tighter than \fBand\fR, which binds

tighter than \fBor\fR. See Test tags for the full grammar and behavior.

The flag may be specified more than once; multiple expressions are combined

with AND, so a test must satisfy every expression to run.

A malformed expression causes the test runner to exit with a non-zero status

before running any tests.

.It Fl -experimental-vfs

Enable the experimental \fBnode:vfs\fR module.

ArrayPrototypePush,

ArrayPrototypePushApply,

ArrayPrototypeShift,

ArrayPrototypeSlice,

ArrayPrototypeSome,

ArrayPrototypeSort,

MathMax,

parseCommandLine,

} = require('internal/test_runner/utils');

const {

parseTagFilterExpression,

} = require('internal/test_runner/tag_filter');

const { Glob } = require('internal/fs/glob');

const { once } = require('events');

inspectPort,

testNamePatterns,

testSkipPatterns,

testTagFilterExpressions,

only,

hasFiles,

testFiles,

if (testSkipPatterns != null) {

ArrayPrototypeForEach(testSkipPatterns, (pattern) => ArrayPrototypePush(runArgs, `--test-skip-pattern=${pattern}`));

}

if (testTagFilterExpressions != null) {

ArrayPrototypeForEach(testTagFilterExpressions, (expr) => ArrayPrototypePush(runArgs, `--experimental-test-tag-filter=${expr}`));

}

if (only === true) {

ArrayPrototypePush(runArgs, '--test-only');

});

}

// The public contract of testTagFilters is `string | string[]`. The

// parseCommandLine bootstrap path piggybacks the already-parsed AST array

// on the same field, identifiable by the sibling testTagFilterExpressions

// field which only that path sets. When that marker is present and the

// first element isn't a string, treat the array as ASTs and skip the

// public validation loop. Otherwise validate every element as a string,

// so any non-string input throws ERR_INVALID_ARG_TYPE with the offending

// index regardless of position.

let testTagFilterExpressions = null;

if (testTagFilters != null) {

if (!ArrayIsArray(testTagFilters)) {

testTagFilters = [testTagFilters];

}

if (testTagFilters.length === 0) {

testTagFilters = null;

} else if (options.testTagFilterExpressions != null &&

typeof testTagFilters[0] !== 'string') {

// Internal bootstrap: trust the AST array as already-parsed.

} else {

emitExperimentalWarning('Test tags');

testTagFilterExpressions = ArrayPrototypeSlice(testTagFilters);

testTagFilters = ArrayPrototypeMap(testTagFilters, (value, i) => {

const name = `options.testTagFilters[${i}]`;

if (typeof value !== 'string') {

throw new ERR_INVALID_ARG_TYPE(name, 'string', value);

}

return parseTagFilterExpression(value, name);

});

}

}

testTagFilterExpressions ??= options.testTagFilterExpressions;

validateOneOf(isolation, 'options.isolation', ['process', 'none']);

validateBoolean(coverage, 'options.coverage');

inspectPort,

testNamePatterns,

testSkipPatterns,

testTagFilterExpressions,

hasFiles: files != null,

globPatterns,

only,