fix: sharding in combination with the --url cli option

src/config/jest-filename-sequencer.test.ts

@@ -0,0 +1,119 @@
+import FilenameSortedTestSequencer from './jest-filename-sequencer';
+import type { Test } from '@jest/test-result';
+
+const createMockTest = (path: string): Test => ({
+  context: {
+    config: {
+      displayName: undefined,
+      rootDir: '/mock/root',
+    },
+    hasteFS: {},
+    moduleMap: {},
+    resolver: {},
+  },
+  duration: undefined,
+  path,
+}) as Test;
+
+describe('FilenameSortedTestSequencer', () => {
+  let sequencer: FilenameSortedTestSequencer;
+
+  beforeEach(() => {
+    sequencer = new FilenameSortedTestSequencer();
+  });
+
+  describe('sort', () => {
+    it('should sort tests by basename (filename)', () => {
+      const tests = [
+        createMockTest('/path/to/story-z.test.js'),
+        createMockTest('/different/path/story-a.test.js'),
+        createMockTest('/another/path/story-m.test.js'),
+      ];
+
+      const result = sequencer.sort(tests);
+
+      expect(result.map(test => test.path)).toEqual([
+        '/different/path/story-a.test.js',
+        '/another/path/story-m.test.js',
+        '/path/to/story-z.test.js',
+      ]);
+    });
+  });
+
+  describe('shard', () => {
+    it('should sort tests first, then divide into shards correctly', () => {
+      const tests = [
+        createMockTest('/path/f-test.js'),
+        createMockTest('/path/a-test.js'),
+        createMockTest('/path/d-test.js'),
+        createMockTest('/path/b-test.js'),
+        createMockTest('/path/e-test.js'),
+        createMockTest('/path/c-test.js'),
+      ];
+
+      const shard1 = sequencer.shard(tests, { shardIndex: 1, shardCount: 3 });
+      expect(shard1.length).toBe(2);
+      expect(shard1.map(test => test.path)).toEqual([
+        '/path/a-test.js',
+        '/path/b-test.js',
+      ]);
+
+      const shard2 = sequencer.shard(tests, { shardIndex: 2, shardCount: 3 });
+      expect(shard2.length).toBe(2);
+      expect(shard2.map(test => test.path)).toEqual([
+        '/path/c-test.js',
+        '/path/d-test.js',
+      ]);
+
+      const shard3 = sequencer.shard(tests, { shardIndex: 3, shardCount: 3 });
+      expect(shard3.length).toBe(2);
+      expect(shard3.map(test => test.path)).toEqual([
+        '/path/e-test.js',
+        '/path/f-test.js',
+      ]);
+    });
+
+    it('should handle uneven shard distribution', () => {
+      const tests = [
+        createMockTest('/path/c-test.js'),
+        createMockTest('/path/a-test.js'),
+        createMockTest('/path/b-test.js'),
+      ];
+
+      const shard1 = sequencer.shard(tests, { shardIndex: 1, shardCount: 2 });
+      expect(shard1.length).toBe(2);
+      expect(shard1.map(test => test.path)).toEqual([
+        '/path/a-test.js',
+        '/path/b-test.js',
+      ]);
+
+      const shard2 = sequencer.shard(tests, { shardIndex: 2, shardCount: 2 });
+      expect(shard2.length).toBe(1);
+      expect(shard2.map(test => test.path)).toEqual([
+        '/path/c-test.js',
+      ]);
+    });
+
+    it('should handle empty test array', () => {
+      const tests: Test[] = [];
+      const result = sequencer.shard(tests, { shardIndex: 1, shardCount: 2 });
+      expect(result).toEqual([]);
+    });
+
+    it('should handle single shard', () => {
+      const tests = [
+        createMockTest('/path/c-test.js'),
+        createMockTest('/path/a-test.js'),
+        createMockTest('/path/b-test.js'),
+      ];
+
+      const result = sequencer.shard(tests, { shardIndex: 1, shardCount: 1 });
+
+      expect(result.map(test => test.path)).toEqual([
+        '/path/a-test.js',
+        '/path/b-test.js',
+        '/path/c-test.js',
+      ]);
+    });
+  });
+});

src/config/jest-filename-sequencer.ts

@@ -0,0 +1,28 @@
+import Sequencer, { ShardOptions } from '@jest/test-sequencer';
+import type { Test } from '@jest/test-result';
+import { basename } from 'path';
+
+const sortByFilename = (tests: Array<Test>): Array<Test> => {
+  return tests.sort((a, b) => basename(a.path).localeCompare(basename(b.path)));
+};
+
+/**
+ * Custom Jest Test Sequencer that sorts tests by their filenames.
+ * This ensures consistent test execution when using sharding
+ * against an externally deployed Storybook instance using --url.
+ */
+class FilenameSortedTestSequencer extends Sequencer {
+  shard(tests: Array<Test>, { shardIndex, shardCount }: ShardOptions) {
+    const shardSize = Math.ceil(tests.length / shardCount);
+    const shardStart = shardSize * (shardIndex - 1);
+    const shardEnd = shardSize * shardIndex;
+
+    return sortByFilename(tests).slice(shardStart, shardEnd);
+  }
+
+  sort(tests: Array<Test>) {
+    return sortByFilename(tests);
+  }
+}
+
+export default FilenameSortedTestSequencer;

src/config/jest-playwright.ts

@@ -1,3 +1,4 @@
+/** @jest-config-loader-options {"transpileOnly": true} */
 import path from 'pathe';
 import { getProjectRoot } from 'storybook/internal/common';
 import type { Config } from '@jest/types';
@@ -43,6 +44,7 @@ export const getJestConfig = (): Config.InitialOptions => {
     TEST_BROWSERS,
     STORYBOOK_COLLECT_COVERAGE,
     STORYBOOK_JUNIT,
+    TEST_INDEX_JSON,
   } = process.env;
 
   const jestJunitPath = path.dirname(require.resolve('jest-junit'));
@@ -78,6 +80,7 @@ export const getJestConfig = (): Config.InitialOptions => {
         exitOnPageError: false,
       },
     },
+    testSequencer: TEST_INDEX_JSON ? require.resolve('./config/jest-filename-sequencer') : undefined,
     watchPlugins: [
       require.resolve('jest-watch-typeahead/filename'),
       require.resolve('jest-watch-typeahead/testname'),

src/test-storybook.ts

@@ -419,6 +419,7 @@ const main = async () => {
     indexTmpDir = await getIndexTempDir(targetURL);
     process.env.TEST_ROOT = indexTmpDir;
     process.env.TEST_MATCH = '**/*.test.js';
+    process.env.TEST_INDEX_JSON = 'true';
   }
 
   const { storiesPaths, lazyCompilation, disableTelemetry, enableCrashReports } =

tsup.config.ts

@@ -8,6 +8,7 @@ export default defineConfig([
     entry: [
       './src/index.ts',
       './src/test-storybook.ts',
+      './src/config/jest-filename-sequencer.ts',
       './src/jest-playwright-entries/extends.ts',
       './src/jest-playwright-entries/setup.ts',
       './src/jest-playwright-entries/teardown.ts',