test_runner: add shards support

lib/internal/test_runner/runner.js

@@ -39,10 +39,17 @@ const console = require('internal/console/global');
 const {
   codes: {
     ERR_INVALID_ARG_TYPE,
+    ERR_INVALID_ARG_VALUE,
     ERR_TEST_FAILURE,
   },
 } = require('internal/errors');
-const { validateArray, validateBoolean, validateFunction } = require('internal/validators');
+const {
+  validateArray,
+  validateBoolean,
+  validateFunction,
+  validateObject,
+  validateNumber,
+} = require('internal/validators');
 const { getInspectPort, isUsingInspector, isInspectorMessage } = require('internal/util/inspector');
 const { isRegExp } = require('internal/util/types');
 const { kEmptyObject } = require('internal/util');
@@ -417,14 +424,35 @@ function run(options) {
     options = kEmptyObject;
   }
   let { testNamePatterns } = options;
-  const { concurrency, timeout, signal, files, inspectPort, watch, setup } = options;
+  const { concurrency, timeout, signal, files, inspectPort, watch, setup, shards } = options;
 
   if (files != null) {
     validateArray(files, 'options.files');
   }
   if (watch != null) {
     validateBoolean(watch, 'options.watch');
   }
+  if (shards != null) {
+    validateObject(shards, 'options.shards');
+    validateNumber(shards.total, 'options.shards.total');
+    validateNumber(shards.index, 'options.shards.index');
+
+    if (shards.total <= 0) {
+      throw new ERR_INVALID_ARG_VALUE('options.shards.total', shards.total, 'total shards must be greater than 0');
+    }
+    if (shards.index <= 0) {
+      throw new ERR_INVALID_ARG_VALUE('options.shards.index', shards.index, 'shard index must be greater than 0');
+    }
+    if (shards.total < shards.index) {
+      throw new ERR_INVALID_ARG_VALUE(
+        'options.shards.index', shards.index, 'shard index must be less than total shards',
+      );
+    }
+
+    if (watch) {
+      throw new ERR_INVALID_ARG_VALUE('options.shards', watch, 'shards not supported with watch mode');
+    }
+  }
   if (setup != null) {
     validateFunction(setup, 'options.setup');
   }
@@ -446,7 +474,11 @@ function run(options) {
   }
 
   const root = createTestTree({ concurrency, timeout, signal });
-  const testFiles = files ?? createTestFileList();
+  let testFiles = files ?? createTestFileList();
+
+  if (shards) {
+    testFiles = testFiles.filter((file, index) => (index % shards.total) === (shards.index - 1));
+  }
 
   let postRun = () => root.postRun();
   let filesWatcher;

test/fixtures/test-runner/shards/a.cjs

@@ -0,0 +1,4 @@
+'use strict';
+const test = require('node:test');
+
+test('this should pass');

test/fixtures/test-runner/shards/b.cjs

@@ -0,0 +1,4 @@
+'use strict';
+const test = require('node:test');
+
+test('this should pass');

test/fixtures/test-runner/shards/c.cjs

@@ -0,0 +1,4 @@
+'use strict';
+const test = require('node:test');
+
+test('this should pass');

test/fixtures/test-runner/shards/d.cjs

@@ -0,0 +1,4 @@
+'use strict';
+const test = require('node:test');
+
+test('this should pass');

test/fixtures/test-runner/shards/e.cjs

@@ -0,0 +1,4 @@
+'use strict';
+const test = require('node:test');
+
+test('this should pass');

test/fixtures/test-runner/shards/f.cjs

@@ -0,0 +1,4 @@
+'use strict';
+const test = require('node:test');
+
+test('this should pass');

test/fixtures/test-runner/shards/g.cjs

@@ -0,0 +1,4 @@
+'use strict';
+const test = require('node:test');
+
+test('this should pass');

test/fixtures/test-runner/shards/h.cjs

@@ -0,0 +1,4 @@
+'use strict';
+const test = require('node:test');
+
+test('this should pass');

test/fixtures/test-runner/shards/i.cjs

@@ -0,0 +1,4 @@
+'use strict';
+const test = require('node:test');
+
+test('this should pass');

test/fixtures/test-runner/shards/j.cjs

@@ -0,0 +1,4 @@
+'use strict';
+const test = require('node:test');
+
+test('this should pass');

test/parallel/test-runner-run.mjs

@@ -142,4 +142,179 @@ 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 shards.total when having shards option', () => {
+        assert.throws(() => run({ files: shardsTestsFiles, shards: {} }), {
+          name: 'TypeError',
+          code: 'ERR_INVALID_ARG_TYPE',
+          message: 'The "options.shards.total" property must be of type number. Received undefined'
+        });
+      });
+
+      it('should require shards.index when having shards option', () => {
+        assert.throws(() => run({
+          files: shardsTestsFiles,
+          shards: {
+            total: 5
+          }
+        }), {
+          name: 'TypeError',
+          code: 'ERR_INVALID_ARG_TYPE',
+          message: 'The "options.shards.index" property must be of type number. Received undefined'
+        });
+      });
+
+      it('should require shards.total to be greater than 0 when having shards option', () => {
+        assert.throws(() => run({
+          files: shardsTestsFiles,
+          shards: {
+            total: 0,
+            index: 1
+          }
+        }), {
+          name: 'TypeError',
+          code: 'ERR_INVALID_ARG_VALUE',
+          message: 'The property \'options.shards.total\' total shards must be greater than 0. Received 0'
+        });
+      });
+
+      it('should require shards.index to be greater than 0 when having shards option', () => {
+        assert.throws(() => run({
+          files: shardsTestsFiles,
+          shards: {
+            total: 6,
+            index: 0
+          }
+        }), {
+          name: 'TypeError',
+          code: 'ERR_INVALID_ARG_VALUE',
+          message: 'The property \'options.shards.index\' shard index must be greater than 0. Received 0'
+        });
+      });
+
+      it('should require shards.index to not be greater than the shards total when having shards option', () => {
+        assert.throws(() => run({
+          files: shardsTestsFiles,
+          shards: {
+            total: 6,
+            index: 7
+          }
+        }), {
+          name: 'TypeError',
+          code: 'ERR_INVALID_ARG_VALUE',
+          message: 'The property \'options.shards.index\' shard index must be less than total shards. Received 7'
+        });
+      });
+
+      it('should require watch mode to e disabled when having shards option', () => {
+        assert.throws(() => run({
+          files: shardsTestsFiles,
+          watch: true,
+          shards: {
+            total: 6,
+            index: 1
+          }
+        }), {
+          name: 'TypeError',
+          code: 'ERR_INVALID_ARG_VALUE',
+          message: 'The property \'options.shards\' 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,
+        shards: {
+          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,
+          shards: {
+            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,
+          shards: {
+            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());
+    });
+  });
 });