test_runner: expose worker ID for concurrent test execution

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

Author: thisalihassan

doc/api/cli.md

@@ -3830,6 +3830,26 @@ If `value` equals `'child'`, test reporter options will be overridden and test
 output will be sent to stdout in the TAP format. If any other value is provided,
 Node.js makes no guarantees about the reporter format used or its stability.
 
+### `NODE_TEST_WORKER_ID=value`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+The unique identifier (from `1` to `N`) of the worker running the current test
+file when using the test runner with concurrent test execution. This variable
+is automatically set by the test runner and should not be manually configured.
+
+When running tests with `--test-isolation=process` (the default), each test
+file runs in a separate child process and `value` will be a number from `1` to
+`N`, where `N` is the number of concurrent workers. When running with
+`--test-isolation=none`, all tests run in the same process and `value` is
+always `'1'`.
+
+This value can be used to allocate separate resources for each test worker,
+such as unique database connections or server ports, to avoid conflicts during
+concurrent test execution.
+
 ### `NODE_TLS_REJECT_UNAUTHORIZED=value`
 
 If `value` equals `'0'`, certificate validation is disabled for TLS connections.

doc/api/test.md

@@ -3720,6 +3720,39 @@ added: v25.0.0
 
 Number of times the test has been attempted.
 
+### `context.workerId`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {number|undefined}
+
+The unique identifier of the worker running the current test file. This value is
+derived from the `NODE_TEST_WORKER_ID` environment variable. When running tests
+with `--test-isolation=process` (the default), each test file runs in a separate
+child process and is assigned a worker ID from 1 to N, where N is the number of
+concurrent workers. When running with `--test-isolation=none`, all tests run in
+the same process and the worker ID is always 1. This value is `undefined` when
+not running in a test context.
+
+This property is useful for splitting resources (like database connections or
+server ports) across concurrent test files:
+
+```mjs
+import { test } from 'node:test';
+import { process } from 'node:process';
+
+test('database operations', async (t) => {
+  // Worker ID is available via context
+  console.log(`Running in worker ${t.workerId}`);
+
+  // Or via environment variable (available at import time)
+  const workerId = process.env.NODE_TEST_WORKER_ID;
+  // Use workerId to allocate separate resources per worker
+});
+```
+
 ### `context.plan(count[,options])`
 
 <!-- YAML

lib/internal/test_runner/runner.js

