From 61c9ba18e876dfa410a0813251186ed4573c6691 Mon Sep 17 00:00:00 2001
From: Raz Luvaton <16746759+rluvaton@users.noreply.github.com>
Date: Wed, 5 Jul 2023 06:57:28 +0300
Subject: [PATCH] test_runner: add shards support

PR-URL: https://github.com/nodejs/node/pull/48639
Reviewed-By: Moshe Atlow <moshe@atlow.co.il>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
---
 doc/api/cli.md                         |  22 +++
 doc/api/test.md                        |   5 +
 doc/node.1                             |   3 +
 lib/internal/main/test_runner.js       |  37 ++++-
 lib/internal/test_runner/runner.js     |  34 ++++-
 src/node_options.cc                    |   4 +
 src/node_options.h                     |   1 +
 test/fixtures/test-runner/shards/a.cjs |   4 +
 test/fixtures/test-runner/shards/b.cjs |   4 +
 test/fixtures/test-runner/shards/c.cjs |   4 +
 test/fixtures/test-runner/shards/d.cjs |   4 +
 test/fixtures/test-runner/shards/e.cjs |   4 +
 test/fixtures/test-runner/shards/f.cjs |   4 +
 test/fixtures/test-runner/shards/g.cjs |   4 +
 test/fixtures/test-runner/shards/h.cjs |   4 +
 test/fixtures/test-runner/shards/i.cjs |   4 +
 test/fixtures/test-runner/shards/j.cjs |   4 +
 test/parallel/test-runner-cli.js       | 133 ++++++++++++++++++
 test/parallel/test-runner-run.mjs      | 178 +++++++++++++++++++++++++
 19 files changed, 453 insertions(+), 4 deletions(-)
 create mode 100644 test/fixtures/test-runner/shards/a.cjs
 create mode 100644 test/fixtures/test-runner/shards/b.cjs
 create mode 100644 test/fixtures/test-runner/shards/c.cjs
 create mode 100644 test/fixtures/test-runner/shards/d.cjs
 create mode 100644 test/fixtures/test-runner/shards/e.cjs
 create mode 100644 test/fixtures/test-runner/shards/f.cjs
 create mode 100644 test/fixtures/test-runner/shards/g.cjs
 create mode 100644 test/fixtures/test-runner/shards/h.cjs
 create mode 100644 test/fixtures/test-runner/shards/i.cjs
 create mode 100644 test/fixtures/test-runner/shards/j.cjs

diff --git a/doc/api/cli.md b/doc/api/cli.md
index 47e03a29763671..e8b21861d24850 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -1500,6 +1500,27 @@ changes:
 Configures the test runner to only execute top level tests that have the `only`
 option set.
 
+### `--test-shard`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Test suite shard to execute in a format of `<index>/<total>`, where
+
+`index` is a positive integer, index of divided parts
+`total` is a positive integer, total of divided part
+This command will divide all tests files into `total` equal parts,
+and will run only those that happen to be in an `index` part.
+
+For example, to split your tests suite into three parts, use this:
+
+```bash
+node --test --test-shard=1/3
+node --test --test-shard=2/3
+node --test --test-shard=3/3
+```
+
 ### `--throw-deprecation`
 
 <!-- YAML
@@ -2177,6 +2198,7 @@ Node.js options that are allowed are:
 * `--test-only`
 * `--test-reporter-destination`
 * `--test-reporter`
+* `--test-shard`
 * `--throw-deprecation`
 * `--title`
 * `--tls-cipher-list`
diff --git a/doc/api/test.md b/doc/api/test.md
index 02a71ee3ecfd67..a6b8ab26a50051 100644
--- a/doc/api/test.md
+++ b/doc/api/test.md
@@ -874,6 +874,11 @@ changes:
     If unspecified, subtests inherit this value from their parent.
     **Default:** `Infinity`.
   * `watch` {boolean} Whether to run in watch mode or not. **Default:** `false`.
