From 45341370440d0c854d28dbefc0c0d16868613553 Mon Sep 17 00:00:00 2001
From: Matteo Collina <hello@matteocollina.com>
Date: Wed, 21 Oct 2026 17:45:50 -0700
Subject: [PATCH 1/2] test_runner: forward arguments after -- to test files

Fixes: https://github.com/nodejs/node/issues/61852
Signed-off-by: Matteo Collina <hello@matteocollina.com>
---
 doc/api/test.md                       | 15 +++++++++++++++
 lib/internal/main/test_runner.js      | 12 +++++++++++-
 lib/internal/test_runner/runner.js    |  3 +++
 test/parallel/test-runner-cli-argv.js | 19 +++++++++++++++++++
 4 files changed, 48 insertions(+), 1 deletion(-)
 create mode 100644 test/parallel/test-runner-cli-argv.js

diff --git a/doc/api/test.md b/doc/api/test.md
index 48d5b0c004cd..ec1e921f7ef7 100644
--- a/doc/api/test.md
+++ b/doc/api/test.md
@@ -759,6 +759,21 @@ prevent shell expansion, which can reduce portability across systems.
 node --test "**/*.test.js" "**/*.spec.js"
 ```
 
+Any arguments following a `--` separator placed after the glob patterns are
+passed to each test file instead of being treated as glob patterns. They are
+available in each test file via `process.argv`.
+
+```bash
+node --test "**/*.test.js" -- --custom-flag value
+```
+
+If no glob patterns are provided, a second `--` is needed, because Node.js
+consumes the first `--` as the end of its own options.
+
+```bash
+node --test -- -- --custom-flag value
+```
+
 ### Randomizing tests execution order
 
 <!-- YAML
diff --git a/lib/internal/main/test_runner.js b/lib/internal/main/test_runner.js
index fda47897da9f..1008142cb65a 100644
--- a/lib/internal/main/test_runner.js
+++ b/lib/internal/main/test_runner.js
@@ -1,6 +1,7 @@
 'use strict';
 
 const {
+  ArrayPrototypeIndexOf,
   ArrayPrototypeSlice,
 } = primordials;
 
@@ -30,7 +31,16 @@ if (isUsingInspector() && options.isolation === 'process') {
   options.inspectPort = process.debugPort;
 }
 
-options.globPatterns = ArrayPrototypeSlice(process.argv, 1);
+// Arguments following `--` are forwarded to each test file instead of being
+// treated as glob patterns.
+const userArgs = ArrayPrototypeSlice(process.argv, 1);
+const separatorIndex = ArrayPrototypeIndexOf(userArgs, '--');
+if (separatorIndex === -1) {
+  options.globPatterns = userArgs;
+} else {
+  options.globPatterns = ArrayPrototypeSlice(userArgs, 0, separatorIndex);
+  options.argv = ArrayPrototypeSlice(userArgs, separatorIndex + 1);
+}
 
 debug('test runner configuration:', options);
 run(options).on('test:summary', (data) => {
diff --git a/lib/internal/test_runner/runner.js b/lib/internal/test_runner/runner.js
index b3d1b30b12e5..fcb7aac5d85d 100644
--- a/lib/internal/test_runner/runner.js
+++ b/lib/internal/test_runner/runner.js
@@ -271,6 +271,9 @@ function getRunArgs(path, { forceExit,
     ArrayPrototypePush(runArgs, '--test');
     ArrayPrototypePush(runArgs, '--test-isolation=none');
     ArrayPrototypePushApply(runArgs, hasFiles ? testFiles : globPatterns ?? []);
+    if (suppliedArgs.length > 0) {
+      ArrayPrototypePush(runArgs, '--');
+    }
   } else {
     ArrayPrototypePush(runArgs, path);
   }
diff --git a/test/parallel/test-runner-cli-argv.js b/test/parallel/test-runner-cli-argv.js
new file mode 100644
index 000000000000..ec4e7c6c1c08
--- /dev/null
+++ b/test/parallel/test-runner-cli-argv.js
@@ -0,0 +1,19 @@
+'use strict';
+
+// https://github.com/nodejs/node/issues/61852
+// Arguments following `--` are forwarded to each test file.
+require('../common');
+const assert = require('assert');
+const { spawnSync } = require('child_process');
+const fixtures = require('../common/fixtures');
+
+const fixture = fixtures.path('test-runner', 'print-arguments.js');
+
+{
+  const args = ['--test', '--test-reporter=tap', fixture, '--', '--a-custom-argument'];
+  const child = spawnSync(process.execPath, args);
+
+  assert.strictEqual(child.stderr.toString(), '');
+  assert.match(child.stdout.toString(), /# pass 1/);
+  assert.strictEqual(child.status, 0);
+}

From 04e330617369cb79fef577da236c52f04380023c Mon Sep 17 00:00:00 2001
From: Matteo Collina <hello@matteocollina.com>
Date: Wed, 21 Oct 2026 17:47:59 -0700
Subject: [PATCH 2/2] doc: add changes entry for --test argument forwarding

Signed-off-by: Matteo Collina <hello@matteocollina.com>
---
 doc/api/cli.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/doc/api/cli.md b/doc/api/cli.md
index 7230231decd4..04be5def3933 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -3147,6 +3147,9 @@ added:
   - v18.1.0
   - v16.17.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/66911
+    description: Arguments following `--` are now passed to each test file.
   - version: v20.0.0
     pr-url: https://github.com/nodejs/node/pull/46983
     description: The test runner is now stable.