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 context.workerId Fixes: #55842 PR-URL: #61394 Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Pietro Marchini <pietro.marchini94@gmail.com> Reviewed-By: Jacob Smith <jacob@frende.me>
nodejs · richardlau · Mar 3, 2026 · Feb 24, 2026 · Feb 22, 2026 · Feb 22, 2026
commit 0d97ec40442d139efc0e645ee36a9ebe9b5ca869
diff --git a/doc/api/test.md b/doc/api/test.md
@@ -3804,6 +3804,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

diff --git a/lib/internal/test_runner/runner.js b/lib/internal/test_runner/runner.js
@@ -15,6 +15,7 @@ const {
   ArrayPrototypeSlice,
   ArrayPrototypeSome,
   ArrayPrototypeSort,
+  MathMax,
   ObjectAssign,
   PromisePrototypeThen,
   PromiseWithResolvers,
@@ -23,6 +24,7 @@ const {
   SafePromiseAllReturnVoid,
   SafePromiseAllSettledReturnVoid,
   SafeSet,
+  String,
   StringPrototypeIndexOf,
   StringPrototypeSlice,
   StringPrototypeStartsWith,
@@ -33,6 +35,7 @@ const {
 
 const { spawn } = require('child_process');
 const { finished } = require('internal/streams/end-of-stream');
+const { availableParallelism } = require('os');
 const { resolve, sep, isAbsolute } = require('path');
 const { DefaultDeserializer, DefaultSerializer } = require('v8');
 const { getOptionValue, getOptionsAsFlagsFromBinding } = require('internal/options');
@@ -117,6 +120,21 @@ const kCanceledTests = new SafeSet()
 
 let kResistStopPropagation;
 
+// Worker ID pool management for concurrent test execution
+class WorkerIdPool {
+  #nextId = 0;
+  #maxConcurrency;
+
+  constructor(maxConcurrency) {
+    this.#maxConcurrency = maxConcurrency;
+  }
+
+  acquire() {
+    const id = (this.#nextId++ % this.#maxConcurrency) + 1;
+    return id;
+  }
+}
+
 function createTestFileList(patterns, cwd) {
   const hasUserSuppliedPattern = patterns != null;
   if (!patterns || patterns.length === 0) {
@@ -404,6 +422,15 @@ function runTestFile(path, filesWatcher, opts) {
     const args = getRunArgs(path, opts);
     const stdio = ['pipe', 'pipe', 'pipe'];
     const env = { __proto__: null, NODE_TEST_CONTEXT: 'child-v8', ...(opts.env || process.env) };
+
+    // 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';
@@ -769,6 +796,25 @@ 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) {
+    maxConcurrency = MathMax(availableParallelism() - 1, 1);
+  } 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,
@@ -786,6 +832,7 @@ function run(options = kEmptyObject) {
     execArgv,
     rerunFailuresFilePath,
     env,
+    workerIdPool: isolation === 'process' ? workerIdPool : null,
   };
 
   if (isolation === 'process') {
@@ -812,6 +859,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);

diff --git a/lib/internal/test_runner/test.js b/lib/internal/test_runner/test.js
@@ -285,6 +285,11 @@ class TestContext {
     return this.#test.attempt ?? 0;
   }
 
+  get workerId() {
+    const envWorkerId = process.env.NODE_TEST_WORKER_ID;
+    return Number(envWorkerId) || undefined;
+  }
+
   diagnostic(message) {
     this.#test.diagnostic(message);
   }

diff --git a/test/fixtures/test-runner/worker-id/test-1.mjs b/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})`);
+	}
+});
diff --git a/test/fixtures/test-runner/worker-id/test-2.mjs b/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})`);
+	}
+});
diff --git a/test/fixtures/test-runner/worker-id/test-3.mjs b/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})`);
+	}
+});
diff --git a/test/parallel/test-runner-worker-id.js b/test/parallel/test-runner-worker-id.js
@@ -0,0 +1,141 @@
+'use strict';
+require('../common');
+const fixtures = require('../common/fixtures');
+const assert = require('node:assert');
+const { spawnSync } = require('node:child_process');
+const { test } = require('node:test');
+
+test('NODE_TEST_WORKER_ID is set for concurrent test files', async () => {
+  const args = [
+    '--test',
+    fixtures.path('test-runner', 'worker-id', 'test-1.mjs'),
+    fixtures.path('test-runner', 'worker-id', 'test-2.mjs'),
+    fixtures.path('test-runner', 'worker-id', 'test-3.mjs'),
+  ];
+  const result = spawnSync(process.execPath, args, {
+    cwd: fixtures.path(),
+    env: { ...process.env }
+  });
+
+  assert.strictEqual(result.status, 0, `Test failed: ${result.stderr.toString()}`);
+});
+
+test('NODE_TEST_WORKER_ID is set with explicit concurrency', async () => {
+  const args = [
+    '--test',
+    '--test-concurrency=2',
+    fixtures.path('test-runner', 'worker-id', 'test-1.mjs'),
+    fixtures.path('test-runner', 'worker-id', 'test-2.mjs'),
+  ];
+  const result = spawnSync(process.execPath, args, {
+    cwd: fixtures.path(),
+    env: { ...process.env }
+  });
+
+  assert.strictEqual(result.status, 0, `Test failed: ${result.stderr.toString()}`);
+});
+
+test('NODE_TEST_WORKER_ID is 1 with concurrency=1', async () => {
+  const args = ['--test', '--test-concurrency=1', fixtures.path('test-runner', 'worker-id', 'test-1.mjs')];
+  const result = spawnSync(process.execPath, args, {
+    cwd: fixtures.path(),
+    env: { ...process.env }
+  });
+
+  assert.strictEqual(result.status, 0, `Test failed: ${result.stderr.toString()}`);
+});
+
+test('NODE_TEST_WORKER_ID with explicit isolation=process', async () => {
+  const args = [
+    '--test',
+    '--test-isolation=process',
+    fixtures.path('test-runner', 'worker-id', 'test-1.mjs'),
+    fixtures.path('test-runner', 'worker-id', 'test-2.mjs'),
+  ];
+  const result = spawnSync(process.execPath, args, {
+    cwd: fixtures.path(),
+    env: { ...process.env }
+  });
+
+  assert.strictEqual(result.status, 0, `Test failed: ${result.stderr.toString()}`);
+});
+
+test('NODE_TEST_WORKER_ID is 1 with isolation=none', async () => {
+  const args = [
+    '--test',
+    '--test-isolation=none',
+    fixtures.path('test-runner', 'worker-id', 'test-1.mjs'),
+    fixtures.path('test-runner', 'worker-id', 'test-2.mjs'),
+  ];
+  const result = spawnSync(process.execPath, args, {
+    cwd: fixtures.path(),
+    env: { ...process.env }
+  });
+
+  assert.strictEqual(result.status, 0, `Test failed: ${result.stderr.toString()}`);
+});
+
+test('context.workerId matches NODE_TEST_WORKER_ID', async () => {
+  const args = ['--test', fixtures.path('test-runner', 'worker-id', 'test-1.mjs')];
+  const result = spawnSync(process.execPath, args, {
+    cwd: fixtures.path(),
+    env: { ...process.env }
+  });
+
+  // The fixture tests already verify that context.workerId matches the env var
+  assert.strictEqual(result.status, 0, `Test failed: ${result.stderr.toString()}`);
+});
+
+test('worker IDs are reused when more tests than concurrency', async () => {
+  const tmpdir = require('../common/tmpdir');
+  const { writeFileSync } = require('node:fs');
+  tmpdir.refresh();
+
+  // Create 9 separate test files dynamically
+  const testFiles = [];
+  const usageFile = tmpdir.resolve('worker-usage.txt');
+  for (let i = 1; i <= 9; i++) {
+    const testFile = tmpdir.resolve(`reuse-test-${i}.mjs`);
+    writeFileSync(
+      testFile,
+      `import { test } from 'node:test';
+import { appendFileSync } from 'node:fs';
+
+test('track worker ${i}', () => {
+  const workerId = process.env.NODE_TEST_WORKER_ID;
+  const usageFile = process.env.WORKER_USAGE_FILE;
+  appendFileSync(usageFile, workerId + '\\n');
+});
+`,
+    );
+    testFiles.push(testFile);
+  }
+
+  const args = ['--test', '--test-concurrency=3', ...testFiles];
+  const result = spawnSync(process.execPath, args, {
+    env: { ...process.env, WORKER_USAGE_FILE: usageFile }
+  });
+
+  assert.strictEqual(result.status, 0, `Test failed: ${result.stderr.toString()}`);
+
+  // Read and analyze worker IDs used
+  const { readFileSync } = require('node:fs');
+  const workerIds = readFileSync(usageFile, 'utf8').trim().split('\n');
+
+  // Count occurrences of each worker ID
+  const workerCounts = {};
+  workerIds.forEach((id) => {
+    workerCounts[id] = (workerCounts[id] || 0) + 1;
+  });
+
+  const uniqueWorkers = Object.keys(workerCounts);
+  assert.strictEqual(
+    uniqueWorkers.length,
+    3,
+    `Should have exactly 3 unique worker IDs, got ${uniqueWorkers.length}: ${uniqueWorkers.join(', ')}`
+  );
+
+  Object.entries(workerCounts).forEach(([id, count]) => {
+    assert.strictEqual(count, 3, `Worker ID ${id} should be used 3 times, got ${count}`);
+  });
+});