test_runner: extend tag filter with boolean expression DSL

Upgrades the experimental tag filter introduced by stage 1 to accept a
boolean expression instead of a literal tag name.
Grammar: `and`/`&&`, `or`/`||`, `not`/`!`, parentheses for grouping,
and `*` wildcards inside identifiers. Standard precedence
(`not > and > or`); binary operators are left-associative. Word forms
require whitespace separation; punctuation forms do not. Untagged
tests evaluate `false` for any include expression and `true` for
`not X`, so excluding tags does not accidentally remove untagged
tests.
The flag and `testTagFilters` option are still repeatable; multiple
expressions still AND together. Malformed expressions fail fast at
the parent process at startup.
Tag value validation tightens to reject whitespace, operator
characters (`& | ! ( ) *`), and the reserved words `and`/`or`/`not`
in any casing - a breaking change relative to the stage 1 ship,
acceptable at Stability 1.0 (Early development).
Signed-off-by: atlowChemi <chemi@atlow.co.il>
PR-URL: #63054
Reviewed-By: Moshe Atlow <moshe@atlow.co.il>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>

Author: atlowChemi

doc/api/cli.md

@@ -1480,22 +1480,28 @@ Enable module mocking in the test runner.
 
 This feature requires `--allow-worker` if used with the [Permission Model][].
 
-### `--experimental-test-tag-filter=<tag>`
+### `--experimental-test-tag-filter='<expr>'`
 
 <!-- YAML
 added: v26.2.0
 -->
 
 > Stability: 1.0 - Early development
 
-Run only tests whose tag set contains `<tag>`. Tests declare tags via the
-`tags` option on `test()`, `it()`, `suite()`, or `describe()`; tags
-inherit from suites to nested tests by union. Filtering is
-case-insensitive.
+Run only tests that match the provided boolean tag-filter expression. Tests
+declare tags via the `tags` option on `test()`, `it()`, `suite()`, or
+`describe()`. Tags inherit from suites to nested tests by union.
 
-The flag may be specified more than once; tests must contain **every**
-filter value to run. See [Test tags][] for details on declaring and
-inheriting tags.
+The expression supports boolean operators (`and`/`&&`, `or`/`||`,
+`not`/`!`), parentheses for grouping, and `*` wildcards inside identifiers.
+Standard precedence applies: `not` binds tighter than `and`, which binds
+tighter than `or`. 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.
 
 ### `--experimental-vfs`
 

doc/api/test.md

@@ -489,8 +489,8 @@ added: v26.2.0
 
 Tags annotate tests and suites with arbitrary string labels. The
 [`--experimental-test-tag-filter`][] CLI flag (or the `testTagFilters`
-option on [`run()`][]) selects tests whose tag set contains every
-provided filter value.
+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,
@@ -523,37 +523,89 @@ describe('database', { tags: ['db'] }, () => {
 });
 ```
 
-Tag values must be non-empty strings. 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.
+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.
 
-### Filtering by tag
+### Filtering syntax
 
-Each [`--experimental-test-tag-filter`][] value is a literal tag name. A
-test runs only when its tag set contains that name. The flag may be
-specified more than once; tests must match **every** filter to run. The
-same applies to the `testTagFilters` array on [`run()`][]. Filters are
-case-insensitive and AND'd with [`--test-name-pattern`][],
-[`--test-skip-pattern`][], and `.only` filtering.
+The filter expression supports:
 
-Untagged tests are excluded under any non-empty filter, since the filter
-requires the tag to be present.
+* 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.
 
-### Reading tags from inside a test
+The word forms (`and`, `or`, `not`) require whitespace separation; the
+punctuation forms do not.
+
+#### Operator precedence
+
+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
+
+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.
+
+#### Composing multiple filters
+
+[`--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.
+
+#### Reading tags from inside a test
 
 The [`TestContext`][] object exposes the test's tags as a frozen array
 through [`context.tags`][], so tests can branch on their own metadata.
 
-### Errors
+####Errors
 
 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 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.
 
 ## Extraneous asynchronous activity
 
@@ -826,7 +878,7 @@ test runner functionality:
 
 *`--test` - Prevented to avoid recursive test execution
 *`--experimental-test-coverage` - Managed by the test runner
-*`--experimental-test-tag-filter` - Filter values are validated by the parent
+*`--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
@@ -1740,10 +1792,11 @@ changes:
  For each test that is executed, any corresponding test hooks, such as
 `beforeEach()`, are also run.
 **Default:**`undefined`.
-*`testTagFilters` {string|string\[]} A tag name, or an array of tag names,
- used to filter tests by their declared tags. Tests must contain every
- listed tag to run. Equivalent to passing [`--experimental-test-tag-filter`][]
- on the command line. See [Test tags][]. **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.

doc/node.1

@@ -810,14 +810,18 @@ collecting code coverage from tests for more details.
 Enable module mocking in the test runner.
 This feature requires \fB--allow-worker\fR if used with the Permission Model.
 .
-.ItFl-experimental-test-tag-filterNs=NsAr<tag>
-Run only tests whose tag set contains \fB<tag>\fR. 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. Filtering is
-case-insensitive.
-The flag may be specified more than once; tests must contain \fBevery\fR
-filter value to run. See Test tags for details on declaring and
-inheriting tags.
+.ItFl-experimental-test-tag-filterNs=NsAr'<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.
 .
 .ItFl-experimental-vfs
 Enable the experimental \fBnode:vfs\fR module.

lib/internal/test_runner/runner.js

@@ -12,6 +12,7 @@ const {
  ArrayPrototypePush,
  ArrayPrototypePushApply,
  ArrayPrototypeShift,
+ ArrayPrototypeSlice,
  ArrayPrototypeSome,
  ArrayPrototypeSort,
  MathMax,
@@ -93,7 +94,7 @@ const {
  parseCommandLine,
 }=require('internal/test_runner/utils');
 const{
-validateAndCanonicalizeTagFilter,
+parseTagFilterExpression,
 }=require('internal/test_runner/tag_filter');
 const{ Glob }=require('internal/fs/glob');
 const{ once }=require('events');
@@ -182,7 +183,7 @@ function getRunArgs(path, { forceExit,
  inspectPort,
  testNamePatterns,
  testSkipPatterns,
-testTagFilters,
+testTagFilterExpressions,
  only,
  hasFiles,
  testFiles,
@@ -224,8 +225,8 @@ function getRunArgs(path, { forceExit,
 if(testSkipPatterns!=null){
 ArrayPrototypeForEach(testSkipPatterns,(pattern)=>ArrayPrototypePush(runArgs,`--test-skip-pattern=${pattern}`));
 }
-if(testTagFilters!=null){
-ArrayPrototypeForEach(testTagFilters,(value)=>ArrayPrototypePush(runArgs,`--experimental-test-tag-filter=${value}`));
+if(testTagFilterExpressions!=null){
+ArrayPrototypeForEach(testTagFilterExpressions,(expr)=>ArrayPrototypePush(runArgs,`--experimental-test-tag-filter=${expr}`));
 }
 if(only===true){
 ArrayPrototypePush(runArgs,'--test-only');
@@ -872,19 +873,37 @@ function run(options = kEmptyObject) {
 });
 }
 
+// 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.
+lettestTagFilterExpressions=null;
 if(testTagFilters!=null){
 if(!ArrayIsArray(testTagFilters)){
 testTagFilters=[testTagFilters];
 }
 if(testTagFilters.length===0){
 testTagFilters=null;
+}elseif(options.testTagFilterExpressions!=null&&
+typeoftestTagFilters[0]!=='string'){
+// Internal bootstrap: trust the AST array as already-parsed.
 }else{
 emitExperimentalWarning('Test tags');
-testTagFilters=ArrayPrototypeMap(testTagFilters,(value,i)=>(
-validateAndCanonicalizeTagFilter(value,`options.testTagFilters[${i}]`)
-));
+testTagFilterExpressions=ArrayPrototypeSlice(testTagFilters);
+testTagFilters=ArrayPrototypeMap(testTagFilters,(value,i)=>{
+constname=`options.testTagFilters[${i}]`;
+if(typeofvalue!=='string'){
+thrownewERR_INVALID_ARG_TYPE(name,'string',value);
+}
+returnparseTagFilterExpression(value,name);
+});
 }
 }
+testTagFilterExpressions??=options.testTagFilterExpressions;
 
 validateOneOf(isolation,'options.isolation',['process','none']);
 validateBoolean(coverage,'options.coverage');
@@ -986,7 +1005,7 @@ function run(options = kEmptyObject) {
  inspectPort,
  testNamePatterns,
  testSkipPatterns,
-testTagFilters,
+testTagFilterExpressions,
 hasFiles: files!=null,
  globPatterns,
  only,

doc/api/cli.md

@@ -1480,22 +1480,28 @@ Enable module mocking in the test runner.
 
 This feature requires `--allow-worker` if used with the [Permission Model][].
 
-### `--experimental-test-tag-filter=<tag>`
+### `--experimental-test-tag-filter='<expr>'`
 
 <!-- YAML
 added: v26.2.0
 -->
 
 > Stability: 1.0 - Early development
 
-Run only tests whose tag set contains `<tag>`. Tests declare tags via the
-`tags` option on `test()`, `it()`, `suite()`, or `describe()`; tags
-inherit from suites to nested tests by union. Filtering is
-case-insensitive.
+Run only tests that match the provided boolean tag-filter expression. Tests
+declare tags via the `tags` option on `test()`, `it()`, `suite()`, or
+`describe()`. Tags inherit from suites to nested tests by union.
 
-The flag may be specified more than once; tests must contain **every**
-filter value to run. See [Test tags][] for details on declaring and
-inheriting tags.
+The expression supports boolean operators (`and`/`&&`, `or`/`||`,
+`not`/`!`), parentheses for grouping, and `*` wildcards inside identifiers.
+Standard precedence applies: `not` binds tighter than `and`, which binds
+tighter than `or`. 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.
 
 ### `--experimental-vfs`
 

doc/api/test.md

@@ -489,8 +489,8 @@ added: v26.2.0
 
 Tags annotate tests and suites with arbitrary string labels. The
 [`--experimental-test-tag-filter`][] CLI flag (or the `testTagFilters`
-option on [`run()`][]) selects tests whose tag set contains every
-provided filter value.
+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,
@@ -523,37 +523,89 @@ describe('database', { tags: ['db'] }, () => {
 });
 ```
 
