test_runner, cli: add --test-concurrency flag

This commit adds a new --test-concurrency CLI flag that controls
the parallelism of the test runner CLI.
PR-URL: #49996Fixes: #49487
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Moshe Atlow <moshe@atlow.co.il>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Chemi Atlow <chemi@atlow.co.il>

Author: cjihrig

doc/api/cli.md

@@ -1654,6 +1654,15 @@ Starts the Node.js command line test runner. This flag cannot be combined with
 See the documentation on [running tests from the command line][]
 for more details.
 
+### `--test-concurrency`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+The maximum number of test files that the test runner CLI will execute
+concurrently. The default value is `os.availableParallelism() - 1`.
+
 ### `--test-name-pattern`
 
 <!-- YAML

doc/api/test.md

@@ -350,11 +350,12 @@ in the [test runner execution model][] section.
 
 ### Test runner execution model
 
-Each matching test file is executed in a separate child process. If the child
-process finishes with an exit code of 0, the test is considered passing.
-Otherwise, the test is considered to be a failure. Test files must be
-executable by Node.js, but are not required to use the `node:test` module
-internally.
+Each matching test file is executed in a separate child process. The maximum
+number of child processes running at any time is controlled by the
+[`--test-concurrency`][] flag. If the child process finishes with an exit code
+of 0, the test is considered passing. Otherwise, the test is considered to be a
+failure. Test files must be executable by Node.js, but are not required to use
+the `node:test` module internally.
 
 Each test file is executed as if it was a regular script. That is, if the test
 file itself uses `node:test` to define tests, all of those tests will be
@@ -2551,6 +2552,7 @@ added:
 [TTY]: tty.md
 [`--experimental-test-coverage`]: cli.md#--experimental-test-coverage
 [`--import`]: cli.md#--importmodule
+[`--test-concurrency`]: cli.md#--test-concurrency
 [`--test-name-pattern`]: cli.md#--test-name-pattern
 [`--test-only`]: cli.md#--test-only
 [`--test-reporter-destination`]: cli.md#--test-reporter-destination

doc/node.1

@@ -418,6 +418,10 @@ Specify the minimum allocation from the OpenSSL secure heap. The default is 2. T
 .ItFl-test
 Starts the Node.js command line test runner.
 .
+.ItFl-test-concurrency
+The maximum number of test files that the test runner CLI will execute
+concurrently.
+.
 .ItFl-test-name-pattern
 A regular expression that configures the test runner to only execute tests
 whose name matches the provided pattern.

lib/internal/main/test_runner.js

@@ -22,7 +22,7 @@ const {
 prepareMainThreadExecution(false);
 markBootstrapComplete();
 
-letconcurrency=true;
+letconcurrency=getOptionValue('--test-concurrency')||true;
 letinspectPort;
 
 if(isUsingInspector()){

src/node_options.cc

@@ -595,6 +595,9 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
 AddOption("--test",
 "launch test runner on startup",
  &EnvironmentOptions::test_runner);
+AddOption("--test-concurrency",
+"specify test runner concurrency",
+ &EnvironmentOptions::test_runner_concurrency);
 AddOption("--experimental-test-coverage",
 "enable code coverage in the test runner",
  &EnvironmentOptions::test_runner_coverage);

src/node_options.h

@@ -159,6 +159,7 @@ class EnvironmentOptions : public Options {
  std::string env_file;
 bool has_env_file_string = false;
 bool test_runner = false;
+uint64_t test_runner_concurrency = 0;
 bool test_runner_coverage = false;
  std::vector<std::string> test_name_pattern;
  std::vector<std::string> test_reporter;

test/parallel/test-runner-cli-concurrency.js

@@ -0,0 +1,45 @@
+'use strict';
+constcommon=require('../common');
+consttmpdir=require('../common/tmpdir');
+const{ deepStrictEqual, strictEqual }=require('node:assert');
+const{ spawnSync }=require('node:child_process');
+const{ readdirSync, writeFileSync }=require('node:fs');
+const{ join }=require('node:path');
+const{ beforeEach, test }=require('node:test');
+
+functioncreateTestFile(name){
+writeFileSync(join(tmpdir.path,name),`
+ const fs = require('node:fs');
+
+ fs.unlinkSync(__filename);
+ setTimeout(() => {}, 1_000_000_000);
+ `);
+}
+
+beforeEach(()=>{
+tmpdir.refresh();
+createTestFile('test-1.js');
+createTestFile('test-2.js');
+});
+
+test('concurrency of one',()=>{
+constcp=spawnSync(process.execPath,['--test','--test-concurrency=1'],{
+cwd: tmpdir.path,
+timeout: common.platformTimeout(1000),
+});
+
+strictEqual(cp.stderr.toString(),'');
+strictEqual(cp.error.code,'ETIMEDOUT');
+deepStrictEqual(readdirSync(tmpdir.path),['test-2.js']);
+});
+
+test('concurrency of two',()=>{
+constcp=spawnSync(process.execPath,['--test','--test-concurrency=2'],{
+cwd: tmpdir.path,
+timeout: common.platformTimeout(1000),
+});
+
+strictEqual(cp.stderr.toString(),'');
+strictEqual(cp.error.code,'ETIMEDOUT');
+deepStrictEqual(readdirSync(tmpdir.path),[]);
+});