test_runner: add experimental tag-based test filtering by atlowChemi · Pull Request #63054 · nodejs/node

atlowChemi · 2026-04-30T16:29:26Z

Summary

Adds an experimental tag-filter feature to node:test, mirroring the
boolean-expression filter shape that other test runners have established.

Authoring: a tags: string[] option on test() / it() / suite() /
describe(). Tags inherit from suites to nested tests by union.
Filtering: --experimental-test-tag-filter='<expr>' CLI flag and
testTagFilters: string | string[] option on run(). Repeatable;
multiple expressions AND together. Composes by AND with
--test-name-pattern, --test-skip-pattern, and .only.
Expression grammar: and/&&, or/||, not/!, parentheses,
* wildcards. Standard precedence (not > and > or).
Reporter: tags: string[] field added to the six testId-keyed
events. Built-in reporters ignore the field for v1; custom reporters
can read it.
Context: t.tags accessor on TestContext exposes the test's
flattened tag set as a frozen array.

Prior art

Tag filtering is well-trodden ground in the JS testing ecosystem. The
expression syntax here is closest to Vitest's, which itself follows the
boolean/wildcard pattern other tools converged on:

Vitest test tags — https://vitest.dev/guide/test-tags
mocha-tags — https://www.npmjs.com/package/mocha-tags
jest-runner-groups — https://www.npmjs.com/package/jest-runner-groups
jest-tags — https://github.com/gitbrik/jest-tags

Vitest additionally lets a tag carry per-test config overrides such as
timeout or retry (with priority resolution between overlapping
tags). That's intentionally out of scope for this PR — landing it
would commit to a separate tags: [{ name, timeout, retry, priority }]
config surface that's orthogonal to filtering. It can be layered on
later without breaking the union-inheritance semantics this PR
establishes.

nodejs-github-bot · 2026-04-30T16:29:32Z

Review requested:

@nodejs/config
@nodejs/test_runner

MoLow · 2026-04-30T17:18:39Z

