test_runner: expose worker ID for concurrent test execution

[thisalihassan]

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]

Review requested:

• @nodejs/test_runner

[JakobJingleheimer]

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]

I think you can simplify this:

Suggested change

	return envWorkerId !== undefined ? Number(envWorkerId) : undefined;
	return Number(envWorkerId) || undefined;

Number(undefined) → NaN (falsy)

envWorkerId should never be zero, so I that should be safe.

[aduh95]

Also that suggestion correctly handles empty string same as not defined, which is the convention for env variables

[thisalihassan]

Thanks for pointing this out @JakobJingleheimer @aduh95 really appreciate the feedback

[thisalihassan]

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]

Codecov Report

❌ Patch coverage is 92.85714% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.54%. Comparing base (ec49a09) to head (897df8b).
⚠️ Report is 7 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   88.51%   88.54%   +0.02%     
==========================================
  Files         704      704              
  Lines      208797   208870      +73     
  Branches    40310    40330      +20     
==========================================
+ Hits       184820   184938     +118     
+ Misses      15961    15911      -50     
- Partials     8016     8021       +5     

Files with missing lines	Coverage Δ
lib/internal/test_runner/test.js	97.30% <80.00%> (-0.05%)	⬇️
lib/internal/test_runner/runner.js	93.00% <94.11%> (+0.06%)	⬆️

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