test_runner: add env option to run function #61367

Ethan-Arrowood · 2026-01-13T14:07:30Z

Support an env option that is passed to the
underlying child_process.
Fixes: #60709

nodejs-github-bot · 2026-01-13T14:07:36Z

Review requested:

@nodejs/test_runner

test/parallel/test-runner-run.mjs

lib/internal/test_runner/runner.js

codecov · 2026-01-13T17:07:39Z

Codecov Report

❌ Patch coverage is 81.81818% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.85%. Comparing base (1bd7f62) to head (2ce1c30).
⚠️ Report is 92 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/test_runner/runner.js	81.81%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #61367      +/-   ##
==========================================
+ Coverage   88.51%   89.85%   +1.33%     
==========================================
  Files         704      671      -33     
  Lines      208739   203176    -5563     
  Branches    40274    39052    -1222     
==========================================
- Hits       184770   182560    -2210     
+ Misses      15968    12971    -2997     
+ Partials     8001     7645     -356

Files with missing lines	Coverage Δ
lib/internal/test_runner/runner.js	`93.12% <81.81%> (+0.17%)`	⬆️

... and 123 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

pmarchini · 2026-01-14T08:23:28Z

lib/internal/test_runner/runner.js

    const args = getRunArgs(path, opts);
    const stdio = ['pipe', 'pipe', 'pipe'];
-    const env = { __proto__: null, ...process.env, NODE_TEST_CONTEXT: 'child-v8' };
+    const env = opts.env || { __proto__: null, ...process.env, NODE_TEST_CONTEXT: 'child-v8' };


NODE_TEST_CONTEXT is used by the test runner to identify the runner subprocesses, and removing it may cause issues with the reporters.

It must be preserved even if the user passes opts.env.

I would suggest, in any case, adding a snapshot test when using this option to cover the E2E once the option has been provided!

Okay, I'm going to switch this line to this: const env = { __proto__: null, NODE_TEST_CONTEXT: 'child-v8', ...(opts.env || process.env) }; so that its configured by default, but is overridable if someone wanted to. I believe currently there is a subtle bug here where even if you specified the NODE_TEST_CONTEXT variable in the main process, it'd be overridden to child-v8 no matter what.

I don't fully understand the ask here:

I would suggest, in any case, adding a snapshot test when using this option to cover the E2E once the option has been provided!

Snapshot of what? The environment variables? Do you mean for me to just assert that something such as NODE_TEST_CONTEXT is retained when env option is specified, or something more in depth?

pmarchini · 2026-01-14T08:24:46Z

doc/api/test.md

  * `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'`.


I think it might be worth specifying here that these variables will override those from the main process

MoLow · 2026-01-15T07:53:39Z

