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

labels.

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.

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.

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.

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

* `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`.

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

ArrayPrototypeSlice,

parseTagFilterExpression,

testTagFilterExpressions,

if (testTagFilterExpressions != null) {

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

// 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;

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

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

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

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;

testTagFilterExpressions,