nodejs
diff --git a/‎doc/api/cli.md‎
Lines changed: 18 additions & 0 deletions b/‎doc/api/cli.md‎
Lines changed: 18 additions & 0 deletions
diff --git a/‎doc/api/test.md‎
Lines changed: 134 additions & 0 deletions b/‎doc/api/test.md‎
Lines changed: 134 additions & 0 deletions
diff --git a/‎doc/node.1‎
Lines changed: 4 additions & 0 deletions b/‎doc/node.1‎
Lines changed: 4 additions & 0 deletions
diff --git a/‎lib/internal/test_runner/harness.js‎
Lines changed: 2 additions & 0 deletions b/‎lib/internal/test_runner/harness.js‎
Lines changed: 2 additions & 0 deletions
@@ -1237,6 +1237,23 @@ Enable module mocking in the test runner.
 
 This feature requires `--allow-worker` if used with the [Permission Model][].
 
+### `--experimental-test-tag-filter=<tag>`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> 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.
+
+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.
+
 ### `--experimental-transform-types`
 
 <!-- YAML
@@ -4140,6 +4157,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [ScriptCoverage]: https://chromedevtools.github.io/devtools-protocol/tot/Profiler#type-ScriptCoverage
 [ShadowRealm]: https://github.com/tc39/proposal-shadowrealm
 [Source Map]: https://tc39.es/ecma426/
+[Test tags]: test.md#test-tags
 [TypeScript type-stripping]: typescript.md#type-stripping
 [V8 Inspector integration for Node.js]: debugger.md#v8-inspector-integration-for-nodejs
 [V8 JavaScript code coverage]: https://v8project.blogspot.com/2017/12/javascript-code-coverage.html
 
@@ -478,6 +478,82 @@ Test name patterns do not change the set of files that the test runner executes.
 If both `--test-name-pattern` and `--test-skip-pattern` are supplied,
 tests must satisfy **both** requirements in order to be executed.
 
+## Test tags
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1.0 - Early development
+
+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.
+
+Tags are an alternative to encoding metadata into test names. They are
+useful for cross-cutting axes such as subsystem, speed bucket, flakiness,
+or environment, where a name pattern would be brittle.
+
+### Authoring tagged tests
+
+Pass a `tags` array on any of `test()`, `it()`, `suite()`, or `describe()`.
+Tags inherit from a suite to its child tests by union—a test inside a
+suite tagged `['db']` that declares its own `tags: ['integration']`
+effectively has both tags.
+
+```mjs
+import { describe, it } from 'node:test';
+
+describe('database', { tags: ['db'] }, () => {
+  it('reads a row');                                            // tags: ['db']
+  it('writes a row', { tags: ['integration'] });                // tags: ['db', 'integration']
+  it('reconnects after disconnect', { tags: ['flaky'] });       // tags: ['db', 'flaky']
+});
+```
+
+```cjs
+const { describe, it } = require('node:test');
+
+describe('database', { tags: ['db'] }, () => {
+  it('reads a row');                                            // tags: ['db']
+  it('writes a row', { tags: ['integration'] });                // tags: ['db', 'integration']
+  it('reconnects after disconnect', { tags: ['flaky'] });       // tags: ['db', 'flaky']
+});
+```
+
+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.
+
+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
+
+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.
+
+Untagged tests are excluded under any non-empty filter, since the filter
+requires the tag to be present.
+
+### 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
+
+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`.
+
 ## Extraneous asynchronous activity
 
 Once a test function finishes executing, the results are reported as quickly
@@ -749,6 +825,8 @@ 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
+  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
 * `--test-reporter` - Reporting is managed by the parent process
@@ -1570,6 +1648,9 @@ added:
   - v18.9.0
   - v16.19.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/63221
+    description: Added the `testTagFilters` option.
   - version: v24.14.0
     pr-url: https://github.com/nodejs/node/pull/61367
     description: Add the `env` option.
@@ -1656,6 +1737,10 @@ 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`.
   * `timeout` {number} A number of milliseconds the test execution will
     fail after.
     If unspecified, subtests inherit this value from their parent.
@@ -1799,6 +1884,9 @@ added:
   - v18.0.0
   - v16.17.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/63221