@@ -23,6 +23,7 @@ const {
   SafePromiseAllReturnVoid,
   SafePromiseAllSettledReturnVoid,
   SafeSet,
+  String,
   StringPrototypeIndexOf,
   StringPrototypeSlice,
   StringPrototypeStartsWith,
@@ -117,6 +118,31 @@ const kCanceledTests = new SafeSet()
 
 let kResistStopPropagation;
 
+// Worker ID pool management for concurrent test execution
+class WorkerIdPool {
+  #availableIds = [];
+  #nextId = 1;
+  #maxConcurrency;
+
+  constructor(maxConcurrency) {
+    this.#maxConcurrency = maxConcurrency || 1;
+  }
+
+  acquire() {
+    if (this.#availableIds.length > 0) {
+      return ArrayPrototypeShift(this.#availableIds);
+    }
+    if (this.#nextId <= this.#maxConcurrency) {
+      return this.#nextId++;
+    }
+    return 1; // Fallback if pool is exhausted
+  }
+
+  release(id) {
+    ArrayPrototypePush(this.#availableIds, id);
+  }
+}
+
 function createTestFileList(patterns, cwd) {
   const hasUserSuppliedPattern = patterns != null;
   if (!patterns || patterns.length === 0) {
@@ -404,6 +430,15 @@ function runTestFile(path, filesWatcher, opts) {
     const args = getRunArgs(path, opts);
     const stdio = ['pipe', 'pipe', 'pipe'];
     const env = { __proto__: null, ...process.env, NODE_TEST_CONTEXT: 'child-v8' };
+
+    // Acquire a worker ID from the pool for process isolation mode
+    let workerId;
+    if (opts.workerIdPool) {
+      workerId = opts.workerIdPool.acquire();
+      env.NODE_TEST_WORKER_ID = String(workerId);
+      debug('Assigned worker ID %d to test file: %s', workerId, path);
+    }
+
     if (watchMode) {
       stdio.push('ipc');
       env.WATCH_REPORT_DEPENDENCIES = '1';
@@ -460,6 +495,11 @@ function runTestFile(path, filesWatcher, opts) {
       finished(child.stdout, { __proto__: null, signal: t.signal }),
     ]);
 
+    // Release worker ID back to the pool
+    if (workerId !== undefined && opts.workerIdPool) {
+      opts.workerIdPool.release(workerId);
+    }
+
     if (watchMode) {
       filesWatcher.runningProcesses.delete(path);
       filesWatcher.runningSubtests.delete(path);
@@ -747,6 +787,26 @@ function run(options = kEmptyObject) {
   let postRun;
   let filesWatcher;
   let runFiles;
+
+  // Create worker ID pool for concurrent test execution.
+  // Use concurrency from globalOptions which has been processed by parseCommandLine().
+  const effectiveConcurrency = globalOptions.concurrency ?? concurrency;
+  let maxConcurrency = 1;
+  if (effectiveConcurrency === true) {
+    // Default concurrency - use number of test files as max
+    maxConcurrency = testFiles.length;
+  } else if (typeof effectiveConcurrency === 'number') {
+    maxConcurrency = effectiveConcurrency;
+  }
+  const workerIdPool = new WorkerIdPool(maxConcurrency);
+  debug(
+    'Created worker ID pool with max concurrency: %d, ' +
+    'effectiveConcurrency: %s, testFiles: %d',
+    maxConcurrency,
+    effectiveConcurrency,
+    testFiles.length,
+  );
+
   const opts = {
     __proto__: null,
     root,
@@ -763,6 +823,7 @@ function run(options = kEmptyObject) {
     argv,
     execArgv,
     rerunFailuresFilePath,
+    workerIdPool: isolation === 'process' ? workerIdPool : null,
   };
 
   if (isolation === 'process') {
@@ -789,6 +850,10 @@ function run(options = kEmptyObject) {
       });
     };
   } else if (isolation === 'none') {
+    // For isolation=none, set worker ID to 1 in the current process
+    process.env.NODE_TEST_WORKER_ID = '1';
+    debug('Set NODE_TEST_WORKER_ID=1 for isolation=none');
+
     if (watch) {
       const absoluteTestFiles = ArrayPrototypeMap(testFiles, (file) => (isAbsolute(file) ? file : resolve(cwd, file)));
       filesWatcher = watchFiles(absoluteTestFiles, opts);

lib/internal/test_runner/test.js

@@ -284,6 +284,11 @@ class TestContext {
     return this.#test.attempt ?? 0;
   }
 
+  get workerId() {
+    const envWorkerId = process.env.NODE_TEST_WORKER_ID;
+    return envWorkerId !== undefined ? Number(envWorkerId) : undefined;
+  }
+
   diagnostic(message) {
     this.#test.diagnostic(message);
   }

test/fixtures/test-runner/worker-id/test-1.mjs

@@ -0,0 +1,26 @@
+import { test } from 'node:test';
+
+test('worker ID is available as environment variable', (t) => {
+	const workerId = process.env.NODE_TEST_WORKER_ID;
+	if (workerId === undefined) {
+		throw new Error('NODE_TEST_WORKER_ID should be defined');
+	}
+
+	const id = Number(workerId);
+	if (isNaN(id) || id < 1) {
+		throw new Error(`Invalid worker ID: ${workerId}`);
+	}
+});
+
+test('worker ID is available via context', (t) => {
+	const workerId = t.workerId;
+	const envWorkerId = process.env.NODE_TEST_WORKER_ID;
+
+	if (workerId === undefined) {
+		throw new Error('context.workerId should be defined');
+	}
+
+	if (workerId !== Number(envWorkerId)) {
+		throw new Error(`context.workerId (${workerId}) should match NODE_TEST_WORKER_ID (${envWorkerId})`);
+	}
+});

test/fixtures/test-runner/worker-id/test-2.mjs

@@ -0,0 +1,26 @@
+import { test } from 'node:test';
+
+test('worker ID is available as environment variable', (t) => {
+	const workerId = process.env.NODE_TEST_WORKER_ID;
+	if (workerId === undefined) {
+		throw new Error('NODE_TEST_WORKER_ID should be defined');
+	}
+
+	const id = Number(workerId);
+	if (isNaN(id) || id < 1) {
+		throw new Error(`Invalid worker ID: ${workerId}`);
+	}
+});
+
+test('worker ID is available via context', (t) => {
+	const workerId = t.workerId;
+	const envWorkerId = process.env.NODE_TEST_WORKER_ID;
+
+	if (workerId === undefined) {
+		throw new Error('context.workerId should be defined');
+	}
+
+	if (workerId !== Number(envWorkerId)) {
+		throw new Error(`context.workerId (${workerId}) should match NODE_TEST_WORKER_ID (${envWorkerId})`);
+	}
+});

test/fixtures/test-runner/worker-id/test-3.mjs

@@ -0,0 +1,26 @@
+import { test } from 'node:test';
+
+test('worker ID is available as environment variable', (t) => {
+	const workerId = process.env.NODE_TEST_WORKER_ID;
+	if (workerId === undefined) {
+		throw new Error('NODE_TEST_WORKER_ID should be defined');
+	}
+
+	const id = Number(workerId);
+	if (isNaN(id) || id < 1) {
+		throw new Error(`Invalid worker ID: ${workerId}`);
+	}
+});
+
+test('worker ID is available via context', (t) => {
+	const workerId = t.workerId;
+	const envWorkerId = process.env.NODE_TEST_WORKER_ID;
+
+	if (workerId === undefined) {
+		throw new Error('context.workerId should be defined');
+	}
+
+	if (workerId !== Number(envWorkerId)) {
+		throw new Error(`context.workerId (${workerId}) should match NODE_TEST_WORKER_ID (${envWorkerId})`);
+	}
+});