+  * `shard` {Object} Running tests in a specific shard. **Default:** `undefined`.
+    * `index` {number} is a positive integer between 1 and `<total>`
+      that specifies the index of the shard to run. This option is _required_.
+    * `total` {number} is a positive integer that specifies the total number
+      of shards to split the test files to. This option is _required_.
 * Returns: {TestsStream}
 
 ```mjs
diff --git a/doc/node.1 b/doc/node.1
index 90d0e42e90deb4..d7095e90fdf4d6 100644
--- a/doc/node.1
+++ b/doc/node.1
@@ -424,6 +424,9 @@ The destination for the corresponding test reporter.
 Configures the test runner to only execute top level tests that have the `only`
 option set.
 .
+.It Fl -test-shard
+Test suite shard to execute in a format of <index>/<total>.
+.
 .It Fl -throw-deprecation
 Throw errors for deprecations.
 .
diff --git a/lib/internal/main/test_runner.js b/lib/internal/main/test_runner.js
index 5ce9e51e4b6af6..064731d77bede1 100644
--- a/lib/internal/main/test_runner.js
+++ b/lib/internal/main/test_runner.js
@@ -8,6 +8,16 @@ const { isUsingInspector } = require('internal/util/inspector');
 const { run } = require('internal/test_runner/runner');
 const { setupTestReporters } = require('internal/test_runner/utils');
 const { exitCodes: { kGenericUserError } } = internalBinding('errors');
+const {
+  codes: {
+    ERR_INVALID_ARG_VALUE,
+  },
+} = require('internal/errors');
+const {
+  NumberParseInt,
+  RegExpPrototypeExec,
+  StringPrototypeSplit,
+} = primordials;
 
 prepareMainThreadExecution(false);
 markBootstrapComplete();
@@ -22,7 +32,32 @@ if (isUsingInspector()) {
   inspectPort = process.debugPort;
 }
 
-run({ concurrency, inspectPort, watch: getOptionValue('--watch'), setup: setupTestReporters })
+let shard;
+const shardOption = getOptionValue('--test-shard');
+if (shardOption) {
+  if (!RegExpPrototypeExec(/^\d+\/\d+$/, shardOption)) {
+    process.exitCode = kGenericUserError;
+
+    throw new ERR_INVALID_ARG_VALUE(
+      '--test-shard',
+      shardOption,
+      'must be in the form of <index>/<total>',
+    );
+  }
+
+  const { 0: indexStr, 1: totalStr } = StringPrototypeSplit(shardOption, '/');
+
+  const index = NumberParseInt(indexStr, 10);
+  const total = NumberParseInt(totalStr, 10);
+
+  shard = {
+    __proto__: null,
+    index,
+    total,
+  };
+}
+
+run({ concurrency, inspectPort, watch: getOptionValue('--watch'), setup: setupTestReporters, shard })
 .once('test:fail', () => {
   process.exitCode = kGenericUserError;
 });
diff --git a/lib/internal/test_runner/runner.js b/lib/internal/test_runner/runner.js
index 09d0df2e660e71..0f2749fd15f0ea 100644
--- a/lib/internal/test_runner/runner.js
+++ b/lib/internal/test_runner/runner.js
@@ -39,10 +39,18 @@ const console = require('internal/console/global');
 const {
   codes: {
     ERR_INVALID_ARG_TYPE,
+    ERR_INVALID_ARG_VALUE,
     ERR_TEST_FAILURE,
+    ERR_OUT_OF_RANGE,
   },
 } = require('internal/errors');
-const { validateArray, validateBoolean, validateFunction } = require('internal/validators');
+const {
+  validateArray,
+  validateBoolean,
+  validateFunction,
+  validateObject,
+  validateInteger,
+} = require('internal/validators');
 const { getInspectPort, isUsingInspector, isInspectorMessage } = require('internal/util/inspector');
 const { isRegExp } = require('internal/util/types');
 const { kEmptyObject } = require('internal/util');
@@ -460,7 +468,7 @@ function run(options) {
   if (options === null || typeof options !== 'object') {
     options = kEmptyObject;
   }
-  let { testNamePatterns } = options;
+  let { testNamePatterns, shard } = options;
   const { concurrency, timeout, signal, files, inspectPort, watch, setup } = options;
 
   if (files != null) {
@@ -469,6 +477,22 @@ function run(options) {
   if (watch != null) {
     validateBoolean(watch, 'options.watch');
   }
+  if (shard != null) {
+    validateObject(shard, 'options.shard');
+    // Avoid re-evaluating the shard object in case it's a getter
+    shard = { __proto__: null, index: shard.index, total: shard.total };
+
+    validateInteger(shard.total, 'options.shard.total', 1);
+    validateInteger(shard.index, 'options.shard.index');
+
+    if (shard.index <= 0 || shard.total < shard.index) {
+      throw new ERR_OUT_OF_RANGE('options.shard.index', `>= 1 && <= ${shard.total} ("options.shard.total")`, shard.index);
+    }
+
+    if (watch) {
+      throw new ERR_INVALID_ARG_VALUE('options.shard', watch, 'shards not supported with watch mode');
+    }
+  }
   if (setup != null) {
     validateFunction(setup, 'options.setup');
   }
@@ -490,7 +514,11 @@ function run(options) {
   }
 
   const root = createTestTree({ concurrency, timeout, signal });
-  const testFiles = files ?? createTestFileList();
+  let testFiles = files ?? createTestFileList();
+
+  if (shard) {
+    testFiles = ArrayPrototypeFilter(testFiles, (_, index) => index % shard.total === shard.index - 1);
+  }
 
   let postRun = () => root.postRun();
   let filesWatcher;
diff --git a/src/node_options.cc b/src/node_options.cc
index 0e7c38722dd860..c02752464c4ab5 100644
--- a/src/node_options.cc
+++ b/src/node_options.cc
@@ -596,6 +596,10 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             "run tests with 'only' option set",
             &EnvironmentOptions::test_only,
             kAllowedInEnvvar);
+  AddOption("--test-shard",
+            "run test at specific shard",
+            &EnvironmentOptions::test_shard,
+            kAllowedInEnvvar);
   AddOption("--test-udp-no-try-send", "",  // For testing only.
             &EnvironmentOptions::test_udp_no_try_send);
   AddOption("--throw-deprecation",
diff --git a/src/node_options.h b/src/node_options.h
index e0d338f203b0c4..bb8b68894b4430 100644
--- a/src/node_options.h
+++ b/src/node_options.h
@@ -165,6 +165,7 @@ class EnvironmentOptions : public Options {
   std::vector<std::string> test_reporter_destination;
   bool test_only = false;
   bool test_udp_no_try_send = false;
+  std::string test_shard;
   bool throw_deprecation = false;
   bool trace_atomics_wait = false;
   bool trace_deprecation = false;
diff --git a/test/fixtures/test-runner/shards/a.cjs b/test/fixtures/test-runner/shards/a.cjs
new file mode 100644
index 00000000000000..650e61eda80b09
--- /dev/null
+++ b/test/fixtures/test-runner/shards/a.cjs
@@ -0,0 +1,4 @@
+'use strict';
+const test = require('node:test');
+
+test('a.cjs this should pass');
diff --git a/test/fixtures/test-runner/shards/b.cjs b/test/fixtures/test-runner/shards/b.cjs
new file mode 100644
index 00000000000000..12677e2505cdcf
--- /dev/null
+++ b/test/fixtures/test-runner/shards/b.cjs
@@ -0,0 +1,4 @@
+'use strict';
+const test = require('node:test');
+
+test('b.cjs this should pass');
diff --git a/test/fixtures/test-runner/shards/c.cjs b/test/fixtures/test-runner/shards/c.cjs
new file mode 100644
index 00000000000000..4a4c938a74d44f
--- /dev/null
+++ b/test/fixtures/test-runner/shards/c.cjs
@@ -0,0 +1,4 @@
+'use strict';
+const test = require('node:test');
+
+test('c.cjs this should pass');
diff --git a/test/fixtures/test-runner/shards/d.cjs b/test/fixtures/test-runner/shards/d.cjs
new file mode 100644
index 00000000000000..d643276b112801
--- /dev/null
+++ b/test/fixtures/test-runner/shards/d.cjs
@@ -0,0 +1,4 @@
+'use strict';
+const test = require('node:test');
+
+test('d.cjs this should pass');
diff --git a/test/fixtures/test-runner/shards/e.cjs b/test/fixtures/test-runner/shards/e.cjs
new file mode 100644
index 00000000000000..e4af3d49fcc335
--- /dev/null
+++ b/test/fixtures/test-runner/shards/e.cjs
@@ -0,0 +1,4 @@
+'use strict';
+const test = require('node:test');
+
+test('e.cjs this should pass');
diff --git a/test/fixtures/test-runner/shards/f.cjs b/test/fixtures/test-runner/shards/f.cjs
new file mode 100644
index 00000000000000..4ed5c4eb4ed841
--- /dev/null
+++ b/test/fixtures/test-runner/shards/f.cjs
@@ -0,0 +1,4 @@
+'use strict';
+const test = require('node:test');
+
+test('f.cjs this should pass');
diff --git a/test/fixtures/test-runner/shards/g.cjs b/test/fixtures/test-runner/shards/g.cjs
new file mode 100644
index 00000000000000..da8d297d35b4b7
--- /dev/null
+++ b/test/fixtures/test-runner/shards/g.cjs
@@ -0,0 +1,4 @@
+'use strict';
+const test = require('node:test');
+
+test('g.cjs this should pass');
diff --git a/test/fixtures/test-runner/shards/h.cjs b/test/fixtures/test-runner/shards/h.cjs
new file mode 100644
index 00000000000000..502250974dbc4b
--- /dev/null
+++ b/test/fixtures/test-runner/shards/h.cjs
@@ -0,0 +1,4 @@
+'use strict';
+const test = require('node:test');
+
+test('h.cjs this should pass');
diff --git a/test/fixtures/test-runner/shards/i.cjs b/test/fixtures/test-runner/shards/i.cjs
new file mode 100644
index 00000000000000..42df5e74c9c483
--- /dev/null
+++ b/test/fixtures/test-runner/shards/i.cjs
@@ -0,0 +1,4 @@
+'use strict';
+const test = require('node:test');
+
+test('i.cjs this should pass');
diff --git a/test/fixtures/test-runner/shards/j.cjs b/test/fixtures/test-runner/shards/j.cjs
new file mode 100644
index 00000000000000..e2167de43d9b94
--- /dev/null
+++ b/test/fixtures/test-runner/shards/j.cjs
@@ -0,0 +1,4 @@
+'use strict';
+const test = require('node:test');
+
+test('j.cjs this should pass');
diff --git a/test/parallel/test-runner-cli.js b/test/parallel/test-runner-cli.js
index 60da7b67037456..496f53e23ea3a6 100644
--- a/test/parallel/test-runner-cli.js
+++ b/test/parallel/test-runner-cli.js
@@ -4,6 +4,7 @@ require('../common');
 const assert = require('assert');
 const { spawnSync } = require('child_process');
 const { join } = require('path');
+const { readdirSync } = require('fs');
 const fixtures = require('../common/fixtures');
 const testFixtures = fixtures.path('test-runner');
 
@@ -210,3 +211,135 @@ const testFixtures = fixtures.path('test-runner');
   const stdout = child.stdout.toString();
   assert.match(stdout, /ok 1 - this should pass/);
 }
+
+{
+  // --test-shard option validation
+  const args = ['--test', '--test-shard=1', join(testFixtures, 'index.js')];
+  const child = spawnSync(process.execPath, args, { cwd: testFixtures });
+
+  assert.strictEqual(child.status, 1);
+  assert.strictEqual(child.signal, null);
+  assert.match(child.stderr.toString(), /The argument '--test-shard' must be in the form of <index>\/<total>\. Received '1'/);
+  const stdout = child.stdout.toString();
+  assert.strictEqual(stdout, '');
+}
+
+{
+  // --test-shard option validation
+  const args = ['--test', '--test-shard=1/2/3', join(testFixtures, 'index.js')];
+  const child = spawnSync(process.execPath, args, { cwd: testFixtures });
+
+  assert.strictEqual(child.status, 1);
+  assert.strictEqual(child.signal, null);
+  assert.match(child.stderr.toString(), /The argument '--test-shard' must be in the form of <index>\/<total>\. Received '1\/2\/3'/);
+  const stdout = child.stdout.toString();
+  assert.strictEqual(stdout, '');
+}
+
+{
+  // --test-shard option validation
+  const args = ['--test', '--test-shard=0/3', join(testFixtures, 'index.js')];
+  const child = spawnSync(process.execPath, args, { cwd: testFixtures });
+
+  assert.strictEqual(child.status, 1);
+  assert.strictEqual(child.signal, null);
+  assert.match(child.stderr.toString(), /The value of "options\.shard\.index" is out of range\. It must be >= 1 && <= 3 \("options\.shard\.total"\)\. Received 0/);
+  const stdout = child.stdout.toString();
+  assert.strictEqual(stdout, '');
+}
+
+{
+  // --test-shard option validation
+  const args = ['--test', '--test-shard=0xf/20abcd', join(testFixtures, 'index.js')];
+  const child = spawnSync(process.execPath, args, { cwd: testFixtures });
+
+  assert.strictEqual(child.status, 1);
+  assert.strictEqual(child.signal, null);
+  assert.match(child.stderr.toString(), /The argument '--test-shard' must be in the form of <index>\/<total>\. Received '0xf\/20abcd'/);
+  const stdout = child.stdout.toString();
+  assert.strictEqual(stdout, '');
+}
+
+{
+  // --test-shard option validation
+  const args = ['--test', '--test-shard=hello', join(testFixtures, 'index.js')];
+  const child = spawnSync(process.execPath, args, { cwd: testFixtures });
+
+  assert.strictEqual(child.status, 1);
+  assert.strictEqual(child.signal, null);
+  assert.match(child.stderr.toString(), /The argument '--test-shard' must be in the form of <index>\/<total>\. Received 'hello'/);
+  const stdout = child.stdout.toString();
+  assert.strictEqual(stdout, '');
+}
+
+{
+  // --test-shard option, first shard
+  const shardsTestPath = join(testFixtures, 'shards');
+  const allShardsTestsFiles = readdirSync(shardsTestPath).map((file) => join(shardsTestPath, file));
+  const args = [
+    '--test',
+    '--test-shard=1/2',
+    ...allShardsTestsFiles,
+  ];
+  const child = spawnSync(process.execPath, args);
+
+  assert.strictEqual(child.status, 0);
+  assert.strictEqual(child.signal, null);
+  assert.strictEqual(child.stderr.toString(), '');
+  const stdout = child.stdout.toString();
+  assert.match(stdout, /# Subtest: a\.cjs this should pass/);
+  assert.match(stdout, /ok 1 - a\.cjs this should pass/);
+
+  assert.match(stdout, /# Subtest: c\.cjs this should pass/);
+  assert.match(stdout, /ok 2 - c\.cjs this should pass/);
+
+  assert.match(stdout, /# Subtest: e\.cjs this should pass/);
+  assert.match(stdout, /ok 3 - e\.cjs this should pass/);
+
+  assert.match(stdout, /# Subtest: g\.cjs this should pass/);
+  assert.match(stdout, /ok 4 - g\.cjs this should pass/);
+
+  assert.match(stdout, /# Subtest: i\.cjs this should pass/);
+  assert.match(stdout, /ok 5 - i\.cjs this should pass/);
+
+  assert.match(stdout, /# tests 5/);
+  assert.match(stdout, /# pass 5/);
+  assert.match(stdout, /# fail 0/);
+  assert.match(stdout, /# skipped 0/);
+}
+
+{
+  // --test-shard option, last shard
+  const shardsTestPath = join(testFixtures, 'shards');
+  const allShardsTestsFiles = readdirSync(shardsTestPath).map((file) => join(shardsTestPath, file));
+  const args = [
+    '--test',
+    '--test-shard=2/2',
+    ...allShardsTestsFiles,
+  ];
+  const child = spawnSync(process.execPath, args);
+
+  assert.strictEqual(child.status, 0);
+  assert.strictEqual(child.signal, null);
+  assert.strictEqual(child.stderr.toString(), '');
+  const stdout = child.stdout.toString();
+  assert.match(stdout, /# Subtest: b\.cjs this should pass/);
+  assert.match(stdout, /ok 1 - b\.cjs this should pass/);
+
+  assert.match(stdout, /# Subtest: d\.cjs this should pass/);
+  assert.match(stdout, /ok 2 - d\.cjs this should pass/);
+
+  assert.match(stdout, /# Subtest: f\.cjs this should pass/);
+  assert.match(stdout, /ok 3 - f\.cjs this should pass/);
+
+  assert.match(stdout, /# Subtest: h\.cjs this should pass/);
+  assert.match(stdout, /ok 4 - h\.cjs this should pass/);
+
+  assert.match(stdout, /# Subtest: j\.cjs this should pass/);
+  assert.match(stdout, /ok 5 - j\.cjs this should pass/);
+
+  assert.match(stdout, /# tests 5/);
+  assert.match(stdout, /# pass 5/);
+  assert.match(stdout, /# fail 0/);
+  assert.match(stdout, /# skipped 0/);
+}
diff --git a/test/parallel/test-runner-run.mjs b/test/parallel/test-runner-run.mjs
index 0e92abd92bb5a2..b5c41b8ae925de 100644
--- a/test/parallel/test-runner-run.mjs
+++ b/test/parallel/test-runner-run.mjs
@@ -142,4 +142,182 @@ describe('require(\'node:test\').run', { concurrency: true }, () => {
         }
       });
   });
+
+  describe('sharding', () => {
+    const shardsTestsFixtures = fixtures.path('test-runner', 'shards');
+    const shardsTestsFiles = [
+      'a.cjs',
+      'b.cjs',
+      'c.cjs',
+      'd.cjs',
+      'e.cjs',
+      'f.cjs',
+      'g.cjs',
+      'h.cjs',
+      'i.cjs',
+      'j.cjs',
+    ].map((file) => join(shardsTestsFixtures, file));
+
+    describe('validation', () => {
+      it('should require shard.total when having shard option', () => {
+        assert.throws(() => run({ files: shardsTestsFiles, shard: {} }), {
+          name: 'TypeError',
+          code: 'ERR_INVALID_ARG_TYPE',
+          message: 'The "options.shard.total" property must be of type number. Received undefined'
+        });
+      });
+
+      it('should require shard.index when having shards option', () => {
+        assert.throws(() => run({
+          files: shardsTestsFiles,
+          shard: {
+            total: 5
+          }
+        }), {
+          name: 'TypeError',
+          code: 'ERR_INVALID_ARG_TYPE',
+          message: 'The "options.shard.index" property must be of type number. Received undefined'
+        });
+      });
+
+      it('should require shard.total to be greater than 0 when having shard option', () => {
+        assert.throws(() => run({
+          files: shardsTestsFiles,
+          shard: {
+            total: 0,
+            index: 1
+          }
+        }), {
+          name: 'RangeError',
+          code: 'ERR_OUT_OF_RANGE',
+          message:
+            'The value of "options.shard.total" is out of range. It must be >= 1 && <= 9007199254740991. Received 0'
+        });
+      });
+
+      it('should require shard.index to be greater than 0 when having shard option', () => {
+        assert.throws(() => run({
+          files: shardsTestsFiles,
+          shard: {
+            total: 6,
+            index: 0
+          }
+        }), {
+          name: 'RangeError',
+          code: 'ERR_OUT_OF_RANGE',
+          // eslint-disable-next-line max-len
+          message: 'The value of "options.shard.index" is out of range. It must be >= 1 && <= 6 ("options.shard.total"). Received 0'
+        });
+      });
+
+      it('should require shard.index to not be greater than the shards total when having shard option', () => {
+        assert.throws(() => run({
+          files: shardsTestsFiles,
+          shard: {
+            total: 6,
+            index: 7
+          }
+        }), {
+          name: 'RangeError',
+          code: 'ERR_OUT_OF_RANGE',
+          // eslint-disable-next-line max-len
+          message: 'The value of "options.shard.index" is out of range. It must be >= 1 && <= 6 ("options.shard.total"). Received 7'
+        });
+      });
+
+      it('should require watch mode to be disabled when having shard option', () => {
+        assert.throws(() => run({
+          files: shardsTestsFiles,
+          watch: true,
+          shard: {
+            total: 6,
+            index: 1
+          }
+        }), {
+          name: 'TypeError',
+          code: 'ERR_INVALID_ARG_VALUE',
+          message: 'The property \'options.shard\' shards not supported with watch mode. Received true'
+        });
+      });
+    });
+
+    it('should run only the tests files matching the shard index', async () => {
+      const stream = run({
+        files: shardsTestsFiles,
+        shard: {
+          total: 5,
+          index: 1
+        }
+      });
+
+      const executedTestFiles = [];
+      stream.on('test:fail', common.mustNotCall());
+      stream.on('test:pass', (passedTest) => {
+        executedTestFiles.push(passedTest.file);
+      });
+      // eslint-disable-next-line no-unused-vars
+      for await (const _ of stream) ;
+
+      assert.deepStrictEqual(executedTestFiles, [
+        join(shardsTestsFixtures, 'a.cjs'),
+        join(shardsTestsFixtures, 'f.cjs'),
+      ]);
+    });
+
+    it('different shards should not run the same file', async () => {
+      const executedTestFiles = [];
+
+      const testStreams = [];
+      const shards = 5;
+      for (let i = 1; i <= shards; i++) {
+        const stream = run({
+          files: shardsTestsFiles,
+          shard: {
+            total: shards,
+            index: i
+          }
+        });
+        stream.on('test:fail', common.mustNotCall());
+        stream.on('test:pass', (passedTest) => {
+          executedTestFiles.push(passedTest.file);
+        });
+        testStreams.push(stream);
+      }
+
+      await Promise.all(testStreams.map(async (stream) => {
+        // eslint-disable-next-line no-unused-vars
+        for await (const _ of stream) ;
+      }));
+
+      assert.deepStrictEqual(executedTestFiles, [...new Set(executedTestFiles)]);
+    });
+
+    it('combination of all shards should be all the tests', async () => {
+      const executedTestFiles = [];
+
+      const testStreams = [];
+      const shards = 5;
+      for (let i = 1; i <= shards; i++) {
+        const stream = run({
+          files: shardsTestsFiles,
+          shard: {
+            total: shards,
+            index: i
+          }
+        });
+        stream.on('test:fail', common.mustNotCall());
+        stream.on('test:pass', (passedTest) => {
+          executedTestFiles.push(passedTest.file);
+        });
+        testStreams.push(stream);
+      }
+
+      await Promise.all(testStreams.map(async (stream) => {
+        // eslint-disable-next-line no-unused-vars
+        for await (const _ of stream) ;
+      }));
+
+      assert.deepStrictEqual(executedTestFiles.sort(), [...shardsTestsFiles].sort());
+    });
+  });
 });