+    description: Added the `tags` option.
   - version:
     - v20.2.0
     - v18.17.0
@@ -1842,6 +1930,10 @@ changes:
   * `skip` {boolean|string} If truthy, the test is skipped. If a string is
     provided, that string is displayed in the test results as the reason for
     skipping the test. **Default:** `false`.
+  * `tags` {string\[]} An array of string labels associated with the test.
+    Used together with [`--experimental-test-tag-filter`][] to filter which
+    tests run. Tags inherit from suites to nested tests by union. See
+    [Test tags][]. **Default:** `[]`.
   * `todo` {boolean|string} If truthy, the test marked as `TODO`. If a string
     is provided, that string is displayed in the test results as the reason why
     the test is `TODO`. **Default:** `false`.
@@ -3425,6 +3517,9 @@ Emitted when code coverage is enabled and all tests have completed.
     `undefined` if the test was run through the REPL.
   * `name` {string} The test name.
   * `nesting` {number} The nesting level of the test.
+  * `tags` {string\[]} The flattened lowercased tags declared on the test
+    and its ancestor suites, in declaration order. Empty for untagged tests.
+    See [Test tags][].
   * `testId` {number} A numeric identifier for this test instance, unique
     within the test file's process. Consistent across all events for the same
     test instance, enabling reliable correlation in custom reporters.
@@ -3448,6 +3543,9 @@ The corresponding declaration ordered events are `'test:pass'` and `'test:fail'`
     `undefined` if the test was run through the REPL.
   * `name` {string} The test name.
   * `nesting` {number} The nesting level of the test.
+  * `tags` {string\[]} The flattened lowercased tags declared on the test
+    and its ancestor suites, in declaration order. Empty for untagged tests.
+    See [Test tags][].
   * `testId` {number} A numeric identifier for this test instance, unique
     within the test file's process. Consistent across all events for the same
     test instance, enabling reliable correlation in custom reporters.
@@ -3489,6 +3587,9 @@ defined.
     `undefined` if the test was run through the REPL.
   * `name` {string} The test name.
   * `nesting` {number} The nesting level of the test.
+  * `tags` {string\[]} The flattened lowercased tags declared on the test
+    and its ancestor suites, in declaration order. Empty for untagged tests.
+    See [Test tags][].
   * `testId` {number} A numeric identifier for this test instance, unique
     within the test file's process. Consistent across all events for the same
     test instance, enabling reliable correlation in custom reporters.
@@ -3515,6 +3616,9 @@ Emitted when a test is enqueued for execution.
     `undefined` if the test was run through the REPL.
   * `name` {string} The test name.
   * `nesting` {number} The nesting level of the test.
+  * `tags` {string\[]} The flattened lowercased tags declared on the test
+    and its ancestor suites, in declaration order. Empty for untagged tests.
+    See [Test tags][].
   * `testId` {number} A numeric identifier for this test instance, unique
     within the test file's process. Consistent across all events for the same
     test instance, enabling reliable correlation in custom reporters.
@@ -3572,6 +3676,9 @@ since the parent runner only knows about file-level tests. When using
     `undefined` if the test was run through the REPL.
   * `name` {string} The test name.
   * `nesting` {number} The nesting level of the test.
+  * `tags` {string\[]} The flattened lowercased tags declared on the test
+    and its ancestor suites, in declaration order. Empty for untagged tests.
+    See [Test tags][].
   * `testId` {number} A numeric identifier for this test instance, unique
     within the test file's process. Consistent across all events for the same
     test instance, enabling reliable correlation in custom reporters.
@@ -3611,6 +3718,9 @@ defined.
     `undefined` if the test was run through the REPL.
   * `name` {string} The test name.
   * `nesting` {number} The nesting level of the test.
+  * `tags` {string\[]} The flattened lowercased tags declared on the test
+    and its ancestor suites, in declaration order. Empty for untagged tests.
+    See [Test tags][].
   * `testId` {number} A numeric identifier for this test instance, unique
     within the test file's process. Consistent across all events for the same
     test instance, enabling reliable correlation in custom reporters.
@@ -4114,6 +4224,20 @@ The attempt number of the test. This value is zero-based, so the first attempt i
 the second attempt is `1`, and so on. This property is useful in conjunction with the
 `--test-rerun-failures` option to determine which attempt the test is currently running.
 
