Skip to content

test_runner: expose worker ID for concurrent test execution#61394

Merged
nodejs-github-bot merged 1 commit intonodejs:mainfrom
thisalihassan:test-runner-worker-id
Feb 24, 2026
Merged

test_runner: expose worker ID for concurrent test execution#61394
nodejs-github-bot merged 1 commit intonodejs:mainfrom
thisalihassan:test-runner-worker-id

Conversation

@thisalihassan
Copy link
Contributor

This adds support for identifying which worker is running a test file when tests execute concurrently, similar to JEST_WORKER_ID in Jest, VITEST_POOL_ID in Vitest, and MOCHA_WORKER_ID in Mocha.

When running with --test-isolation=process (default), each test file runs in a separate child process and receives a unique worker ID from 1 to N. When running with --test-isolation=none, all tests run in the same process and the worker ID is always 1.

This enables users to allocate separate resources (databases, ports, etc.) for each test worker to avoid conflicts during concurrent execution.

Changes:

  • Add WorkerIdPool class to manage worker ID allocation and reuse
  • Set NODE_TEST_WORKER_ID environment variable for child processes
  • Add context.workerId getter to TestContext class
  • Add tests for worker ID functionality
  • Add documentation for NODE_TEST_WORKER_ID and context.workerId

Fixes: #55842

@nodejs-github-bot
Copy link
Collaborator

Review requested:

  • @nodejs/test_runner

@nodejs-github-bot nodejs-github-bot added needs-ci PRs that need a full CI run. test_runner Issues and PRs related to the test runner subsystem. labels Jan 15, 2026
Copy link
Member

@JakobJingleheimer JakobJingleheimer left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm still not sure this feature is necessary since it's easily facilitated in userland. But if it helps ease adoption from Jest and Mocha 🤔

@thisalihassan
Copy link
Contributor Author

I'm still not sure this feature is necessary since it's easily facilitated in userland. But if it helps ease adoption from Jest and Mocha 🤔

@JakobJingleheimer Thanks for taking a look!

I totally get the hesitation about adding to core.

The main issue is that while this is possible in userland, the workarounds are usually pretty messy or come with big trade-offs. Most people trying to migrate from Jest hit one of two walls:

Unstable IDs: They try to use threadId/PID but that breaks because the IDs keep climbing (1, 2, 3 -> 99) as workers recycle, so you can't map them to a fixed set of databases

Manual Sharding: They run multiple node --test processes to pass custom env vars but then they lose the loadbalancing of the native runner (one process finishes fast and sits idle while another is slammed).

@codecov
Copy link

codecov bot commented Jan 16, 2026

Codecov Report

❌ Patch coverage is 92.85714% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.76%. Comparing base (f6464c5) to head (5cf226d).
⚠️ Report is 173 commits behind head on main.

Files with missing lines Patch % Lines
lib/internal/test_runner/runner.js 94.11% 2 Missing and 1 partial ⚠️
lib/internal/test_runner/test.js 80.00% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main   #61394      +/-   ##
==========================================
- Coverage   89.76%   89.76%   -0.01%     
==========================================
  Files         673      673              
  Lines      203944   204000      +56     
  Branches    39191    39209      +18     
==========================================
+ Hits       183080   183112      +32     
  Misses      13194    13194              
- Partials     7670     7694      +24     
Files with missing lines Coverage Δ
lib/internal/test_runner/test.js 97.27% <80.00%> (-0.06%) ⬇️
lib/internal/test_runner/runner.js 93.17% <94.11%> (+0.05%) ⬆️

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

@thisalihassan thisalihassan force-pushed the test-runner-worker-id branch 2 times, most recently from 1fb7c1d to 897df8b Compare January 16, 2026 08:51
Copy link
Member

@mcollina mcollina left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@mcollina mcollina added request-ci Add this label to start a Jenkins CI on a PR. semver-minor PRs that contain new features and should be released in the next minor version. and removed request-ci Add this label to start a Jenkins CI on a PR. labels Jan 22, 2026
This adds support for identifying which worker is running a test file
when tests execute concurrently, similar to JEST_WORKER_ID in Jest,
VITEST_POOL_ID in Vitest, and MOCHA_WORKER_ID in Mocha.

When running with --test-isolation=process (default), each test file
runs in a separate child process and receives a unique worker ID from
1 to N. When running with --test-isolation=none, all tests run in the
same process and the worker ID is always 1.

This enables users to allocate separate resources (databases, ports,
etc.) for each test worker to avoid conflicts during concurrent
execution.

Changes:
- Add WorkerIdPool class to manage worker ID allocation and reuse
- Set NODE_TEST_WORKER_ID environment variable for child processes
- Add context.workerId getter to TestContext class
- Add tests for worker ID functionality
- Add documentation for context.workerId

