test_runner: add env option to run function

Support an `env` option that is passed to the underlying child_process.

Fixes: #60709

Author: Ethan-Arrowood

doc/api/test.md

@@ -1384,6 +1384,9 @@ added:
   - v18.9.0
   - v16.19.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/61367
+    description: Add the `env` option.
   - version: v24.7.0
     pr-url: https://github.com/nodejs/node/pull/59443
     description: Added a rerunFailuresFilePath option.
@@ -1504,6 +1507,9 @@ changes:
   * `functionCoverage` {number} Require a minimum percent of covered functions. If code
     coverage does not reach the threshold specified, the process will exit with code `1`.
     **Default:** `0`.
+  * `env` {Object} Specify environment variables to be passed along to the test process.
+    This options is not compatible with `isolation='none'`. These variables will override
+    those from the main process, and are not merged with `process.env`.
 * Returns: {TestsStream}
 
 **Note:** `shard` is used to horizontally parallelize test running across

lib/internal/test_runner/runner.js

@@ -403,7 +403,7 @@ function runTestFile(path, filesWatcher, opts) {
   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, NODE_TEST_CONTEXT: 'child-v8', ...(opts.env || process.env) };
     if (watchMode) {
       stdio.push('ipc');
       env.WATCH_REPORT_DEPENDENCIES = '1';
@@ -610,6 +610,7 @@ function run(options = kEmptyObject) {
     argv = [],
     cwd = process.cwd(),
     rerunFailuresFilePath,
+    env,
   } = options;
 
   if (files != null) {
@@ -718,6 +719,14 @@ function run(options = kEmptyObject) {
     validatePath(globalSetupPath, 'options.globalSetupPath');
   }
 
+  if (env != null) {
+    validateObject(env);
+
+    if (isolation === 'none') {
+      throw new ERR_INVALID_ARG_VALUE('options.env', env, 'is not supported with isolation=\'none\'');
+    }
+  }
+
   const rootTestOptions = { __proto__: null, concurrency, timeout, signal };
   const globalOptions = {
     __proto__: null,
@@ -763,6 +772,7 @@ function run(options = kEmptyObject) {
     argv,
     execArgv,
     rerunFailuresFilePath,
+    env,
   };
 
   if (isolation === 'process') {

test/fixtures/test-runner/process-env.js

@@ -0,0 +1,7 @@
+const { test } = require('node:test');
+
+test('process.env is correct', (t) => {
+    t.assert.strictEqual(process.env.ABC, undefined, 'main process env var should be undefined');
+    t.assert.strictEqual(process.env.NODE_TEST_CONTEXT, 'child-v8', 'NODE_TEST_CONTEXT should be set by run()');
+    t.assert.strictEqual(process.env.FOOBAR, 'FUZZBUZZ', 'specified env var should be defined');
+});

test/parallel/test-runner-run.mjs

@@ -650,6 +650,29 @@ describe('require(\'node:test\').run', { concurrency: true }, () => {
   });
 });
 
+describe('env', () => {
+  it('should allow env variables to be configured', async () => {
+    // Need to inherit some process.env variables so it runs reliably across different environments.
+    const env = { ...process.env, FOOBAR: 'FUZZBUZZ' };
+    // Set a variable on main process env and test it does not exist within test env.
+    process.env.ABC = 'XYZ';
+
+    const stream = run({ files: [join(testFixtures, 'process-env.js')], env });
+    stream.on('test:fail', common.mustNotCall());
+    stream.on('test:pass', common.mustCall(1));
+    // eslint-disable-next-line no-unused-vars
+    for await (const _ of stream);
+    delete process.env.ABC;
+  });
+
+  it('should throw error when env is specified with isolation=none', async () => {
+    assert.throws(() => run({ env: { foo: 'bar' }, isolation: 'none' }), {
+      code: 'ERR_INVALID_ARG_VALUE',
+      message: /The property 'options\.env' is not supported with isolation='none'\. Received { foo: 'bar' }/
+    });
+  });
+});
+
 describe('forceExit', () => {
   it('throws for non-boolean values', () => {
     [Symbol(), {}, 0, 1, '1', Promise.resolve([])].forEach((forceExit) => {