+### `context.tags`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1.0 - Early development
+
+* Type: {string\[]}
+
+A frozen array of the test's flattened lowercased tags, in declaration
+order, including any tags inherited from ancestor suites. Empty when the
+test has no tags. See [Test tags][].
+
 ### `context.workerId`
 
 <!-- YAML
@@ -4329,6 +4453,9 @@ added:
   - v18.0.0
   - v16.17.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/63221
+    description: Added the `tags` option.
   - version:
     - v18.8.0
     - v16.18.0
@@ -4359,6 +4486,10 @@ changes:
   * `skip` {boolean|string} If truthy, the test is skipped. If a string is
     provided, that string is displayed in the test results as the reason for
     skipping the test. **Default:** `false`.
+  * `tags` {string\[]} An array of string labels associated with the subtest.
+    Used together with [`--experimental-test-tag-filter`][] to filter which
+    tests run. Tags inherit from the parent test or suite by union. See
+    [Test tags][]. **Default:** `[]`.
   * `todo` {boolean|string} If truthy, the test marked as `TODO`. If a string
     is provided, that string is displayed in the test results as the reason why
     the test is `TODO`. **Default:** `false`.
@@ -4507,8 +4638,10 @@ test.describe('my suite', (suite) => {
 ```
 
 [TAP]: https://testanything.org/
+[Test tags]: #test-tags
 [`--experimental-test-coverage`]: cli.md#--experimental-test-coverage
 [`--experimental-test-module-mocks`]: cli.md#--experimental-test-module-mocks
+[`--experimental-test-tag-filter`]: cli.md#--experimental-test-tag-filtertag
 [`--import`]: cli.md#--importmodule
 [`--no-strip-types`]: cli.md#--no-strip-types
 [`--test-concurrency`]: cli.md#--test-concurrency
@@ -4534,6 +4667,7 @@ test.describe('my suite', (suite) => {
 [`assert.throws`]: assert.md#assertthrowsfn-error-message
 [`context.diagnostic`]: #contextdiagnosticmessage
 [`context.skip`]: #contextskipmessage
+[`context.tags`]: #contexttags
 [`context.todo`]: #contexttodomessage
 [`describe()`]: #describename-options-fn
 [`diagnostics_channel`]: diagnostics_channel.md
 
@@ -222,6 +222,10 @@ Disable support for loading ECMAScript modules with require().
 .It Fl -no-strip-types
 Disable type-stripping for TypeScript files.
 .
+.It Fl -experimental-test-tag-filter Ar tag
+Run only tests whose tag set contains \fItag\fR. May be specified multiple
+times; tests must contain every filter to run.
+.
 .It Fl -experimental-vm-modules
 Enable experimental ES module support in VM module.
 .
 
@@ -47,6 +47,7 @@ function createTestTree(rootTestOptions, globalOptions) {
     globalOptions.testSkipPatterns;
   const isFilteringByOnly = (globalOptions.isolation === 'process' || process.env.NODE_TEST_CONTEXT) ?
     globalOptions.only : true;
+  const isFilteringByTags = globalOptions.testTagFilters != null;
   const harness = {
     __proto__: null,
     buildPromise: buildPhaseDeferred.promise,
@@ -76,6 +77,7 @@ function createTestTree(rootTestOptions, globalOptions) {
     previousRuns: null,
     isFilteringByName,
     isFilteringByOnly,
+    isFilteringByTags,
     async runBootstrap() {
       if (globalSetupExecuted) {
         return PromiseResolve();
Original file line number	Diff line number	Diff line change
`@@ -222,6 +222,10 @@ Disable support for loading ECMAScript modules with require().`
`222`	`222`	`.It Fl -no-strip-types`
`223`	`223`	`Disable type-stripping for TypeScript files.`
`224`	`224`	`.`
	`225`	`+.It Fl -experimental-test-tag-filter Ar tag`
	`226`	`+Run only tests whose tag set contains \fItag\fR. May be specified multiple`
	`227`	`+times; tests must contain every filter to run.`
	`228`	`+.`
`225`	`229`	`.It Fl -experimental-vm-modules`
`226`	`230`	`Enable experimental ES module support in VM module.`
`227`	`231`	`.`