test_runner: add tags option and tag-name filter by atlowChemi · Pull Request #63221 · nodejs/node

atlowChemi · 2026-05-10T06:29:31Z

Summary

Add tags array option to test(), it(), suite(), describe()
with case-insensitive canonicalization and union inheritance from suites.
Expose tags on reporter events (test:start, test:pass, etc.) and
via context.tags.
Add --experimental-test-tag-filter=<tag> and testTagFilters for
literal tag-name filtering. Multi-occurrence composes by AND.
Gated behind a one-shot ExperimentalWarning.

Extracts the tagging mechanism from #63054 so the boolean expression
DSL can be discussed separately. The filter syntax here is a single
literal tag name.

One known caveat: tag values currently accept any non-empty string.
Adding the DSL later will require reserving operator characters
(& | ! ( ) *) and the words and/or/not, which would be a
breaking change. Acceptable since this ships at Stability 1.0
(Early development).

nodejs-github-bot · 2026-05-10T06:29:37Z

Review requested:

@nodejs/config
@nodejs/test_runner

codecov · 2026-05-10T07:57:46Z

Codecov Report

❌ Patch coverage is 98.83721% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.04%. Comparing base (0a60e90) to head (28beec8).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/test_runner/runner.js	90.32%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #63221      +/-   ##
==========================================
+ Coverage   90.02%   90.04%   +0.02%     
==========================================
  Files         713      714       +1     
  Lines      224950   225192     +242     
  Branches    42530    42570      +40     
==========================================
+ Hits       202513   202777     +264     
+ Misses      14220    14186      -34     
- Partials     8217     8229      +12

Files with missing lines	Coverage Δ
lib/internal/test_runner/harness.js	`86.42% <100.00%> (+0.27%)`	⬆️
lib/internal/test_runner/tag_filter.js	`100.00% <100.00%> (ø)`
lib/internal/test_runner/test.js	`96.99% <100.00%> (+0.08%)`	⬆️
lib/internal/test_runner/tests_stream.js	`88.65% <100.00%> (+0.42%)`	⬆️
lib/internal/test_runner/utils.js	`65.23% <100.00%> (+1.65%)`	⬆️
src/node_options.cc	`76.63% <100.00%> (+0.12%)`	⬆️
src/node_options.h	`97.98% <ø> (ø)`
lib/internal/test_runner/runner.js	`93.57% <90.32%> (-0.10%)`	⬇️

... and 27 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

MoLow · 2026-05-10T10:26:25Z

    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,


should we accept a function as well?

I don't think so.
That should be discussed in a follow up, as part of the DSL addition, IMHO

Adds a `tags` option to test(), it(), suite(), and describe() that accepts an array of string labels. Tags are canonicalized to lowercase and inherited from suites to nested tests by union. Reporter events expose the tag set on every test, and TestContext exposes the test's tags via `context.tags`. Filtering is done by literal tag name through the new `--experimental-test-tag-filter=<tag>` flag (or `testTagFilters` on run()). The flag may be specified more than once; tests must contain every filter to run. Untagged tests are excluded under any positive filter. The tagging mechanism is gated behind a one-shot ExperimentalWarning. Signed-off-by: atlowChemi <chemi@atlow.co.il>

atlowChemi · 2026-05-11T08:48:09Z

@MoLow @pmarchini I rebased to include a CI fix for the windows Jenkins job. Could you re-approve?

nodejs-github-bot · 2026-05-11T10:10:23Z

CI: https://ci.nodejs.org/job/node-test-pull-request/73364/

avivkeller · 2026-05-11T11:42:34Z

+    if (testTagFilters.length === 0) {
+      testTagFilters = null;
+    } else {
+      emitExperimentalWarning('Test tags');


Suggested change

emitExperimentalWarning('Test tags');

emitExperimentalWarning('Test tag filtering');

@avivkeller I don't agree with this, since this is not only the filtering which is experimental, but also the inheritance between suites/tests, the property on the test's context etc.

avivkeller · 2026-05-11T11:43:05Z


+    const tagFilterFlag = getOptionValue('--experimental-test-tag-filter');
+    if (tagFilterFlag?.length > 0) {
+      emitExperimentalWarning('Test tags');


Suggested change

emitExperimentalWarning('Test tags');

emitExperimentalWarning('Test tag filtering');

nodejs-github-bot added lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run. labels May 10, 2026

atlowChemi mentioned this pull request May 10, 2026

test_runner: add experimental tag-based test filtering #63054

Open

atlowChemi force-pushed the test_runner-tags branch from 4f4407b to 3d18efb Compare May 10, 2026 06:34

atlowChemi added the test_runner Issues and PRs related to the test runner subsystem. label May 10, 2026

atlowChemi requested review from JakobJingleheimer and MoLow May 10, 2026 06:39

This comment was marked as spam.

Sign in to view

MoLow reviewed May 10, 2026

View reviewed changes

MoLow approved these changes May 10, 2026

View reviewed changes

atlowChemi added the request-ci Add this label to start a Jenkins CI on a PR. label May 10, 2026

github-actions Bot removed the request-ci Add this label to start a Jenkins CI on a PR. label May 10, 2026

This comment was marked as outdated.

Sign in to view

pmarchini approved these changes May 11, 2026

View reviewed changes

atlowChemi force-pushed the test_runner-tags branch from 3d18efb to 28beec8 Compare May 11, 2026 08:47

This comment was marked as outdated.

Sign in to view

pmarchini approved these changes May 11, 2026

View reviewed changes

atlowChemi added the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label May 11, 2026

avivkeller approved these changes May 11, 2026

View reviewed changes

	emitExperimentalWarning('Test tags');
	emitExperimentalWarning('Test tag filtering');

Uh oh!

Conversation

atlowChemi commented May 10, 2026

Summary

Uh oh!

nodejs-github-bot commented May 10, 2026

Uh oh!

codecov Bot commented May 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

MoLow May 10, 2026

Choose a reason for hiding this comment

Uh oh!

atlowChemi May 10, 2026

Choose a reason for hiding this comment

Uh oh!

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

atlowChemi commented May 11, 2026

Uh oh!

This comment was marked as outdated.

nodejs-github-bot commented May 11, 2026

Uh oh!

avivkeller May 11, 2026

Choose a reason for hiding this comment

Uh oh!

atlowChemi May 11, 2026

Choose a reason for hiding this comment

Uh oh!

avivkeller May 11, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

codecov Bot commented May 10, 2026 •

edited

Loading