test_runner: avoid reading process state directly in run()

[murataslan1]

Refs: #53867

Summary

The run() function is exposed as a public API via node:test, but it accessed process.argv, process.execArgv, process.cwd(), and process.env directly. This meant programmatic API users could not fully control the test runner behavior.

PR #54705 added cwd as an option but other process state references remained (as noted by @cjihrig).

Changes

• Capture process.argv, process.cwd(), process.env, and process.execArgv in the CLI entry point (lib/internal/main/test_runner.js) and pass them explicitly to run() as options
• Add processExecArgv option for V8 flag propagation to child processes
• Replace process.env fallback in runTestFile() with opts.env
• Replace process.argv usage in getRunArgs() with globPatterns
• Replace process.env.NODE_TEST_CONTEXT check with env option
• Maintain backwards compatibility: when options are not provided, run() falls back to process state as before

Test plan

• Existing test runner tests should pass without changes
• Programmatic run() calls now respect explicitly provided env, cwd, processExecArgv options instead of reading from process globals

[nodejs-github-bot]

Review requested:

• @nodejs/test_runner

[Copilot]

Pull request overview

This PR updates the Node.js test runner so the public node:test run() API can be controlled programmatically without implicitly reading from process globals (argv/cwd/env/execArgv), while keeping backwards-compatible fallbacks.

Changes:

• Capture process.argv, process.cwd(), process.env, and process.execArgv in the CLI entry point and pass them into run() as options.
• Add/propagate processExecArgv for forwarding V8 flags to child processes.
• Replace remaining direct reads of process.argv/process.env in runner internals with option-based values.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
lib/internal/test_runner/runner.js	Adds option plumbing/defaults for process state, uses passed-in argv/env/execArgv equivalents when spawning child test processes.
lib/internal/main/test_runner.js	Captures process state at the CLI entry point and passes it down via run() options.

Comments suppressed due to low confidence (1)

lib/internal/test_runner/runner.js:787

• run() now treats any defined env as user-provided, and rejects it when isolation === 'none'. Because the CLI entry point always passes options.env = process.env, node --test --test-isolation=none will now throw. Consider adjusting the "user provided" detection (e.g., distinguish internal captured env from an explicit API override) or relaxing the isolation='none' restriction for the default/inherited env case.

  if (userProvidedEnv) {
    validateObject(env);

    if (isolation === 'none') {
      throw new ERR_INVALID_ARG_VALUE('options.env', env, 'is not supported with isolation=\'none\'');
    }
  }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

globPatterns is forwarded into runArgs via ArrayPrototypePushApply() (so it must be an array of strings). Currently run() only ensures it's an array; consider validating its element types (e.g., string array) to avoid child-spawn argument errors caused by non-string entries.

[Copilot]

options.env is being set unconditionally, which makes run() think the caller explicitly provided an env option. With --test-isolation=none, run() currently rejects options.env, so this change will break node --test --test-isolation=none. Consider only setting/passing options.env in the CLI when isolation='process' (or update run() to treat this captured env as non-user-provided).

Suggested change

	options.env = process.env;
	if (options.isolation === 'process') {
	options.env = process.env;
	}

[Copilot]

processExecArgv is consumed by getRunArgs() as an array (it is filtered and iterated), but there is no validation for the options.processExecArgv type. If a public API caller passes a non-array value, this will fail at runtime in less obvious ways. Consider validating it (e.g., validateStringArray(processExecArgv, 'options.processExecArgv')) when it is explicitly provided.

[avivkeller]

How's this differ from execArgv?

[murataslan1]

Yeah you're right, dropped it. The idea was to avoid the direct process.execArgv read, but it doesn't really make sense as a user-facing option — it's just the parent's V8 flags that get forwarded to child processes. Reverted to reading it directly.

[avivkeller]

Blocking as this needs documentation and tests

[murataslan1]

Pushed fixes based on the feedback:

• Dropped processExecArgv entirely — doesn't belong in the public API, reverted to reading process.execArgv directly
• Fixed the env + isolation=none issue — only passing env from CLI when isolation is process-based
• Added docs for the env option and two tests (env acceptance + env rejection with isolation=none)

Let me know if anything else needs changing!