doc/api/test.md

  * `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.


env vars are supposed to be inherited, what is the usecase here?

They still are by default; this feature is essentially just bubbling up the underlying child_process.spawn() env option.

If you are using the run() method multiple times to spawn multiple test processes. And want to be able to specify unique environment variables for each; there currently is no way to do so.

MoLow · 2026-01-15T16:11:39Z

lib/internal/test_runner/runner.js

    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) };


Suggested change

const env = { __proto__: null, NODE_TEST_CONTEXT: 'child-v8', ...(opts.env || process.env) };

const env = { __proto__: null, NODE_TEST_CONTEXT: 'child-v8', ...(opts.env ?? process.env) };

nitpic

nodejs-github-bot · 2026-01-18T11:38:04Z

CI: https://ci.nodejs.org/job/node-test-pull-request/70869/

pmarchini · 2026-01-20T08:41:14Z

Hey @Ethan-Arrowood, while checking the CI, I noticed failures related to these changes.
Could you please take a look at them?

Ethan-Arrowood · 2026-01-20T14:56:51Z

The only one that isn't a flake or build issue is Linux Containered: https://ci.nodejs.org/job/node-test-commit-linux-containered/54320/

I'm not familiar with this environment, but I will try to take a look.

Ethan-Arrowood · 2026-01-20T15:52:53Z

I am having a hard time understanding why this test is failing on these environments. I'm inspecting the stack trace in Jenkins and its not sharing anything useful:


---
duration_ms: 1248.809
exitcode: 1
severity: fail
stack: |-
  Test failure: 'should allow env variables to be configured'
  Location: test/parallel/test-runner-run.mjs:654:3
  AssertionError [ERR_ASSERTION]: function should not have been called at file:///home/iojs/build/workspace/node-test-commit-linux-containered/test/parallel/test-runner-run.mjs:658
  called with arguments: [Object: null prototype] {
    name: '/home/iojs/build/workspace/node-test-commit-linux-containered/test/fixtures/test-runner/process-env.js',
    nesting: 0,
    testNumber: 1,
    details: [Object: null prototype] {
      duration_ms: 6.408189,
      type: 'test',
      error: [Error: test failed] {
        code: 'ERR_TEST_FAILURE',
        failureType: 'testCodeFailure',
        cause: 'test failed',
        exitCode: 127,
        signal: null
      }
    },
    line: 1,
    column: 1,
    file: '/home/iojs/build/workspace/node-test-commit-linux-containered/test/fixtures/test-runner/process-env.js'
  }
      at TestsStream.mustNotCall (/home/iojs/build/workspace/node-test-commit-linux-containered/test/common/index.js:564:12)
      at TestsStream.emit (node:events:508:20)
      at [kEmitMessage] (node:internal/test_runner/tests_stream:157:10)
      at TestsStream.fail (node:internal/test_runner/tests_stream:38:23)
      at FileTest.report (node:internal/test_runner/test:1384:21)
      at FileTest.report (node:internal/test_runner/runner:307:13)
      at FileTest.finalize (node:internal/test_runner/test:1325:10)
      at Test.processReadySubtestRange (node:internal/test_runner/test:833:15)
      at FileTest.postRun (node:internal/test_runner/test:1237:19)
      at Test.postRun (node:internal/test_runner/test:1210:17) {
    generatedMessage: false,
    code: 'ERR_ASSERTION',
    actual: undefined,
    expected: undefined,
    operator: 'fail',
    diff: 'simple'
  }

  (node:158076) MaxListenersExceededWarning: Possible EventEmitter memory leak detected. 11 uncaughtException listeners added to [process]. MaxListeners is 10. Use emitter.setMaxListeners() to increase limit
  (Use `node --trace-warnings ...` to show where the warning was created)
  (node:158076) MaxListenersExceededWarning: Possible EventEmitter memory leak detected. 11 unhandledRejection listeners added to [process]. MaxListeners is 10. Use emitter.setMaxListeners() to increase limit
  (node:158076) MaxListenersExceededWarning: Possible EventEmitter memory leak detected. 11 beforeExit listeners added to [process]. MaxListeners is 10. Use emitter.setMaxListeners() to increase limit
...

All this stack is telling me is that the stream.on('test:fail', common.mustNotCall()); in the test is being called. But, it is not saying why making me think this is not an actual assertion issue from test/fixtures/test-runner/process-env.js, but possibly something else?

Locally, if I add a line like: t.assert.fail('Intentionally fail test.'); to test/fixtures/test-runner/process-env.js, then the stack trace actually has useful information about whats causing the test to fail:

❯ tools/test.py test/parallel/test-runner-run.mjs
=== release test-runner-run ===                   
Path: parallel/test-runner-run
Test failure: 'should allow env variables to be configured'
Location: test/parallel/test-runner-run.mjs:654:3
AssertionError [ERR_ASSERTION]: function should not have been called at file:///Users/ethan/dev/nodejs/node/test/parallel/test-runner-run.mjs:658
called with arguments: [Object: null prototype] {
  name: '/Users/ethan/dev/nodejs/node/test/fixtures/test-runner/process-env.js',
  nesting: 0,
  testNumber: 1,
  details: [Object: null prototype] {
    duration_ms: 61.008,
    type: 'test',
    error: Error [ERR_TEST_FAILURE]: function should not have been called at file:///Users/ethan/dev/nodejs/node/test/parallel/test-runner-run.mjs:658
    called with arguments: {
      name: 'process.env is correct',
      nesting: 0,
      testNumber: 1,
      details: {
        duration_ms: 1.46075,
        type: 'test',
        error: [Error [ERR_TEST_FAILURE]: Intentionally fail test.] {
          code: 'ERR_TEST_FAILURE',
          failureType: 'testCodeFailure',
          cause: [Error]
        }
      },
      line: 3,
      column: 1,
      file: '/Users/ethan/dev/nodejs/node/test/fixtures/test-runner/process-env.js'
    }
        at process.emit (node:events:520:22)
        at process.emit (node:domain:489:12) {
      code: 'ERR_TEST_FAILURE',
      failureType: 'uncaughtException',
      cause: AssertionError [ERR_ASSERTION]: function should not have been called at file:///Users/ethan/dev/nodejs/node/test/parallel/test-runner-run.mjs:658
      called with arguments: {
        name: 'process.env is correct',
        nesting: 0,
        testNumber: 1,
        details: {
          duration_ms: 1.46075,
          type: 'test',
          error: [Error [ERR_TEST_FAILURE]: Intentionally fail test.] {
            code: 'ERR_TEST_FAILURE',
            failureType: 'testCodeFailure',
            cause: [Error]
          }
        },
        line: 3,
        column: 1,
        file: '/Users/ethan/dev/nodejs/node/test/fixtures/test-runner/process-env.js'
      }
          at TestsStream.mustNotCall (/Users/ethan/dev/nodejs/node/test/common/index.js:564:12)
          at TestsStream.emit (node:events:508:20)
          at TestsStream.emit (node:domain:489:12)
          at [kEmitMessage] (node:internal/test_runner/tests_stream:153:10)
          at #handleReportItem (node:internal/test_runner/runner:272:32)
          at FileTest.addToReport (node:internal/test_runner/runner:296:27)
          at #processRawBuffer (node:internal/test_runner/runner:395:12)
          at FileTest.parseMessage (node:internal/test_runner/runner:329:27)
          at Socket.<anonymous> (node:internal/test_runner/runner:439:15)
          at Socket.emit (node:events:508:20) {
        generatedMessage: false,
        code: 'ERR_ASSERTION',
        actual: undefined,
        expected: undefined,
        operator: 'fail',
        diff: 'simple'
      }
    }
  },
  line: 1,
  column: 1,
  file: '/Users/ethan/dev/nodejs/node/test/fixtures/test-runner/process-env.js'
}
    at TestsStream.mustNotCall (/Users/ethan/dev/nodejs/node/test/common/index.js:564:12)
    at TestsStream.emit (node:events:508:20)
    at TestsStream.emit (node:domain:489:12)
    at [kEmitMessage] (node:internal/test_runner/tests_stream:153:10)
    at TestsStream.fail (node:internal/test_runner/tests_stream:38:23)
    at FileTest.report (node:internal/test_runner/test:1367:21)
    at FileTest.report (node:internal/test_runner/runner:308:13)
    at FileTest.finalize (node:internal/test_runner/test:1311:10)
    at Test.processReadySubtestRange (node:internal/test_runner/test:824:15)
    at FileTest.postRun (node:internal/test_runner/test:1223:19) {
  generatedMessage: false,
  code: 'ERR_ASSERTION',
  actual: undefined,
  expected: undefined,
  operator: 'fail',
  diff: 'simple'
}
Command: out/Release/node --test-reporter=./test/common/test-error-reporter.js --test-reporter-destination=stdout /Users/ethan/dev/nodejs/node/test/parallel/test-runner-run.mjs


[00:00|% 100|+   0|-   1]: Done                   

Failed tests:
out/Release/node --test-reporter=./test/common/test-error-reporter.js --test-reporter-destination=stdout /Users/ethan/dev/nodejs/node/test/parallel/test-runner-run.mjs

Does anyone have a better idea here?

Ethan-Arrowood · 2026-01-20T15:58:43Z

Is the issue that we are not inheriting anything from process.env? Could the Linux Containered environment have a more minimal environment where PATH and other variables are needed? Like the exit code 127 is telling me that this environment cannot find the necessary things to execute.

So following this idea... could the run() implementation have been implicitly relying on something being specified in process.env ? Maybe there is a required fix there 🤔

Ethan-Arrowood · 2026-01-20T16:12:27Z

I prompted AI with that idea and it came up with something by looking at other tests and things. Here is a summary from what it figured out.

The Fix: Added addLibraryPath(env) call in test-runner-run.mjs:661 to ensure the custom environment includes necessary library paths when Node.js is built as a shared library.

Why this approach:

Respects the env API contract: When users provide env, they get exactly what they specify. The test runner doesn't inject variables automatically.
Follows existing patterns: Other Node.js tests that use custom environments (like test-child-process-fork-exec-path.js) also use addLibraryPath() explicitly.
User responsibility: If you're building Node.js as a shared library and providing a custom environment, you need to handle the library paths yourself using the test utility.

This reasoning makes sense to me, but please correct if it was wrong.

github-actions · 2026-01-20T16:31:14Z

Failed to start CI

   ⚠  Commits were pushed since the last approving review:
   ⚠  - test_runner: add env option to run function
   ✘  Refusing to run CI on potentially unsafe PR

https://github.com/nodejs/node/actions/runs/21179244874

Ethan-Arrowood · 2026-01-20T21:21:43Z

Those debugger tests on the macOS action are not failing for me locally 🤔 That has to be flakiness right?

test/parallel/test-runner-run.mjs

pmarchini · 2026-01-21T08:10:48Z

Those debugger tests on the macOS action are not failing for me locally 🤔 That has to be flakiness right?

yes that seems just a flakiness issue!

Support an `env` option that is passed to the underlying child_process. Fixes: nodejs#60709

nodejs-github-bot · 2026-01-21T19:04:34Z

CI: https://ci.nodejs.org/job/node-test-pull-request/70947/

Ethan-Arrowood · 2026-01-21T21:22:39Z

Only flake in the CI 🎉

This is ready to merge I think 🚀

Ethan-Arrowood · 2026-01-21T21:23:36Z

I think we could backport this feature to all active release lines, right? Nothing at all breaking here.

nodejs-github-bot · 2026-01-21T21:24:34Z

CI: https://ci.nodejs.org/job/node-test-pull-request/70950/

nodejs-github-bot added needs-ci PRs that need a full CI run. test_runner Issues and PRs related to the test runner subsystem. labels Jan 13, 2026

pmarchini reviewed Jan 13, 2026

View reviewed changes

test/parallel/test-runner-run.mjs Outdated Show resolved Hide resolved

avivkeller approved these changes Jan 13, 2026

View reviewed changes

lib/internal/test_runner/runner.js Outdated Show resolved Hide resolved

Ethan-Arrowood force-pushed the test-runner-env-option branch from 724b84e to cd4d84e Compare January 14, 2026 00:14

Ethan-Arrowood requested review from avivkeller, ljharb, mcollina and pmarchini January 14, 2026 00:15

pmarchini reviewed Jan 14, 2026

View reviewed changes

Ethan-Arrowood force-pushed the test-runner-env-option branch from cd4d84e to 315e0bb Compare January 14, 2026 16:45

Ethan-Arrowood requested a review from pmarchini January 14, 2026 16:45

MoLow reviewed Jan 15, 2026

View reviewed changes

avivkeller approved these changes Jan 15, 2026

View reviewed changes

MoLow reviewed Jan 15, 2026

View reviewed changes

MoLow approved these changes Jan 15, 2026

View reviewed changes

atlowChemi approved these changes Jan 17, 2026

View reviewed changes

pmarchini approved these changes Jan 18, 2026

View reviewed changes

pmarchini added the request-ci Add this label to start a Jenkins CI on a PR. label Jan 18, 2026

github-actions bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Jan 18, 2026

Ethan-Arrowood force-pushed the test-runner-env-option branch from 315e0bb to c7e2bd6 Compare January 20, 2026 16:08

Ethan-Arrowood requested review from avivkeller and pmarchini January 20, 2026 16:14

Ethan-Arrowood added the request-ci Add this label to start a Jenkins CI on a PR. label Jan 20, 2026

github-actions bot added request-ci-failed An error occurred while starting CI via request-ci label, and manual interventon is needed. and removed request-ci Add this label to start a Jenkins CI on a PR. labels Jan 20, 2026

Ethan-Arrowood removed the request-ci-failed An error occurred while starting CI via request-ci label, and manual interventon is needed. label Jan 20, 2026

pmarchini reviewed Jan 21, 2026

View reviewed changes

test/parallel/test-runner-run.mjs Show resolved Hide resolved

test_runner: add env option to run function

2ce1c30

Support an `env` option that is passed to the underlying child_process. Fixes: nodejs#60709

Ethan-Arrowood force-pushed the test-runner-env-option branch from c7e2bd6 to 2ce1c30 Compare January 21, 2026 17:47

Ethan-Arrowood requested a review from pmarchini January 21, 2026 17:47

pmarchini approved these changes Jan 21, 2026

View reviewed changes

pmarchini added the request-ci Add this label to start a Jenkins CI on a PR. label Jan 21, 2026

github-actions bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Jan 21, 2026

MoLow approved these changes Jan 21, 2026

View reviewed changes

Ethan-Arrowood added author ready PRs that have at least one approval, no pending requests for changes, and a CI started. lts-watch-v24.x PRs that may need to be released in v24.x labels Jan 21, 2026

	const env = { __proto__: null, NODE_TEST_CONTEXT: 'child-v8', ...(opts.env \|\| process.env) };
	const env = { __proto__: null, NODE_TEST_CONTEXT: 'child-v8', ...(opts.env ?? process.env) };

Uh oh!

test_runner: add env option to run function #61367

Are you sure you want to change the base?

test_runner: add env option to run function #61367

Conversation

Ethan-Arrowood commented Jan 13, 2026

Uh oh!

nodejs-github-bot commented Jan 13, 2026

Uh oh!

Uh oh!

Uh oh!

codecov bot commented Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nodejs-github-bot commented Jan 18, 2026

Uh oh!

pmarchini commented Jan 20, 2026

Uh oh!

Ethan-Arrowood commented Jan 20, 2026

Uh oh!

Ethan-Arrowood commented Jan 20, 2026

Uh oh!

Ethan-Arrowood commented Jan 20, 2026

Uh oh!

Ethan-Arrowood commented Jan 20, 2026

Uh oh!

github-actions bot commented Jan 20, 2026

Uh oh!

Ethan-Arrowood commented Jan 20, 2026

Uh oh!

Uh oh!

pmarchini commented Jan 21, 2026

Uh oh!

nodejs-github-bot commented Jan 21, 2026

Uh oh!

Ethan-Arrowood commented Jan 21, 2026

Uh oh!

Ethan-Arrowood commented Jan 21, 2026

Uh oh!

nodejs-github-bot commented Jan 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

codecov bot commented Jan 13, 2026 •

edited

Loading