Add support for execution sharding (#2600)

Co-authored-by: David Goss <[email protected]>

Author: agologan

CHANGELOG.md

@@ -10,6 +10,7 @@ Please see [CONTRIBUTING.md](./CONTRIBUTING.md) on how to contribute to Cucumber
 ## [Unreleased]
 ### Added
 - Export configuration types ([#2598](https://github.com/cucumber/cucumber-js/pull/2598))
+- Add support for execution sharding ([#2303](https://github.com/cucumber/cucumber-js/pull/2303)) by [@agologan](https://github.com/agologan)
 
 ## [12.1.0] - 2025-07-19
 ### Added

compatibility/cck_spec.ts

@@ -39,6 +39,7 @@ describe('Cucumber Compatibility Kit', () => {
           names: [],
           tagExpression: '',
           order: 'defined',
+          shard: '',
         },
         support: {
           requireModules: ['ts-node/register'],

exports/api/report.api.md

@@ -28,6 +28,7 @@ export interface IConfiguration {
     requireModule: string[];
     retry: number;
     retryTagFilter: string;
+    shard: string;
     strict: boolean;
     tags: string;
     worldParameters: JsonObject;
@@ -146,6 +147,7 @@ export interface ISourcesCoordinates {
     names: string[];
     order: IPickleOrder;
     paths: string[];
+    shard?: string;
     tagExpression: string;
 }
 

exports/root/report.api.md

@@ -223,6 +223,7 @@ export interface IConfiguration {
     requireModule: string[];
     retry: number;
     retryTagFilter: string;
+    shard: string;
     strict: boolean;
     tags: string;
     worldParameters: JsonObject;

features/sharding.feature

@@ -0,0 +1,77 @@
+Feature: Running scenarios using sharding
+  As a developer running features
+  I want a way to split my test execution across multiple independent processes
+  So that I save time in my build pipeline
+
+  Background:
+    Given a file named "features/a.feature" with:
+      """
+      Feature: some feature
+        @a
+        Scenario: first scenario
+          Given a step
+
+        @b
+        Scenario Outline: second scenario - <ID>
+          Given a step
+
+          @c
+          Examples:
+            | ID |
+            | X  |
+            | Y  |
+
+          @d
+          Examples:
+            | ID |
+            | Z  |
+      """
+    And a file named "features/step_definitions/cucumber_steps.js" with:
+      """
+      const {Given} = require('@cucumber/cucumber')
+
+      Given('a step', function() {})
+      """
+
+  Scenario: run a single scenario
+    When I run cucumber-js with `--shard 1/5`
+    Then it passes
+    And it runs the scenario "first scenario"
+
+  Scenario: run every other scenario starting at 1
+    When I run cucumber-js with `--shard 1/2`
+    Then it passes
+    And it runs the scenarios:
+      | NAME |
+      | first scenario      |
+      | second scenario - Y |
+
+  Scenario: run every 3rd scenario starting at 1
+    When I run cucumber-js with `--shard 1/3`
+    Then it passes
+    And it runs the scenarios:
+      | NAME |
+      | first scenario      |
+      | second scenario - Z |
+
+  Scenario: run even scenarios
+    When I run cucumber-js with `--shard 2/2`
+    Then it passes
+    And it runs the scenarios:
+      | NAME |
+      | second scenario - X |
+      | second scenario - Z |
+
+  Scenario: no scenarios in shard
+    When I run cucumber-js with `--shard 5/5`
+    Then it passes
+    And it runs 0 scenarios
+
+  Scenario: invalid shard option
+    When I run cucumber-js with `--shard whoops`
+    Then it fails
+    And the error output contains the text:
+    """
+    the shard option must be in the format <index>/<total> (e.g. 1/3)
+    """
+

package.json

@@ -19,7 +19,7 @@
     "Ádám Gólya <[email protected]>",
     "Ahmed Ashour (https://github.com/asashour)",
     "ahulab <[email protected]>",
-    "Alon Diamant <diamant.alon@gmail.com>",
+    "Alexandru Gologan (https://github.com/agologan)",
     "Artem Bronitsky <[email protected]>",
     "Artem Repko <[email protected]>",
     "Artur Kania <[email protected]>",

src/api/convert_configuration.ts

@@ -19,6 +19,7 @@ export async function convertConfiguration(
       names: flatConfiguration.name,
       tagExpression: flatConfiguration.tags,
       order: flatConfiguration.order,
+      shard: flatConfiguration.shard,
     },
     support: {
       requireModules: flatConfiguration.requireModule,

src/api/convert_configuration_spec.ts

@@ -36,6 +36,7 @@ describe('convertConfiguration', () => {
         order: 'defined',
         paths: [],
         tagExpression: '',
+        shard: '',
       },
       support: {
         requireModules: [],

src/api/load_sources_spec.ts

@@ -51,6 +51,7 @@ describe('loadSources', () => {
         paths: [],
         names: [],
         tagExpression: '',
+        shard: '',
       },
       environment
     )
@@ -112,6 +113,7 @@ describe('loadSources', () => {
         paths: ['features/test.feature:8'],
         names: [],
         tagExpression: '',
+        shard: '',
       },
       environment
     )
@@ -127,6 +129,7 @@ describe('loadSources', () => {
         paths: [],
         names: ['two'],
         tagExpression: '',
+        shard: '',
       },
       environment
     )
@@ -142,6 +145,7 @@ describe('loadSources', () => {
         paths: [],
         names: [],
         tagExpression: '@tag2',
+        shard: '',
       },
       environment
     )
@@ -157,6 +161,7 @@ describe('loadSources', () => {
         paths: ['@rerun.txt'],
         names: [],
         tagExpression: '',
+        shard: '',
       },
       environment
     )

src/api/plugins.ts

@@ -1,6 +1,7 @@
 import { PluginManager } from '../plugin'
 import publishPlugin from '../publish'
 import filterPlugin from '../filter'
+import shardingPlugin from '../sharding'
 import { UsableEnvironment } from '../environment'
 import { IRunConfiguration, ISourcesCoordinates } from './types'
 
@@ -37,5 +38,10 @@ export async function initializeForRunCucumber(
     filterPlugin,
     configuration.sources
   )
+  await pluginManager.initCoordinator(
+    'runCucumber',
+    shardingPlugin,
+    configuration.sources
+  )
   return pluginManager
 }