+declare tags via the `tags` option on `test()`, `it()`, `suite()`, or
+`describe()`. Tags inherit from suites to nested tests by union.
+
+The expression supports boolean operators (`and`/`&&`, `or`/`||`,


isnt there a better way then this tag filtering syntax?.
i.e accept in the run method a string[] or function(string) => boolean and in case you want some complex logic - use the run api without the node cli - That makes much more sense to me

that is more consistent to our name filter flag

Without the boolean syntax this feature mostly collapses into name-pattern...

The goal (I had in mind) of this feature is to introduce a easy (and common, see prior art) way to filter without the need for a programmatic API. Sure, you could already achieve complex filtering via run() API, but the goal here is to add a built-in logic for this.

Vitest, mocha-tags, and jest-runner-groups all expose such a boolean composition syntax.

Before I even saw Moshe's comment, I was thinking the same thing. But after a minute, I can see the use of it.

I know && and || align with javascript, but it seems a little long, and the simpler & and | look pretty straightforward to me (and aligns with others, like query params and old skool forum query syntax). What happens when you combine them though?

--experimental-test-tag-filter=foo&bar&qux|zed

Is that "foo and bar and (qux or zed)" or "(foo and bar and qux) or zed"? For some reason, my eyes see the former, but syntactically, it's usually the latter. IMO the original spec for syntax made a huge mistake not requiring parentheses when combining operators. If we support combining operators, I think parentheses should be required.

--experimental-test-tag-filter=(foo&bar&qux)|zed

--experimental-test-tag-filter=foo&bar&(qux|zed)

@JakobJingleheimer I feel that & vs && is not really "a little long", and I feel using & and | could be confusing with bitwise operators, while removing just a single character...

I considered that before posting: I think nobody would be confused here because bitwise is not appropriate.

&& vs & is a thought musing.

My bigger concern would be parens for combined operators.

thats why I think we should release a initial version that does not include this new langauge

codecov · 2026-04-30T18:06:08Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.06%. Comparing base (1fd4949) to head (853f715).

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #63054      +/-   ##
==========================================
+ Coverage   90.03%   90.06%   +0.02%     
==========================================
  Files         713      714       +1     
  Lines      224699   225345     +646     
  Branches    42473    42623     +150     
==========================================
+ Hits       202310   202959     +649     
+ Misses      14179    14172       -7     
- Partials     8210     8214       +4

Files with missing lines	Coverage Δ
lib/internal/test_runner/harness.js	`86.42% <100.00%> (+0.27%)`	⬆️
lib/internal/test_runner/runner.js	`93.93% <100.00%> (+0.26%)`	⬆️
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.19% <100.00%> (+1.60%)`	⬆️
src/node_options.cc	`76.63% <100.00%> (+0.02%)`	⬆️
src/node_options.h	`97.98% <ø> (ø)`

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

JakobJingleheimer · 2026-04-30T20:18:32Z

Sweet! I'll try to carve out time on Saturday to reciew

JakobJingleheimer

Sorry for the delay. GitHub is having a bit of a stroke. Every time I try to add a comment to the review "Something went wrong" and I have to copy it, reload, paste, and try a couple more times.

I'll try to finish tomorrow (I got through 10 of 18 files, which doesn't include tag_filter.js).

JakobJingleheimer · 2026-05-06T18:08:28Z

+declare tags via the `tags` option on `test()`, `it()`, `suite()`, or
+`describe()`. Tags inherit from suites to nested tests by union.
+
+The expression supports boolean operators (`and`/`&&`, `or`/`||`,


Before I even saw Moshe's comment, I was thinking the same thing. But after a minute, I can see the use of it.

I know && and || align with javascript, but it seems a little long, and the simpler & and | look pretty straightforward to me (and aligns with others, like query params and old skool forum query syntax). What happens when you combine them though?

--experimental-test-tag-filter=foo&bar&qux|zed

Is that "foo and bar and (qux or zed)" or "(foo and bar and qux) or zed"? For some reason, my eyes see the former, but syntactically, it's usually the latter. IMO the original spec for syntax made a huge mistake not requiring parentheses when combining operators. If we support combining operators, I think parentheses should be required.

--experimental-test-tag-filter=(foo&bar&qux)|zed

--experimental-test-tag-filter=foo&bar&(qux|zed)

JakobJingleheimer · 2026-05-06T18:14:09Z

+### 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


Suggested change

Tags inherit from a suite to its child tests by union — a test inside a

Tags inherit from a suite to its child tests by union—a test inside a

Why? (genuinely asking, English is not my first language)

The second part is an interjection, like you're interrupting yourself to clarify something. That's separated by an emdash. Basically what you did is correct except you used the wrong character (and an emdash is not padded by whitespace—it spears the two phrases together like a kebab).

I used it there as another example of how it works 🙂

Basically:

Hyphen combines words (after-thought)

Endash combines numbers (2–3)

Emdash combines phrases (but not always—sometimes a colon or semicolon is more appropriate)

JakobJingleheimer · 2026-05-06T18:19:07Z

+
+Untagged tests behave as if they have an empty tag set. As a result:
+
+* Any include expression (a tag, wildcard, `and`, or `or`) is **false**


I think

Suggested change

* Any include expression (a tag, wildcard, `and`, or `or`) is **false**

* Any included expression (a tag, wildcard, `and`, or `or`) is **false**

Otherwise, I don't understand what it intends.

JakobJingleheimer · 2026-05-06T18:20:57Z

+* Any include expression (a tag, wildcard, `and`, or `or`) is **false**
+  for an untagged test, so untagged tests are excluded under any positive
+  filter.
+* `not X` is **true** for an untagged test, so excluding tags does not
+  accidentally remove untagged tests.


This is generally difficult to follow. I think a table of examples would be more straightforward.

JakobJingleheimer · 2026-05-06T18:33:45Z

+        if (!mergedSet.has(ownTags[i])) {
+          ArrayPrototypePush(merged, ownTags[i]);
+          mergedSet.add(ownTags[i]);
+        }


Nit: This is a bit unexpected—Set is already unique (SafeSet surely already handles this "doesn't have"). I would expect something like two (Safe)Sets, one full and one subset. If context.tags is accessed, then pay the Array.from cost JIT.

JakobJingleheimer · 2026-05-06T18:35:02Z

-  fail(nesting, loc, testNumber, name, details, directive, testId) {
+  fail(nesting, loc, testNumber, name, details, directive, testId, tags) {


General comment: this is getting to be a bit of a junk-drawer of arguments 😬

I agree, perhaps we could open a good first issue Issues that are suitable for first-time contributors. issue to handle this

atlowChemi · 2026-05-06T19:11:09Z

GitHub is having a bit of a stroke.

@JakobJingleheimer github having issues? no way 😂

Add a `tags` option on `test()` / `it()` / `suite()` / `describe()` and the `--experimental-test-tag-filter` CLI flag (plus the `testTagFilters` option on `run()`) that accepts a Vitest-style boolean expression with `and`/`&&`, `or`/`||`, `not`/`!`, parentheses, and `*` wildcards. Tags inherit from suite to child tests by union. Filtering composes by AND with name patterns, skip patterns, and `.only`. Untagged tests are filtered out under any include expression; `not X` is true against an untagged test. Tag matching is case-insensitive with lowercase canonical storage. Signed-off-by: atlowChemi <chemi@atlow.co.il>

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 Apr 30, 2026

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

MoLow reviewed Apr 30, 2026

View reviewed changes

JakobJingleheimer added this to Test Runner Board Apr 30, 2026

TheOneTheOnlyJJ reviewed May 1, 2026

View reviewed changes

Comment thread test/parallel/test-runner-tag-filter-cli.mjs Outdated

atlowChemi force-pushed the test_runner-tag-filter branch 3 times, most recently from 3591324 to 31a7737 Compare May 5, 2026 16:47

JakobJingleheimer reviewed May 6, 2026

View reviewed changes

atlowChemi force-pushed the test_runner-tag-filter branch from 31a7737 to 853f715 Compare May 7, 2026 19:13

	Tags inherit from a suite to its child tests by union — a test inside a
	Tags inherit from a suite to its child tests by union—a test inside a


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

		* Any include expression (a tag, wildcard, `and`, or `or`) is false

	* Any include expression (a tag, wildcard, `and`, or `or`) is false
	* Any included expression (a tag, wildcard, `and`, or `or`) is false

		fail(nesting, loc, testNumber, name, details, directive, testId) {
		fail(nesting, loc, testNumber, name, details, directive, testId, tags) {

Uh oh!

Conversation

atlowChemi commented Apr 30, 2026

Summary

Prior art

Uh oh!

nodejs-github-bot commented Apr 30, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

JakobJingleheimer commented Apr 30, 2026

Uh oh!

Uh oh!

JakobJingleheimer left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JakobJingleheimer May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

atlowChemi commented May 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

codecov Bot commented Apr 30, 2026 •

edited

Loading

JakobJingleheimer May 6, 2026 •

edited

Loading