-Tag values must be non-empty strings. 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.
+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.
 
-### Filtering by tag
+### Filtering syntax
 
-Each [`--experimental-test-tag-filter`][] value is a literal tag name. A
-test runs only when its tag set contains that name. The flag may be
-specified more than once; tests must match **every** filter to run. The
-same applies to the `testTagFilters` array on [`run()`][]. Filters are
-case-insensitive and AND'd with [`--test-name-pattern`][],
-[`--test-skip-pattern`][], and `.only` filtering.
+The filter expression supports:
 
-Untagged tests are excluded under any non-empty filter, since the filter
-requires the tag to be present.
+* 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.
 
-### Reading tags from inside a test
+The word forms (`and`, `or`, `not`) require whitespace separation; the
+punctuation forms do not.
+
+#### Operator precedence
+
+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
+
+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.
+
+#### Composing multiple filters
+
+[`--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.
+
+#### Reading tags from inside a test
 
 The [`TestContext`][] object exposes the test's tags as a frozen array
 through [`context.tags`][], so tests can branch on their own metadata.
 
-### Errors
+####Errors
 
 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 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.
 
 ## Extraneous asynchronous activity
 
@@ -826,7 +878,7 @@ test runner functionality:
 
 *`--test` - Prevented to avoid recursive test execution
 *`--experimental-test-coverage` - Managed by the test runner
-*`--experimental-test-tag-filter` - Filter values are validated by the parent
+*`--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
@@ -1740,10 +1792,11 @@ changes:
  For each test that is executed, any corresponding test hooks, such as
 `beforeEach()`, are also run.
 **Default:**`undefined`.
-*`testTagFilters` {string|string\[]} A tag name, or an array of tag names,
- used to filter tests by their declared tags. Tests must contain every
- listed tag to run. Equivalent to passing [`--experimental-test-tag-filter`][]
- on the command line. See [Test tags][]. **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.

doc/node.1

@@ -810,14 +810,18 @@ collecting code coverage from tests for more details.
 Enable module mocking in the test runner.
 This feature requires \fB--allow-worker\fR if used with the Permission Model.
 .
-.ItFl-experimental-test-tag-filterNs=NsAr<tag>
-Run only tests whose tag set contains \fB<tag>\fR. 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. Filtering is
-case-insensitive.
-The flag may be specified more than once; tests must contain \fBevery\fR
-filter value to run. See Test tags for details on declaring and
-inheriting tags.
+.ItFl-experimental-test-tag-filterNs=NsAr'<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.
 .
 .ItFl-experimental-vfs
 Enable the experimental \fBnode:vfs\fR module.

lib/internal/test_runner/runner.js

@@ -12,6 +12,7 @@ const {
  ArrayPrototypePush,
  ArrayPrototypePushApply,
  ArrayPrototypeShift,
+ ArrayPrototypeSlice,
  ArrayPrototypeSome,
  ArrayPrototypeSort,
  MathMax,
@@ -93,7 +94,7 @@ const {
  parseCommandLine,
 }=require('internal/test_runner/utils');
 const{
-validateAndCanonicalizeTagFilter,
+parseTagFilterExpression,
 }=require('internal/test_runner/tag_filter');
 const{ Glob }=require('internal/fs/glob');
 const{ once }=require('events');
@@ -182,7 +183,7 @@ function getRunArgs(path, { forceExit,
  inspectPort,
  testNamePatterns,
  testSkipPatterns,
-testTagFilters,
+testTagFilterExpressions,
  only,
  hasFiles,
  testFiles,
@@ -224,8 +225,8 @@ function getRunArgs(path, { forceExit,
 if(testSkipPatterns!=null){
 ArrayPrototypeForEach(testSkipPatterns,(pattern)=>ArrayPrototypePush(runArgs,`--test-skip-pattern=${pattern}`));
 }
-if(testTagFilters!=null){
-ArrayPrototypeForEach(testTagFilters,(value)=>ArrayPrototypePush(runArgs,`--experimental-test-tag-filter=${value}`));
+if(testTagFilterExpressions!=null){
+ArrayPrototypeForEach(testTagFilterExpressions,(expr)=>ArrayPrototypePush(runArgs,`--experimental-test-tag-filter=${expr}`));
 }
 if(only===true){
 ArrayPrototypePush(runArgs,'--test-only');
@@ -872,19 +873,37 @@ function run(options = kEmptyObject) {
 });
 }
 
+// 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.
+lettestTagFilterExpressions=null;
 if(testTagFilters!=null){
 if(!ArrayIsArray(testTagFilters)){
 testTagFilters=[testTagFilters];
 }
 if(testTagFilters.length===0){
 testTagFilters=null;
+}elseif(options.testTagFilterExpressions!=null&&
+typeoftestTagFilters[0]!=='string'){
+// Internal bootstrap: trust the AST array as already-parsed.
 }else{
 emitExperimentalWarning('Test tags');
-testTagFilters=ArrayPrototypeMap(testTagFilters,(value,i)=>(
-validateAndCanonicalizeTagFilter(value,`options.testTagFilters[${i}]`)
-));
+testTagFilterExpressions=ArrayPrototypeSlice(testTagFilters);
+testTagFilters=ArrayPrototypeMap(testTagFilters,(value,i)=>{
+constname=`options.testTagFilters[${i}]`;
+if(typeofvalue!=='string'){
+thrownewERR_INVALID_ARG_TYPE(name,'string',value);
+}
+returnparseTagFilterExpression(value,name);
+});
 }
 }
+testTagFilterExpressions??=options.testTagFilterExpressions;
 
 validateOneOf(isolation,'options.isolation',['process','none']);
 validateBoolean(coverage,'options.coverage');
@@ -986,7 +1005,7 @@ function run(options = kEmptyObject) {
  inspectPort,
  testNamePatterns,
  testSkipPatterns,
-testTagFilters,
+testTagFilterExpressions,
 hasFiles: files!=null,
  globPatterns,
  only,

doc/api/cli.md

@@ -1480,22 +1480,28 @@ Enable module mocking in the test runner.
 
 This feature requires `--allow-worker` if used with the [Permission Model][].
 
-### `--experimental-test-tag-filter=<tag>`
+### `--experimental-test-tag-filter='<expr>'`
 
 <!-- YAML
 added: v26.2.0
 -->
 
 > Stability: 1.0 - Early development
 
-Run only tests whose tag set contains `<tag>`. Tests declare tags via the
-`tags` option on `test()`, `it()`, `suite()`, or `describe()`; tags
-inherit from suites to nested tests by union. Filtering is
-case-insensitive.
+Run only tests that match the provided boolean tag-filter expression. Tests
+declare tags via the `tags` option on `test()`, `it()`, `suite()`, or
+`describe()`. Tags inherit from suites to nested tests by union.
 
-The flag may be specified more than once; tests must contain **every**
-filter value to run. See [Test tags][] for details on declaring and
-inheriting tags.
+The expression supports boolean operators (`and`/`&&`, `or`/`||`,
+`not`/`!`), parentheses for grouping, and `*` wildcards inside identifiers.
+Standard precedence applies: `not` binds tighter than `and`, which binds
+tighter than `or`. 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.
 
 ### `--experimental-vfs`
 

doc/api/test.md

@@ -489,8 +489,8 @@ added: v26.2.0
 
 Tags annotate tests and suites with arbitrary string labels. The
 [`--experimental-test-tag-filter`][] CLI flag (or the `testTagFilters`
-option on [`run()`][]) selects tests whose tag set contains every
-provided filter value.
+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,
@@ -523,37 +523,89 @@ describe('database', { tags: ['db'] }, () => {
 });
 ```
 
-Tag values must be non-empty strings. 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.
+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.
 
-### Filtering by tag
+### Filtering syntax
 
-Each [`--experimental-test-tag-filter`][] value is a literal tag name. A
-test runs only when its tag set contains that name. The flag may be
-specified more than once; tests must match **every** filter to run. The
-same applies to the `testTagFilters` array on [`run()`][]. Filters are
-case-insensitive and AND'd with [`--test-name-pattern`][],
-[`--test-skip-pattern`][], and `.only` filtering.
+The filter expression supports:
 
-Untagged tests are excluded under any non-empty filter, since the filter
-requires the tag to be present.
+* 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.
 
-### Reading tags from inside a test
+The word forms (`and`, `or`, `not`) require whitespace separation; the
+punctuation forms do not.
+
+#### Operator precedence
+
+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
+
+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.
+
+#### Composing multiple filters
+
+[`--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.
+
+#### Reading tags from inside a test
 
 The [`TestContext`][] object exposes the test's tags as a frozen array
 through [`context.tags`][], so tests can branch on their own metadata.
 
-### Errors
+####Errors
 
 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 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.
 
 ## Extraneous asynchronous activity
 
@@ -826,7 +878,7 @@ test runner functionality:
 
 *`--test` - Prevented to avoid recursive test execution
 *`--experimental-test-coverage` - Managed by the test runner
-*`--experimental-test-tag-filter` - Filter values are validated by the parent
+*`--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
@@ -1740,10 +1792,11 @@ changes:
  For each test that is executed, any corresponding test hooks, such as
 `beforeEach()`, are also run.
 **Default:**`undefined`.
-*`testTagFilters` {string|string\[]} A tag name, or an array of tag names,
- used to filter tests by their declared tags. Tests must contain every
- listed tag to run. Equivalent to passing [`--experimental-test-tag-filter`][]
- on the command line. See [Test tags][]. **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.

doc/node.1

@@ -810,14 +810,18 @@ collecting code coverage from tests for more details.
 Enable module mocking in the test runner.
 This feature requires \fB--allow-worker\fR if used with the Permission Model.
 .
-.ItFl-experimental-test-tag-filterNs=NsAr<tag>
-Run only tests whose tag set contains \fB<tag>\fR. 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. Filtering is
-case-insensitive.
-The flag may be specified more than once; tests must contain \fBevery\fR
-filter value to run. See Test tags for details on declaring and
-inheriting tags.
+.ItFl-experimental-test-tag-filterNs=NsAr'<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.
 .
 .ItFl-experimental-vfs
 Enable the experimental \fBnode:vfs\fR module.

lib/internal/test_runner/runner.js

@@ -12,6 +12,7 @@ const {
  ArrayPrototypePush,
  ArrayPrototypePushApply,
  ArrayPrototypeShift,
+ ArrayPrototypeSlice,
  ArrayPrototypeSome,
  ArrayPrototypeSort,
  MathMax,
@@ -93,7 +94,7 @@ const {
  parseCommandLine,
 }=require('internal/test_runner/utils');
 const{
-validateAndCanonicalizeTagFilter,
+parseTagFilterExpression,
 }=require('internal/test_runner/tag_filter');
 const{ Glob }=require('internal/fs/glob');
 const{ once }=require('events');
@@ -182,7 +183,7 @@ function getRunArgs(path, { forceExit,
  inspectPort,
  testNamePatterns,
  testSkipPatterns,
-testTagFilters,
+testTagFilterExpressions,
  only,
  hasFiles,
  testFiles,
@@ -224,8 +225,8 @@ function getRunArgs(path, { forceExit,
 if(testSkipPatterns!=null){
 ArrayPrototypeForEach(testSkipPatterns,(pattern)=>ArrayPrototypePush(runArgs,`--test-skip-pattern=${pattern}`));
 }
-if(testTagFilters!=null){
-ArrayPrototypeForEach(testTagFilters,(value)=>ArrayPrototypePush(runArgs,`--experimental-test-tag-filter=${value}`));
+if(testTagFilterExpressions!=null){
+ArrayPrototypeForEach(testTagFilterExpressions,(expr)=>ArrayPrototypePush(runArgs,`--experimental-test-tag-filter=${expr}`));
 }
 if(only===true){
 ArrayPrototypePush(runArgs,'--test-only');
@@ -872,19 +873,37 @@ function run(options = kEmptyObject) {
 });
 }
 
+// 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.
+lettestTagFilterExpressions=null;
 if(testTagFilters!=null){
 if(!ArrayIsArray(testTagFilters)){
 testTagFilters=[testTagFilters];
 }
 if(testTagFilters.length===0){
 testTagFilters=null;
+}elseif(options.testTagFilterExpressions!=null&&
+typeoftestTagFilters[0]!=='string'){
+// Internal bootstrap: trust the AST array as already-parsed.
 }else{
 emitExperimentalWarning('Test tags');
-testTagFilters=ArrayPrototypeMap(testTagFilters,(value,i)=>(
-validateAndCanonicalizeTagFilter(value,`options.testTagFilters[${i}]`)
-));
+testTagFilterExpressions=ArrayPrototypeSlice(testTagFilters);
+testTagFilters=ArrayPrototypeMap(testTagFilters,(value,i)=>{
+constname=`options.testTagFilters[${i}]`;
+if(typeofvalue!=='string'){
+thrownewERR_INVALID_ARG_TYPE(name,'string',value);
+}
+returnparseTagFilterExpression(value,name);
+});
 }
 }
+testTagFilterExpressions??=options.testTagFilterExpressions;
 
 validateOneOf(isolation,'options.isolation',['process','none']);
 validateBoolean(coverage,'options.coverage');
@@ -986,7 +1005,7 @@ function run(options = kEmptyObject) {
  inspectPort,
  testNamePatterns,
  testSkipPatterns,
-testTagFilters,
+testTagFilterExpressions,
 hasFiles: files!=null,
  globPatterns,
  only,

doc/api/cli.md

@@ -1480,22 +1480,28 @@ Enable module mocking in the test runner.
 
 This feature requires `--allow-worker` if used with the [Permission Model][].
 
-### `--experimental-test-tag-filter=<tag>`
+### `--experimental-test-tag-filter='<expr>'`
 
 <!-- YAML
 added: v26.2.0
 -->
 
 > Stability: 1.0 - Early development
 
-Run only tests whose tag set contains `<tag>`. Tests declare tags via the
-`tags` option on `test()`, `it()`, `suite()`, or `describe()`; tags
-inherit from suites to nested tests by union. Filtering is
-case-insensitive.
+Run only tests that match the provided boolean tag-filter expression. Tests
+declare tags via the `tags` option on `test()`, `it()`, `suite()`, or
+`describe()`. Tags inherit from suites to nested tests by union.
 
-The flag may be specified more than once; tests must contain **every**
-filter value to run. See [Test tags][] for details on declaring and
-inheriting tags.
+The expression supports boolean operators (`and`/`&&`, `or`/`||`,
+`not`/`!`), parentheses for grouping, and `*` wildcards inside identifiers.
+Standard precedence applies: `not` binds tighter than `and`, which binds
+tighter than `or`. 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.
 
 ### `--experimental-vfs`
 

doc/api/test.md

@@ -489,8 +489,8 @@ added: v26.2.0
 
 Tags annotate tests and suites with arbitrary string labels. The
 [`--experimental-test-tag-filter`][] CLI flag (or the `testTagFilters`
-option on [`run()`][]) selects tests whose tag set contains every
-provided filter value.
+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,
@@ -523,37 +523,89 @@ describe('database', { tags: ['db'] }, () => {
 });
 ```
 
-Tag values must be non-empty strings. 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.
+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.
 
-### Filtering by tag
+### Filtering syntax
 
-Each [`--experimental-test-tag-filter`][] value is a literal tag name. A
-test runs only when its tag set contains that name. The flag may be
-specified more than once; tests must match **every** filter to run. The
-same applies to the `testTagFilters` array on [`run()`][]. Filters are
-case-insensitive and AND'd with [`--test-name-pattern`][],
-[`--test-skip-pattern`][], and `.only` filtering.
+The filter expression supports:
 
-Untagged tests are excluded under any non-empty filter, since the filter
-requires the tag to be present.
+* 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.
 
-### Reading tags from inside a test
+The word forms (`and`, `or`, `not`) require whitespace separation; the
+punctuation forms do not.
+
+#### Operator precedence
+
+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
+
+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.
+
+#### Composing multiple filters
+
+[`--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.
+
+#### Reading tags from inside a test
 
 The [`TestContext`][] object exposes the test's tags as a frozen array
 through [`context.tags`][], so tests can branch on their own metadata.
 
-### Errors
+####Errors
 
 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 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.
 
 ## Extraneous asynchronous activity
 
@@ -826,7 +878,7 @@ test runner functionality:
 
 *`--test` - Prevented to avoid recursive test execution
 *`--experimental-test-coverage` - Managed by the test runner
-*`--experimental-test-tag-filter` - Filter values are validated by the parent
+*`--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
@@ -1740,10 +1792,11 @@ changes:
  For each test that is executed, any corresponding test hooks, such as
 `beforeEach()`, are also run.
 **Default:**`undefined`.
-*`testTagFilters` {string|string\[]} A tag name, or an array of tag names,
- used to filter tests by their declared tags. Tests must contain every
- listed tag to run. Equivalent to passing [`--experimental-test-tag-filter`][]
- on the command line. See [Test tags][]. **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.

doc/node.1

@@ -810,14 +810,18 @@ collecting code coverage from tests for more details.
 Enable module mocking in the test runner.
 This feature requires \fB--allow-worker\fR if used with the Permission Model.
 .
-.ItFl-experimental-test-tag-filterNs=NsAr<tag>
-Run only tests whose tag set contains \fB<tag>\fR. 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. Filtering is
-case-insensitive.
-The flag may be specified more than once; tests must contain \fBevery\fR
-filter value to run. See Test tags for details on declaring and
-inheriting tags.
+.ItFl-experimental-test-tag-filterNs=NsAr'<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.
 .
 .ItFl-experimental-vfs
 Enable the experimental \fBnode:vfs\fR module.

lib/internal/test_runner/runner.js

@@ -12,6 +12,7 @@ const {
  ArrayPrototypePush,
  ArrayPrototypePushApply,
  ArrayPrototypeShift,
+ ArrayPrototypeSlice,
  ArrayPrototypeSome,
  ArrayPrototypeSort,
  MathMax,
@@ -93,7 +94,7 @@ const {
  parseCommandLine,
 }=require('internal/test_runner/utils');
 const{
-validateAndCanonicalizeTagFilter,
+parseTagFilterExpression,
 }=require('internal/test_runner/tag_filter');
 const{ Glob }=require('internal/fs/glob');
 const{ once }=require('events');
@@ -182,7 +183,7 @@ function getRunArgs(path, { forceExit,
  inspectPort,
  testNamePatterns,
  testSkipPatterns,
-testTagFilters,
+testTagFilterExpressions,
  only,
  hasFiles,
  testFiles,
@@ -224,8 +225,8 @@ function getRunArgs(path, { forceExit,
 if(testSkipPatterns!=null){
 ArrayPrototypeForEach(testSkipPatterns,(pattern)=>ArrayPrototypePush(runArgs,`--test-skip-pattern=${pattern}`));
 }
-if(testTagFilters!=null){
-ArrayPrototypeForEach(testTagFilters,(value)=>ArrayPrototypePush(runArgs,`--experimental-test-tag-filter=${value}`));
+if(testTagFilterExpressions!=null){
+ArrayPrototypeForEach(testTagFilterExpressions,(expr)=>ArrayPrototypePush(runArgs,`--experimental-test-tag-filter=${expr}`));
 }
 if(only===true){
 ArrayPrototypePush(runArgs,'--test-only');
@@ -872,19 +873,37 @@ function run(options = kEmptyObject) {
 });
 }
 
+// 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.
+lettestTagFilterExpressions=null;
 if(testTagFilters!=null){
 if(!ArrayIsArray(testTagFilters)){
 testTagFilters=[testTagFilters];
 }
 if(testTagFilters.length===0){
 testTagFilters=null;
+}elseif(options.testTagFilterExpressions!=null&&
+typeoftestTagFilters[0]!=='string'){
+// Internal bootstrap: trust the AST array as already-parsed.
 }else{
 emitExperimentalWarning('Test tags');
-testTagFilters=ArrayPrototypeMap(testTagFilters,(value,i)=>(
-validateAndCanonicalizeTagFilter(value,`options.testTagFilters[${i}]`)
-));
+testTagFilterExpressions=ArrayPrototypeSlice(testTagFilters);
+testTagFilters=ArrayPrototypeMap(testTagFilters,(value,i)=>{
+constname=`options.testTagFilters[${i}]`;
+if(typeofvalue!=='string'){
+thrownewERR_INVALID_ARG_TYPE(name,'string',value);
+}
+returnparseTagFilterExpression(value,name);
+});
 }
 }
+testTagFilterExpressions??=options.testTagFilterExpressions;
 
 validateOneOf(isolation,'options.isolation',['process','none']);
 validateBoolean(coverage,'options.coverage');
@@ -986,7 +1005,7 @@ function run(options = kEmptyObject) {
  inspectPort,
  testNamePatterns,
  testSkipPatterns,
-testTagFilters,
+testTagFilterExpressions,
 hasFiles: files!=null,
  globPatterns,
  only,

doc/api/cli.md

@@ -1480,22 +1480,28 @@ Enable module mocking in the test runner.
 
 This feature requires `--allow-worker` if used with the [Permission Model][].
 
-### `--experimental-test-tag-filter=<tag>`
+### `--experimental-test-tag-filter='<expr>'`
 
 <!-- YAML
 added: v26.2.0
 -->
 
 > Stability: 1.0 - Early development
 
-Run only tests whose tag set contains `<tag>`. Tests declare tags via the
-`tags` option on `test()`, `it()`, `suite()`, or `describe()`; tags
-inherit from suites to nested tests by union. Filtering is
-case-insensitive.
+Run only tests that match the provided boolean tag-filter expression. Tests
+declare tags via the `tags` option on `test()`, `it()`, `suite()`, or
+`describe()`. Tags inherit from suites to nested tests by union.
 
-The flag may be specified more than once; tests must contain **every**
-filter value to run. See [Test tags][] for details on declaring and
-inheriting tags.
+The expression supports boolean operators (`and`/`&&`, `or`/`||`,
+`not`/`!`), parentheses for grouping, and `*` wildcards inside identifiers.
+Standard precedence applies: `not` binds tighter than `and`, which binds
+tighter than `or`. 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.
 
 ### `--experimental-vfs`
 

doc/api/test.md

@@ -489,8 +489,8 @@ added: v26.2.0
 
 Tags annotate tests and suites with arbitrary string labels. The
 [`--experimental-test-tag-filter`][] CLI flag (or the `testTagFilters`
-option on [`run()`][]) selects tests whose tag set contains every
-provided filter value.
+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,
@@ -523,37 +523,89 @@ describe('database', { tags: ['db'] }, () => {
 });
 ```
 
-Tag values must be non-empty strings. 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.
+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.
 
-### Filtering by tag
+### Filtering syntax
 
-Each [`--experimental-test-tag-filter`][] value is a literal tag name. A
-test runs only when its tag set contains that name. The flag may be
-specified more than once; tests must match **every** filter to run. The
-same applies to the `testTagFilters` array on [`run()`][]. Filters are
-case-insensitive and AND'd with [`--test-name-pattern`][],
-[`--test-skip-pattern`][], and `.only` filtering.
+The filter expression supports:
 
-Untagged tests are excluded under any non-empty filter, since the filter
-requires the tag to be present.
+* 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.
 
-### Reading tags from inside a test
+The word forms (`and`, `or`, `not`) require whitespace separation; the
+punctuation forms do not.
+
+#### Operator precedence
+
+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
+
+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.
+
+#### Composing multiple filters
+
+[`--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.
+
+#### Reading tags from inside a test
 
 The [`TestContext`][] object exposes the test's tags as a frozen array
 through [`context.tags`][], so tests can branch on their own metadata.
 
-### Errors
+####Errors
 
 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 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.
 
 ## Extraneous asynchronous activity
 
@@ -826,7 +878,7 @@ test runner functionality:
 
 *`--test` - Prevented to avoid recursive test execution
 *`--experimental-test-coverage` - Managed by the test runner
-*`--experimental-test-tag-filter` - Filter values are validated by the parent
+*`--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
@@ -1740,10 +1792,11 @@ changes:
  For each test that is executed, any corresponding test hooks, such as
 `beforeEach()`, are also run.
 **Default:**`undefined`.
-*`testTagFilters` {string|string\[]} A tag name, or an array of tag names,
- used to filter tests by their declared tags. Tests must contain every
- listed tag to run. Equivalent to passing [`--experimental-test-tag-filter`][]
- on the command line. See [Test tags][]. **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.

doc/node.1

@@ -810,14 +810,18 @@ collecting code coverage from tests for more details.
 Enable module mocking in the test runner.
 This feature requires \fB--allow-worker\fR if used with the Permission Model.
 .
-.ItFl-experimental-test-tag-filterNs=NsAr<tag>
-Run only tests whose tag set contains \fB<tag>\fR. 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. Filtering is
-case-insensitive.
-The flag may be specified more than once; tests must contain \fBevery\fR
-filter value to run. See Test tags for details on declaring and
-inheriting tags.
+.ItFl-experimental-test-tag-filterNs=NsAr'<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.
 .
 .ItFl-experimental-vfs
 Enable the experimental \fBnode:vfs\fR module.

lib/internal/test_runner/runner.js

@@ -12,6 +12,7 @@ const {
  ArrayPrototypePush,
  ArrayPrototypePushApply,
  ArrayPrototypeShift,
+ ArrayPrototypeSlice,
  ArrayPrototypeSome,
  ArrayPrototypeSort,
  MathMax,
@@ -93,7 +94,7 @@ const {
  parseCommandLine,
 }=require('internal/test_runner/utils');
 const{
-validateAndCanonicalizeTagFilter,
+parseTagFilterExpression,
 }=require('internal/test_runner/tag_filter');
 const{ Glob }=require('internal/fs/glob');
 const{ once }=require('events');
@@ -182,7 +183,7 @@ function getRunArgs(path, { forceExit,
  inspectPort,
  testNamePatterns,
  testSkipPatterns,
-testTagFilters,
+testTagFilterExpressions,
  only,
  hasFiles,
  testFiles,
@@ -224,8 +225,8 @@ function getRunArgs(path, { forceExit,
 if(testSkipPatterns!=null){
 ArrayPrototypeForEach(testSkipPatterns,(pattern)=>ArrayPrototypePush(runArgs,`--test-skip-pattern=${pattern}`));
 }
-if(testTagFilters!=null){
-ArrayPrototypeForEach(testTagFilters,(value)=>ArrayPrototypePush(runArgs,`--experimental-test-tag-filter=${value}`));
+if(testTagFilterExpressions!=null){
+ArrayPrototypeForEach(testTagFilterExpressions,(expr)=>ArrayPrototypePush(runArgs,`--experimental-test-tag-filter=${expr}`));
 }
 if(only===true){
 ArrayPrototypePush(runArgs,'--test-only');
@@ -872,19 +873,37 @@ function run(options = kEmptyObject) {
 });
 }
 
+// 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.
+lettestTagFilterExpressions=null;
 if(testTagFilters!=null){
 if(!ArrayIsArray(testTagFilters)){
 testTagFilters=[testTagFilters];
 }
 if(testTagFilters.length===0){
 testTagFilters=null;
+}elseif(options.testTagFilterExpressions!=null&&
+typeoftestTagFilters[0]!=='string'){
+// Internal bootstrap: trust the AST array as already-parsed.
 }else{
 emitExperimentalWarning('Test tags');
-testTagFilters=ArrayPrototypeMap(testTagFilters,(value,i)=>(
-validateAndCanonicalizeTagFilter(value,`options.testTagFilters[${i}]`)
-));
+testTagFilterExpressions=ArrayPrototypeSlice(testTagFilters);
+testTagFilters=ArrayPrototypeMap(testTagFilters,(value,i)=>{
+constname=`options.testTagFilters[${i}]`;
+if(typeofvalue!=='string'){
+thrownewERR_INVALID_ARG_TYPE(name,'string',value);
+}
+returnparseTagFilterExpression(value,name);
+});
 }
 }
+testTagFilterExpressions??=options.testTagFilterExpressions;
 
 validateOneOf(isolation,'options.isolation',['process','none']);
 validateBoolean(coverage,'options.coverage');
@@ -986,7 +1005,7 @@ function run(options = kEmptyObject) {
  inspectPort,
  testNamePatterns,
  testSkipPatterns,
-testTagFilters,
+testTagFilterExpressions,
 hasFiles: files!=null,
  globPatterns,
  only,

doc/api/cli.md

@@ -1480,22 +1480,28 @@ Enable module mocking in the test runner.
 
 This feature requires `--allow-worker` if used with the [Permission Model][].
 
-### `--experimental-test-tag-filter=<tag>`
+### `--experimental-test-tag-filter='<expr>'`
 
 <!-- YAML
 added: v26.2.0
 -->
 
 > Stability: 1.0 - Early development
 
-Run only tests whose tag set contains `<tag>`. Tests declare tags via the
-`tags` option on `test()`, `it()`, `suite()`, or `describe()`; tags
-inherit from suites to nested tests by union. Filtering is
-case-insensitive.
+Run only tests that match the provided boolean tag-filter expression. Tests
+declare tags via the `tags` option on `test()`, `it()`, `suite()`, or
+`describe()`. Tags inherit from suites to nested tests by union.
 
-The flag may be specified more than once; tests must contain **every**
-filter value to run. See [Test tags][] for details on declaring and
-inheriting tags.
+The expression supports boolean operators (`and`/`&&`, `or`/`||`,
+`not`/`!`), parentheses for grouping, and `*` wildcards inside identifiers.
+Standard precedence applies: `not` binds tighter than `and`, which binds
+tighter than `or`. 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.
 
 ### `--experimental-vfs`
 

doc/api/test.md

@@ -489,8 +489,8 @@ added: v26.2.0
 
 Tags annotate tests and suites with arbitrary string labels. The
 [`--experimental-test-tag-filter`][] CLI flag (or the `testTagFilters`
-option on [`run()`][]) selects tests whose tag set contains every
-provided filter value.
+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,
@@ -523,37 +523,89 @@ describe('database', { tags: ['db'] }, () => {
 });
 ```
 
-Tag values must be non-empty strings. 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.
+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.
 
-### Filtering by tag
+### Filtering syntax
 
-Each [`--experimental-test-tag-filter`][] value is a literal tag name. A
-test runs only when its tag set contains that name. The flag may be
-specified more than once; tests must match **every** filter to run. The
-same applies to the `testTagFilters` array on [`run()`][]. Filters are
-case-insensitive and AND'd with [`--test-name-pattern`][],
-[`--test-skip-pattern`][], and `.only` filtering.
+The filter expression supports:
 
-Untagged tests are excluded under any non-empty filter, since the filter
-requires the tag to be present.
+* 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.
 
-### Reading tags from inside a test
+The word forms (`and`, `or`, `not`) require whitespace separation; the
+punctuation forms do not.
+
+#### Operator precedence
+
+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
+
+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.
+
+#### Composing multiple filters
+
+[`--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.
+
+#### Reading tags from inside a test
 
 The [`TestContext`][] object exposes the test's tags as a frozen array
 through [`context.tags`][], so tests can branch on their own metadata.
 
-### Errors
+####Errors
 
 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 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.
 
 ## Extraneous asynchronous activity
 
@@ -826,7 +878,7 @@ test runner functionality:
 
 *`--test` - Prevented to avoid recursive test execution
 *`--experimental-test-coverage` - Managed by the test runner
-*`--experimental-test-tag-filter` - Filter values are validated by the parent
+*`--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
@@ -1740,10 +1792,11 @@ changes:
  For each test that is executed, any corresponding test hooks, such as
 `beforeEach()`, are also run.
 **Default:**`undefined`.
-*`testTagFilters` {string|string\[]} A tag name, or an array of tag names,
- used to filter tests by their declared tags. Tests must contain every
- listed tag to run. Equivalent to passing [`--experimental-test-tag-filter`][]
- on the command line. See [Test tags][]. **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.

doc/node.1

@@ -810,14 +810,18 @@ collecting code coverage from tests for more details.
 Enable module mocking in the test runner.
 This feature requires \fB--allow-worker\fR if used with the Permission Model.
 .
-.ItFl-experimental-test-tag-filterNs=NsAr<tag>
-Run only tests whose tag set contains \fB<tag>\fR. 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. Filtering is
-case-insensitive.
-The flag may be specified more than once; tests must contain \fBevery\fR
-filter value to run. See Test tags for details on declaring and
-inheriting tags.
+.ItFl-experimental-test-tag-filterNs=NsAr'<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.
 .
 .ItFl-experimental-vfs
 Enable the experimental \fBnode:vfs\fR module.

lib/internal/test_runner/runner.js

@@ -12,6 +12,7 @@ const {
  ArrayPrototypePush,
  ArrayPrototypePushApply,
  ArrayPrototypeShift,
+ ArrayPrototypeSlice,
  ArrayPrototypeSome,
  ArrayPrototypeSort,
  MathMax,
@@ -93,7 +94,7 @@ const {
  parseCommandLine,
 }=require('internal/test_runner/utils');
 const{
-validateAndCanonicalizeTagFilter,
+parseTagFilterExpression,
 }=require('internal/test_runner/tag_filter');
 const{ Glob }=require('internal/fs/glob');
 const{ once }=require('events');
@@ -182,7 +183,7 @@ function getRunArgs(path, { forceExit,
  inspectPort,
  testNamePatterns,
  testSkipPatterns,
-testTagFilters,
+testTagFilterExpressions,
  only,
  hasFiles,
  testFiles,
@@ -224,8 +225,8 @@ function getRunArgs(path, { forceExit,
 if(testSkipPatterns!=null){
 ArrayPrototypeForEach(testSkipPatterns,(pattern)=>ArrayPrototypePush(runArgs,`--test-skip-pattern=${pattern}`));
 }
-if(testTagFilters!=null){
-ArrayPrototypeForEach(testTagFilters,(value)=>ArrayPrototypePush(runArgs,`--experimental-test-tag-filter=${value}`));
+if(testTagFilterExpressions!=null){
+ArrayPrototypeForEach(testTagFilterExpressions,(expr)=>ArrayPrototypePush(runArgs,`--experimental-test-tag-filter=${expr}`));
 }
 if(only===true){
 ArrayPrototypePush(runArgs,'--test-only');
@@ -872,19 +873,37 @@ function run(options = kEmptyObject) {
 });
 }
 
+// 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.
+lettestTagFilterExpressions=null;
 if(testTagFilters!=null){
 if(!ArrayIsArray(testTagFilters)){
 testTagFilters=[testTagFilters];
 }
 if(testTagFilters.length===0){
 testTagFilters=null;
+}elseif(options.testTagFilterExpressions!=null&&
+typeoftestTagFilters[0]!=='string'){
+// Internal bootstrap: trust the AST array as already-parsed.
 }else{
 emitExperimentalWarning('Test tags');
-testTagFilters=ArrayPrototypeMap(testTagFilters,(value,i)=>(
-validateAndCanonicalizeTagFilter(value,`options.testTagFilters[${i}]`)
-));
+testTagFilterExpressions=ArrayPrototypeSlice(testTagFilters);
+testTagFilters=ArrayPrototypeMap(testTagFilters,(value,i)=>{
+constname=`options.testTagFilters[${i}]`;
+if(typeofvalue!=='string'){
+thrownewERR_INVALID_ARG_TYPE(name,'string',value);
+}
+returnparseTagFilterExpression(value,name);
+});
 }
 }
+testTagFilterExpressions??=options.testTagFilterExpressions;
 
 validateOneOf(isolation,'options.isolation',['process','none']);
 validateBoolean(coverage,'options.coverage');
@@ -986,7 +1005,7 @@ function run(options = kEmptyObject) {
  inspectPort,
  testNamePatterns,
  testSkipPatterns,
-testTagFilters,
+testTagFilterExpressions,
 hasFiles: files!=null,
  globPatterns,
  only,

doc/api/cli.md

@@ -1480,22 +1480,28 @@ Enable module mocking in the test runner.
 
 This feature requires `--allow-worker` if used with the [Permission Model][].
 
-### `--experimental-test-tag-filter=<tag>`
+### `--experimental-test-tag-filter='<expr>'`
 
 <!-- YAML
 added: v26.2.0
 -->
 
 > Stability: 1.0 - Early development
 
-Run only tests whose tag set contains `<tag>`. Tests declare tags via the
-`tags` option on `test()`, `it()`, `suite()`, or `describe()`; tags
-inherit from suites to nested tests by union. Filtering is
-case-insensitive.
+Run only tests that match the provided boolean tag-filter expression. Tests
+declare tags via the `tags` option on `test()`, `it()`, `suite()`, or
+`describe()`. Tags inherit from suites to nested tests by union.
 
-The flag may be specified more than once; tests must contain **every**
-filter value to run. See [Test tags][] for details on declaring and
-inheriting tags.
+The expression supports boolean operators (`and`/`&&`, `or`/`||`,
+`not`/`!`), parentheses for grouping, and `*` wildcards inside identifiers.
+Standard precedence applies: `not` binds tighter than `and`, which binds
+tighter than `or`. 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.
 
 ### `--experimental-vfs`
 

doc/api/test.md

@@ -489,8 +489,8 @@ added: v26.2.0
 
 Tags annotate tests and suites with arbitrary string labels. The
 [`--experimental-test-tag-filter`][] CLI flag (or the `testTagFilters`
-option on [`run()`][]) selects tests whose tag set contains every
-provided filter value.
+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,
@@ -523,37 +523,89 @@ describe('database', { tags: ['db'] }, () => {
 });
 ```
 
-Tag values must be non-empty strings. 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.
+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.
 
-### Filtering by tag
+### Filtering syntax
 
-Each [`--experimental-test-tag-filter`][] value is a literal tag name. A
-test runs only when its tag set contains that name. The flag may be
-specified more than once; tests must match **every** filter to run. The
-same applies to the `testTagFilters` array on [`run()`][]. Filters are
-case-insensitive and AND'd with [`--test-name-pattern`][],
-[`--test-skip-pattern`][], and `.only` filtering.
+The filter expression supports:
 
-Untagged tests are excluded under any non-empty filter, since the filter
-requires the tag to be present.
+* 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.
 
-### Reading tags from inside a test
+The word forms (`and`, `or`, `not`) require whitespace separation; the
+punctuation forms do not.
+
+#### Operator precedence
+
+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
+
+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.
+
+#### Composing multiple filters
+
+[`--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.
+
+#### Reading tags from inside a test
 
 The [`TestContext`][] object exposes the test's tags as a frozen array
 through [`context.tags`][], so tests can branch on their own metadata.
 
-### Errors
+####Errors
 
 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 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.
 
 ## Extraneous asynchronous activity
 
@@ -826,7 +878,7 @@ test runner functionality:
 
 *`--test` - Prevented to avoid recursive test execution
 *`--experimental-test-coverage` - Managed by the test runner
-*`--experimental-test-tag-filter` - Filter values are validated by the parent
+*`--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
@@ -1740,10 +1792,11 @@ changes:
  For each test that is executed, any corresponding test hooks, such as
 `beforeEach()`, are also run.
 **Default:**`undefined`.
-*`testTagFilters` {string|string\[]} A tag name, or an array of tag names,
- used to filter tests by their declared tags. Tests must contain every
- listed tag to run. Equivalent to passing [`--experimental-test-tag-filter`][]
- on the command line. See [Test tags][]. **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.

doc/node.1

@@ -810,14 +810,18 @@ collecting code coverage from tests for more details.
 Enable module mocking in the test runner.
 This feature requires \fB--allow-worker\fR if used with the Permission Model.
 .
-.ItFl-experimental-test-tag-filterNs=NsAr<tag>
-Run only tests whose tag set contains \fB<tag>\fR. 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. Filtering is
-case-insensitive.
-The flag may be specified more than once; tests must contain \fBevery\fR
-filter value to run. See Test tags for details on declaring and
-inheriting tags.
+.ItFl-experimental-test-tag-filterNs=NsAr'<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.
 .
 .ItFl-experimental-vfs
 Enable the experimental \fBnode:vfs\fR module.

lib/internal/test_runner/runner.js

@@ -12,6 +12,7 @@ const {
  ArrayPrototypePush,
  ArrayPrototypePushApply,
  ArrayPrototypeShift,
+ ArrayPrototypeSlice,
  ArrayPrototypeSome,
  ArrayPrototypeSort,
  MathMax,
@@ -93,7 +94,7 @@ const {
  parseCommandLine,
 }=require('internal/test_runner/utils');
 const{
-validateAndCanonicalizeTagFilter,
+parseTagFilterExpression,
 }=require('internal/test_runner/tag_filter');
 const{ Glob }=require('internal/fs/glob');
 const{ once }=require('events');
@@ -182,7 +183,7 @@ function getRunArgs(path, { forceExit,
  inspectPort,
  testNamePatterns,
  testSkipPatterns,
-testTagFilters,
+testTagFilterExpressions,
  only,
  hasFiles,
  testFiles,
@@ -224,8 +225,8 @@ function getRunArgs(path, { forceExit,
 if(testSkipPatterns!=null){
 ArrayPrototypeForEach(testSkipPatterns,(pattern)=>ArrayPrototypePush(runArgs,`--test-skip-pattern=${pattern}`));
 }
-if(testTagFilters!=null){
-ArrayPrototypeForEach(testTagFilters,(value)=>ArrayPrototypePush(runArgs,`--experimental-test-tag-filter=${value}`));
+if(testTagFilterExpressions!=null){
+ArrayPrototypeForEach(testTagFilterExpressions,(expr)=>ArrayPrototypePush(runArgs,`--experimental-test-tag-filter=${expr}`));
 }
 if(only===true){
 ArrayPrototypePush(runArgs,'--test-only');
@@ -872,19 +873,37 @@ function run(options = kEmptyObject) {
 });
 }
 
+// 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.
+lettestTagFilterExpressions=null;
 if(testTagFilters!=null){
 if(!ArrayIsArray(testTagFilters)){
 testTagFilters=[testTagFilters];
 }
 if(testTagFilters.length===0){
 testTagFilters=null;
+}elseif(options.testTagFilterExpressions!=null&&
+typeoftestTagFilters[0]!=='string'){
+// Internal bootstrap: trust the AST array as already-parsed.
 }else{
 emitExperimentalWarning('Test tags');
-testTagFilters=ArrayPrototypeMap(testTagFilters,(value,i)=>(
-validateAndCanonicalizeTagFilter(value,`options.testTagFilters[${i}]`)
-));
+testTagFilterExpressions=ArrayPrototypeSlice(testTagFilters);
+testTagFilters=ArrayPrototypeMap(testTagFilters,(value,i)=>{
+constname=`options.testTagFilters[${i}]`;
+if(typeofvalue!=='string'){
+thrownewERR_INVALID_ARG_TYPE(name,'string',value);
+}
+returnparseTagFilterExpression(value,name);
+});
 }
 }
+testTagFilterExpressions??=options.testTagFilterExpressions;
 
 validateOneOf(isolation,'options.isolation',['process','none']);
 validateBoolean(coverage,'options.coverage');
@@ -986,7 +1005,7 @@ function run(options = kEmptyObject) {
  inspectPort,
  testNamePatterns,
  testSkipPatterns,
-testTagFilters,
+testTagFilterExpressions,
 hasFiles: files!=null,
  globPatterns,
  only,

doc/api/cli.md

@@ -1480,22 +1480,28 @@ Enable module mocking in the test runner.
 
 This feature requires `--allow-worker` if used with the [Permission Model][].
 
-### `--experimental-test-tag-filter=<tag>`
+### `--experimental-test-tag-filter='<expr>'`
 
 <!-- YAML
 added: v26.2.0
 -->
 
 > Stability: 1.0 - Early development
 
-Run only tests whose tag set contains `<tag>`. Tests declare tags via the
-`tags` option on `test()`, `it()`, `suite()`, or `describe()`; tags
-inherit from suites to nested tests by union. Filtering is
-case-insensitive.
+Run only tests that match the provided boolean tag-filter expression. Tests
+declare tags via the `tags` option on `test()`, `it()`, `suite()`, or
+`describe()`. Tags inherit from suites to nested tests by union.
 
-The flag may be specified more than once; tests must contain **every**
-filter value to run. See [Test tags][] for details on declaring and
-inheriting tags.
+The expression supports boolean operators (`and`/`&&`, `or`/`||`,
+`not`/`!`), parentheses for grouping, and `*` wildcards inside identifiers.
+Standard precedence applies: `not` binds tighter than `and`, which binds
+tighter than `or`. 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.
 
 ### `--experimental-vfs`
 

doc/api/test.md

@@ -489,8 +489,8 @@ added: v26.2.0
 
 Tags annotate tests and suites with arbitrary string labels. The
 [`--experimental-test-tag-filter`][] CLI flag (or the `testTagFilters`
-option on [`run()`][]) selects tests whose tag set contains every
-provided filter value.
+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,
@@ -523,37 +523,89 @@ describe('database', { tags: ['db'] }, () => {
 });
 ```
 
-Tag values must be non-empty strings. 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.
+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.
 
-### Filtering by tag
+### Filtering syntax
 
-Each [`--experimental-test-tag-filter`][] value is a literal tag name. A
-test runs only when its tag set contains that name. The flag may be
-specified more than once; tests must match **every** filter to run. The
-same applies to the `testTagFilters` array on [`run()`][]. Filters are
-case-insensitive and AND'd with [`--test-name-pattern`][],
-[`--test-skip-pattern`][], and `.only` filtering.
+The filter expression supports:
 
-Untagged tests are excluded under any non-empty filter, since the filter
-requires the tag to be present.
+* 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.
 
-### Reading tags from inside a test
+The word forms (`and`, `or`, `not`) require whitespace separation; the
+punctuation forms do not.
+
+#### Operator precedence
+
+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
+
+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.
+
+#### Composing multiple filters
+
+[`--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.
+
+#### Reading tags from inside a test
 
 The [`TestContext`][] object exposes the test's tags as a frozen array
 through [`context.tags`][], so tests can branch on their own metadata.
 
-### Errors
+####Errors
 
 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 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.
 
 ## Extraneous asynchronous activity
 
@@ -826,7 +878,7 @@ test runner functionality:
 
 *`--test` - Prevented to avoid recursive test execution
 *`--experimental-test-coverage` - Managed by the test runner
-*`--experimental-test-tag-filter` - Filter values are validated by the parent
+*`--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
@@ -1740,10 +1792,11 @@ changes:
  For each test that is executed, any corresponding test hooks, such as
 `beforeEach()`, are also run.
 **Default:**`undefined`.
-*`testTagFilters` {string|string\[]} A tag name, or an array of tag names,
- used to filter tests by their declared tags. Tests must contain every
- listed tag to run. Equivalent to passing [`--experimental-test-tag-filter`][]
- on the command line. See [Test tags][]. **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.

doc/node.1

@@ -810,14 +810,18 @@ collecting code coverage from tests for more details.
 Enable module mocking in the test runner.
 This feature requires \fB--allow-worker\fR if used with the Permission Model.
 .
-.ItFl-experimental-test-tag-filterNs=NsAr<tag>
-Run only tests whose tag set contains \fB<tag>\fR. 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. Filtering is
-case-insensitive.
-The flag may be specified more than once; tests must contain \fBevery\fR
-filter value to run. See Test tags for details on declaring and
-inheriting tags.
+.ItFl-experimental-test-tag-filterNs=NsAr'<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.
 .
 .ItFl-experimental-vfs
 Enable the experimental \fBnode:vfs\fR module.

lib/internal/test_runner/runner.js

@@ -12,6 +12,7 @@ const {
  ArrayPrototypePush,
  ArrayPrototypePushApply,
  ArrayPrototypeShift,
+ ArrayPrototypeSlice,
  ArrayPrototypeSome,
  ArrayPrototypeSort,
  MathMax,
@@ -93,7 +94,7 @@ const {
  parseCommandLine,
 }=require('internal/test_runner/utils');
 const{
-validateAndCanonicalizeTagFilter,
+parseTagFilterExpression,
 }=require('internal/test_runner/tag_filter');
 const{ Glob }=require('internal/fs/glob');
 const{ once }=require('events');
@@ -182,7 +183,7 @@ function getRunArgs(path, { forceExit,
  inspectPort,
  testNamePatterns,
  testSkipPatterns,
-testTagFilters,
+testTagFilterExpressions,
  only,
  hasFiles,
  testFiles,
@@ -224,8 +225,8 @@ function getRunArgs(path, { forceExit,
 if(testSkipPatterns!=null){
 ArrayPrototypeForEach(testSkipPatterns,(pattern)=>ArrayPrototypePush(runArgs,`--test-skip-pattern=${pattern}`));
 }
-if(testTagFilters!=null){
-ArrayPrototypeForEach(testTagFilters,(value)=>ArrayPrototypePush(runArgs,`--experimental-test-tag-filter=${value}`));
+if(testTagFilterExpressions!=null){
+ArrayPrototypeForEach(testTagFilterExpressions,(expr)=>ArrayPrototypePush(runArgs,`--experimental-test-tag-filter=${expr}`));
 }
 if(only===true){
 ArrayPrototypePush(runArgs,'--test-only');
@@ -872,19 +873,37 @@ function run(options = kEmptyObject) {
 });
 }
 
+// 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.
+lettestTagFilterExpressions=null;
 if(testTagFilters!=null){
 if(!ArrayIsArray(testTagFilters)){
 testTagFilters=[testTagFilters];
 }
 if(testTagFilters.length===0){
 testTagFilters=null;
+}elseif(options.testTagFilterExpressions!=null&&
+typeoftestTagFilters[0]!=='string'){
+// Internal bootstrap: trust the AST array as already-parsed.
 }else{
 emitExperimentalWarning('Test tags');
-testTagFilters=ArrayPrototypeMap(testTagFilters,(value,i)=>(
-validateAndCanonicalizeTagFilter(value,`options.testTagFilters[${i}]`)
-));
+testTagFilterExpressions=ArrayPrototypeSlice(testTagFilters);
+testTagFilters=ArrayPrototypeMap(testTagFilters,(value,i)=>{
+constname=`options.testTagFilters[${i}]`;
+if(typeofvalue!=='string'){
+thrownewERR_INVALID_ARG_TYPE(name,'string',value);
+}
+returnparseTagFilterExpression(value,name);
+});
 }
 }
+testTagFilterExpressions??=options.testTagFilterExpressions;
 
 validateOneOf(isolation,'options.isolation',['process','none']);
 validateBoolean(coverage,'options.coverage');
@@ -986,7 +1005,7 @@ function run(options = kEmptyObject) {
  inspectPort,
  testNamePatterns,
  testSkipPatterns,
-testTagFilters,
+testTagFilterExpressions,
 hasFiles: files!=null,
  globPatterns,
  only,