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

@@ -1411,6 +1411,9 @@ changes:
     - v18.17.0
     pr-url: https://github.com/nodejs/node/pull/47628
     description: Add a testNamePatterns option.
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/61367
+    description: Add the `env` option
 -->
 
 * `options` {Object} Configuration options for running tests. The following
@@ -1504,6 +1507,7 @@ 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.
 * 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, ...process.env, ...opts.env, NODE_TEST_CONTEXT: 'child-v8' };
     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,10 @@ function run(options = kEmptyObject) {
     validatePath(globalSetupPath, 'options.globalSetupPath');
   }
 
+  if (env != null) {
+    validateObject(env);
+  }
+
   const rootTestOptions = { __proto__: null, concurrency, timeout, signal };
   const globalOptions = {
     __proto__: null,
@@ -763,6 +768,7 @@ function run(options = kEmptyObject) {
     argv,
     execArgv,
     rerunFailuresFilePath,
+    env,
   };
 
   if (isolation === 'process') {

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

@@ -0,0 +1,5 @@
+const { test } = require('node:test');
+
+test('process.env is correct', (t) => {
+    t.assert.strictEqual(process.env.FOOBAR, 'FUZZBUZZ');
+});

test/parallel/test-runner-run.mjs

@@ -648,6 +648,14 @@ describe('require(\'node:test\').run', { concurrency: true }, () => {
       assert.strictEqual(diagnostics.includes(entry), true);
     }
   });
+
+  it('should allow env variables to be configured', async () => {
+    const stream = run({ files: [join(testFixtures, 'process-env.js')], env: { FOOBAR: 'FUZZBUZZ' } });
+    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);
+  });
 });
 
 describe('forceExit', () => {