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.87%. Comparing base (1bd7f62) to head (0eb68d1).
⚠️ Report is 155 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.87%   +1.36%     
==========================================
  Files         704      671      -33     
  Lines      208739   203319    -5420     
  Branches    40274    39095    -1179     
==========================================
- Hits       184770   182742    -2028     
+ Misses      15968    12926    -3042     
+ Partials     8001     7651     -350

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

... and 129 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.

@Ethan-Arrowood The docs here are missing the default value.

I created a doc PR here:

doc: mention default option for test runner env #61659

Good catch!

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.

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

Ethan-Arrowood · 2026-01-22T14:52:24Z

Silly new line lol

nodejs-github-bot · 2026-01-22T15:01:48Z

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

nodejs-github-bot · 2026-01-22T20:46:04Z

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

mcollina

lgtm

nodejs-github-bot · 2026-01-23T18:48:20Z

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

nodejs-github-bot · 2026-01-26T18:50:33Z

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

nodejs-github-bot · 2026-01-27T22:50:59Z

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

nodejs-github-bot · 2026-01-29T08:18:13Z

Landed in ec15c3b

Support an `env` option that is passed to the underlying child_process. Fixes: #60709 PR-URL: #61367 Reviewed-By: Aviv Keller <me@aviv.sh> Reviewed-By: Moshe Atlow <moshe@atlow.co.il> Reviewed-By: Chemi Atlow <chemi@atlow.co.il> Reviewed-By: Pietro Marchini <pietro.marchini94@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com>

Notable changes: async_hooks: * (SEMVER-MINOR) add trackPromises option to createHook() (Joyee Cheung) #61415 src: * improve textEncoder encode performance with simdutf (Mert Can Altin) #61496 stream: * (SEMVER-MINOR) add bytes() method to stream/consumers (wantaek) #60426 test_runner: * (SEMVER-MINOR) add env option to run function (Ethan Arrowood) #61367 url: * update ada to v3.4.2 and support unicode 17 (Yagiz Nizipli) #61593 PR-URL: #61635

Support an `env` option that is passed to the underlying child_process. Fixes: #60709 PR-URL: #61367 Reviewed-By: Aviv Keller <me@aviv.sh> Reviewed-By: Moshe Atlow <moshe@atlow.co.il> Reviewed-By: Chemi Atlow <chemi@atlow.co.il> Reviewed-By: Pietro Marchini <pietro.marchini94@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com>

Notable changes: async_hooks: * (SEMVER-MINOR) add `trackPromises` option to `createHook()` (Joyee Cheung) #61415 net: * (SEMVER-MINOR) add `setTOS` and `getTOS` to `Socket` (Amol Yadav) #61503 src: * (SEMVER-MINOR) add initial support for ESM in embedder API (Joyee Cheung) #61548 * improve `TextEncoder` encode performance with `simdutf` (Mert Can Altin) #61496 stream: * (SEMVER-MINOR) add `bytes()` method to `node:stream/consumers` (wantaek) #60426 test_runner: * (SEMVER-MINOR) add `env` option to `run` function (Ethan Arrowood) #61367 url: * update Ada to v3.4.2 and support Unicode 17 (Yagiz Nizipli) #61593 PR-URL: #61635

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

test_runner: add env option to run function

0eb68d1

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 2ce1c30 to 0eb68d1 Compare January 22, 2026 14:52

Ethan-Arrowood added the semver-minor PRs that contain new features and should be released in the next minor version. label Jan 22, 2026

MoLow approved these changes Jan 22, 2026

View reviewed changes

MoLow added request-ci Add this label to start a Jenkins CI on a PR. and removed commit-queue-failed An error occurred while landing this pull request using GitHub Actions. labels Jan 22, 2026

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

mcollina approved these changes Jan 22, 2026

View reviewed changes

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

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

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

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

pmarchini added the commit-queue Add this label to land a pull request using GitHub Actions. label Jan 29, 2026

nodejs-github-bot removed the commit-queue Add this label to land a pull request using GitHub Actions. label Jan 29, 2026

nodejs-github-bot merged commit ec15c3b into nodejs:main Jan 29, 2026
78 checks passed

github-actions bot mentioned this pull request Feb 2, 2026

2026-02-03, Version 25.6.0 (Current) #61635

Merged

styfle mentioned this pull request Feb 3, 2026

doc: mention default option for test runner env #61659

Open

	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

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!

styfle Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Ethan-Arrowood commented Jan 22, 2026

Uh oh!

nodejs-github-bot commented Jan 22, 2026

Uh oh!

nodejs-github-bot commented Jan 22, 2026

Uh oh!

mcollina left a comment

Choose a reason for hiding this comment

Uh oh!

nodejs-github-bot commented Jan 23, 2026

Uh oh!

nodejs-github-bot commented Jan 26, 2026

Uh oh!

nodejs-github-bot commented Jan 27, 2026

Uh oh!

Uh oh!

nodejs-github-bot commented Jan 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

codecov bot commented Jan 13, 2026 •

edited

Loading

styfle Feb 3, 2026 •

edited

Loading