From 185d6090cd810ef5423e8eddeae5963787fc357e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tobias=20Nie=C3=9Fen?= <tniessen@tnie.de>
Date: Fri, 28 Apr 2023 20:32:08 +0200
Subject: [PATCH] doc,test: fix concurrency option of test()

The documentation appears to still be wrong w.r.t. the meaning of the
concurrency option of the test() function. The implementation appears to
default to Infinity when the option is set to true. Is that intended or
a good idea? I don't know. It certainly makes more sense than what the
documentation says (which is basing the number of concurrent tasks
within a single thread on the number of CPU cores).

This changes the documentation to hopefully match the implementation and
adds a test that rules out the (rather arbitrary) behavior described in
the documentation.

Refs: https://github.com/nodejs/node/issues/47365
Refs: https://github.com/nodejs/node/pull/47642
PR-URL: https://github.com/nodejs/node/pull/47734
Reviewed-By: Moshe Atlow <moshe@atlow.co.il>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
---
 doc/api/test.md                          |  5 ++---
 test/parallel/test-runner-concurrency.js | 17 +++++++++++++++++
 2 files changed, 19 insertions(+), 3 deletions(-)

diff --git a/doc/api/test.md b/doc/api/test.md
index 66f4c661dce7bf..24707512860ffc 100644
--- a/doc/api/test.md
+++ b/doc/api/test.md
@@ -808,9 +808,8 @@ changes:
   properties are supported:
   * `concurrency` {number|boolean} If a number is provided,
     then that many tests would run in parallel within the application thread.
-    If `true`, it would run `os.availableParallelism() - 1` tests in parallel.
-    For subtests, it will be `Infinity` tests in parallel.
-    If `false`, it would only run one test at a time.
+    If `true`, all scheduled asynchronous tests run concurrently within the
+    thread. If `false`, only one test runs at a time.
     If unspecified, subtests inherit this value from their parent.
     **Default:** `false`.
   * `only` {boolean} If truthy, and the test context is configured to run
diff --git a/test/parallel/test-runner-concurrency.js b/test/parallel/test-runner-concurrency.js
index 4f2a99c2734fe8..5a9ac8ec44beef 100644
--- a/test/parallel/test-runner-concurrency.js
+++ b/test/parallel/test-runner-concurrency.js
@@ -7,6 +7,7 @@ const assert = require('node:assert');
 const path = require('node:path');
 const fs = require('node:fs/promises');
 const os = require('node:os');
+const timers = require('node:timers/promises');
 
 tmpdir.refresh();
 
@@ -35,6 +36,22 @@ describe(
   }
 );
 
+// Despite the docs saying so at some point, setting concurrency to true should
+// not limit concurrency to the number of available CPU cores.
+describe('concurrency: true implies Infinity', { concurrency: true }, () => {
+  // The factor 5 is intentionally chosen to be higher than the default libuv
+  // thread pool size.
+  const nTests = 5 * os.availableParallelism();
+  let nStarted = 0;
+  for (let i = 0; i < nTests; i++) {
+    it(`should run test ${i} concurrently`, async () => {
+      assert.strictEqual(nStarted++, i);
+      await timers.setImmediate();
+      assert.strictEqual(nStarted, nTests);
+    });
+  }
+});
+
 {
   // Make sure tests run in order when root concurrency is 1 (default)
   const tree = [];