Fixes: nodejs#55842
@thisalihassan
Copy link
Contributor Author

Resolved conflicts

@thisalihassan thisalihassan requested a review from aduh95 February 1, 2026 16:11
@thisalihassan
Copy link
Contributor Author

Hi @mcollina @pmarchini should we merge this PR?

@thisalihassan
Copy link
Contributor Author

Guys can we please merge this PR? @mcollina @aduh95 @pmarchini or request-ci? this PR has been sitting for a while

@JakobJingleheimer JakobJingleheimer added the request-ci Add this label to start a Jenkins CI on a PR. label Feb 24, 2026
@github-actions github-actions bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Feb 24, 2026
@nodejs-github-bot
Copy link
Collaborator

@JakobJingleheimer
Copy link
Member

@thisalihassan FYI: since you pushed new commits after the last CI run, CI has to be re-run (which I just triggered). What you were seeing green here are a subset of the full test suite that has to pass.

As long as no new commits are pushed, the checks listed on the PR will display the status of the full CI suite (it takes about an hour to run, and sometimes some parts need to be re-tried). I'll keep an eye on it until I go to bed in ~30 mins. If it's green tomorrow morning, I'll land the PR.

@JakobJingleheimer JakobJingleheimer added commit-queue Add this label to land a pull request using GitHub Actions. commit-queue-squash Add this label to instruct the Commit Queue to squash all the PR commits into the first one. labels Feb 24, 2026
@nodejs-github-bot nodejs-github-bot removed the commit-queue Add this label to land a pull request using GitHub Actions. label Feb 24, 2026
@nodejs-github-bot nodejs-github-bot merged commit 2ebe496 into nodejs:main Feb 24, 2026
70 checks passed
@nodejs-github-bot
Copy link
Collaborator

Landed in 2ebe496

@thisalihassan
Copy link
Contributor Author

ohh didn't know that, thanks for this information @JakobJingleheimer I am also keeping an eye over it

@JakobJingleheimer
Copy link
Member

The PR is already merged 😉

aduh95 pushed a commit that referenced this pull request Feb 28, 2026
This adds support for identifying which worker is running a test file
when tests execute concurrently, similar to JEST_WORKER_ID in Jest,
VITEST_POOL_ID in Vitest, and MOCHA_WORKER_ID in Mocha.

When running with --test-isolation=process (default), each test file
runs in a separate child process and receives a unique worker ID from
1 to N. When running with --test-isolation=none, all tests run in the
same process and the worker ID is always 1.

This enables users to allocate separate resources (databases, ports,
etc.) for each test worker to avoid conflicts during concurrent
execution.

Changes:
- Add WorkerIdPool class to manage worker ID allocation and reuse
- Set NODE_TEST_WORKER_ID environment variable for child processes
- Add context.workerId getter to TestContext class
- Add tests for worker ID functionality
- Add documentation for context.workerId

Fixes: #55842
PR-URL: #61394
Reviewed-By: Matteo Collina <[email protected]>
Reviewed-By: Pietro Marchini <[email protected]>
Reviewed-By: Jacob Smith <[email protected]>
nodejs-github-bot added a commit that referenced this pull request Mar 2, 2026
Notable changes:

build, doc:
  * use new api doc tooling (flakey5) #57343
sqlite:
  * (SEMVER-MINOR) add limits property to DatabaseSync (Mert Can Altin) #61298
src:
  * (SEMVER-MINOR) add C++ support for diagnostics channels (RafaelGSS) #61869
src,permission:
  * (SEMVER-MINOR) add --permission-audit (RafaelGSS) #61869
test_runner:
  * (SEMVER-MINOR) expose worker ID for concurrent test execution (Ali Hassan) #61394

PR-URL: #62073
richardlau pushed a commit that referenced this pull request Mar 2, 2026
Notable changes:

build, doc:
  * use new api doc tooling (flakey5) #57343
sqlite:
  * (SEMVER-MINOR) add limits property to DatabaseSync (Mert Can Altin) #61298
src:
  * (SEMVER-MINOR) add C++ support for diagnostics channels (RafaelGSS) #61869
src,permission:
  * (SEMVER-MINOR) add --permission-audit (RafaelGSS) #61869
test_runner:
  * (SEMVER-MINOR) expose worker ID for concurrent test execution (Ali Hassan) #61394

PR-URL: #62073
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

commit-queue-squash Add this label to instruct the Commit Queue to squash all the PR commits into the first one. needs-ci PRs that need a full CI run. semver-minor PRs that contain new features and should be released in the next minor version. test_runner Issues and PRs related to the test runner subsystem.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Expose an id for concurrent test runners (like JEST_WORKER_ID)

7 participants