test_runner: introduce NODE_TEST_WORKER_ID for improved concurrent te…

…st execution

Added a new environment variable, `NODE_TEST_WORKER_ID`, which ranges from 1 to N when `--experimental-test-isolation=process` is enabled and defaults to 1 when `--experimental-test-isolation=none` is used.

doc/api/cli.md

@@ -2249,6 +2249,19 @@ Starts the Node.js command line test runner. This flag cannot be combined with
 See the documentation on [running tests from the command line][]
 for more details.
 
+### Environment Variable
+
+The following environment variable is available when running tests with the `--test` flag:
+
+`NODE_TEST_WORKER_ID`:
+
+* Parallel Test Runs: If tests are executed in parallel (using the `--test` flag
+  alone or with the `--experimental-test-isolation=process` flag), this variable is assigned
+  a unique number ranging from `1` to `N`, where `N` represents the total number of test files being processed.
+
+* Isolated Test Runs: When tests are run in isolation (using the `--experimental-test-isolation=none` flag),
+  this variable is always set to `1`.
+
 ### `--test-concurrency`
 
 <!-- YAML

lib/internal/test_runner/runner.js

@@ -358,14 +358,14 @@ class FileTest extends Test {
   }
 }
 
-function runTestFile(path, filesWatcher, opts) {
+function runTestFile(path, filesWatcher, opts, workerId = 1) {
   const watchMode = filesWatcher != null;
   const testPath = path === kIsolatedProcessName ? '' : path;
   const testOpts = { __proto__: null, signal: opts.signal };
   const subtest = opts.root.createSubtest(FileTest, testPath, testOpts, async (t) => {
     const args = getRunArgs(path, opts);
     const stdio = ['pipe', 'pipe', 'pipe'];
-    const env = { __proto__: null, ...process.env, NODE_TEST_CONTEXT: 'child-v8' };
+    const env = { __proto__: null, ...process.env, NODE_TEST_CONTEXT: 'child-v8', NODE_TEST_WORKER_ID: workerId };
     if (watchMode) {
       stdio.push('ipc');
       env.WATCH_REPORT_DEPENDENCIES = '1';
@@ -724,8 +724,10 @@ function run(options = kEmptyObject) {
     runFiles = () => {
       root.harness.bootstrapPromise = null;
       root.harness.buildPromise = null;
+      let workerId = 1;
       return SafePromiseAllSettledReturnVoid(testFiles, (path) => {
-        const subtest = runTestFile(path, filesWatcher, opts);
+        const subtest = runTestFile(path, filesWatcher, opts, workerId);
+        workerId++;
         filesWatcher?.runningSubtests.set(path, subtest);
         return subtest;
       });
@@ -766,6 +768,7 @@ function run(options = kEmptyObject) {
 
             root.entryFile = resolve(testFile);
             debug('loading test file:', fileURL.href);
+            process.env.NODE_TEST_WORKER_ID = 1;
             try {
               await cascadedLoader.import(fileURL, parent, { __proto__: null });
             } catch (err) {

test/fixtures/test-runner/NODE_TEST_WORKER_ID/1.test.js

@@ -0,0 +1,5 @@
+const test = require('node:test');
+
+test('test1', t => {
+    console.log('NODE_TEST_WORKER_ID', process.env.NODE_TEST_WORKER_ID)
+});

test/fixtures/test-runner/NODE_TEST_WORKER_ID/2.test.js

@@ -0,0 +1,5 @@
+const test = require('node:test');
+
+test('test2', t => {
+    console.log('NODE_TEST_WORKER_ID', process.env.NODE_TEST_WORKER_ID)
+});

test/fixtures/test-runner/NODE_TEST_WORKER_ID/3.test.js

@@ -0,0 +1,5 @@
+const test = require('node:test');
+
+test('test3', t => {
+    console.log('NODE_TEST_WORKER_ID', process.env.NODE_TEST_WORKER_ID)
+});

test/parallel/test-runner-worker-id.js

@@ -0,0 +1,35 @@
+'use strict';
+
+require('../common');
+const assert = require('assert');
+const { spawnSync } = require('child_process');
+const { join } = require('path');
+const fixtures = require('../common/fixtures');
+const testFixtures = fixtures.path('test-runner');
+
+{
+  const args = ['--test', '--experimental-test-isolation=process'];
+  const child = spawnSync(process.execPath, args, { cwd: join(testFixtures, 'NODE_TEST_WORKER_ID') });
+
+  assert.strictEqual(child.stderr.toString(), '');
+  const stdout = child.stdout.toString();
+
+  assert.match(stdout, /NODE_TEST_WORKER_ID 1/);
+  assert.match(stdout, /NODE_TEST_WORKER_ID 2/);
+  assert.match(stdout, /NODE_TEST_WORKER_ID 3/);
+
+  assert.strictEqual(child.status, 0);
+}
+
+{
+  const args = ['--test', '--experimental-test-isolation=none'];
+  const child = spawnSync(process.execPath, args, { cwd: join(testFixtures, 'NODE_TEST_WORKER_ID') });
+
+  assert.strictEqual(child.stderr.toString(), '');
+  const stdout = child.stdout.toString();
+  const regex = /NODE_TEST_WORKER_ID 1/g;
+  const result = stdout.match(regex);
+
+  assert.strictEqual(result.length, 3);
+  assert.strictEqual(child.status, 0);
+}