feat: add replay test sharding

src/__tests__/cli-network.test.ts

@@ -213,9 +213,7 @@ test('test command --verbose prints step telemetry for passing tests without deb
 });
 
 test('test command --verbose keeps nested retry and open step telemetry distinct', async () => {
-  const tmpDir = await fs.mkdtemp(
-    path.join(os.tmpdir(), 'agent-device-cli-test-verbose-retry-'),
-  );
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-device-cli-test-verbose-retry-'));
   const artifactsDir = path.join(tmpDir, 'material-top-tabs');
   const attemptDir = path.join(artifactsDir, 'attempt-1');
   await fs.mkdir(attemptDir, { recursive: true });
@@ -497,6 +495,32 @@ test('test --maestro forwards Maestro backend and platform for directory suites'
   }
 });
 
+test('test forwards shard flags and comma device lists', async () => {
+  const result = await runCliCapture(
+    ['test', '--maestro', '--device', 'udid1,emulator-5554', '--shard-all', '2', './suite'],
+    async () => ({
+      ok: true,
+      data: {
+        total: 0,
+        executed: 0,
+        passed: 0,
+        failed: 0,
+        skipped: 0,
+        notRun: 0,
+        durationMs: 1,
+        failures: [],
+        tests: [],
+      },
+    }),
+  );
+
+  assert.equal(result.code, null);
+  assert.equal(result.calls.length, 1);
+  assert.equal(result.calls[0]?.flags?.replayBackend, 'maestro');
+  assert.equal(result.calls[0]?.flags?.device, 'udid1,emulator-5554');
+  assert.equal(result.calls[0]?.flags?.shardAll, 2);
+});
+
 test('test command writes JUnit report with failure metadata', async () => {
   const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-device-junit-test-'));
   const reportPath = path.join(tmpDir, 'replays.junit.xml');

src/cli-test.ts

@@ -317,20 +317,21 @@ function renderFlakyTestSummary(
 
 function replayTestDisplayName(result: ReplaySuiteTestResult): string {
   const title = replayTestTitle(result);
-  if (title && title.length > 0) return JSON.stringify(title);
-  return path.basename(result.file);
+  const base = title && title.length > 0 ? JSON.stringify(title) : path.basename(result.file);
+  return `${base}${formatReplayTestShardSuffix(result)}`;
 }
 
 function replayFailedTestDisplayName(
   result: Extract<ReplaySuiteTestResult, { status: 'failed' }>,
 ): string {
   const title = replayTestTitle(result);
   const filename = path.basename(result.file);
-  return title && title.length > 0 ? `${JSON.stringify(title)} in ${filename}` : filename;
+  const base = title && title.length > 0 ? `${JSON.stringify(title)} in ${filename}` : filename;
+  return `${base}${formatReplayTestShardSuffix(result)}`;
 }
 
 function replayTestCaseName(result: ReplaySuiteTestResult): string {
-  return replayTestTitle(result) ?? path.basename(result.file);
+  return `${replayTestTitle(result) ?? path.basename(result.file)}${formatReplayTestShardSuffix(result)}`;
 }
 
 function replayTestTitle(result: ReplaySuiteTestResult): string | undefined {
@@ -402,7 +403,7 @@ function buildReplayJunitXml(suite: ReplaySuiteResult): string {
 function renderJUnitTestCase(test: ReplaySuiteTestResult): string[] {
   const name = xmlEscape(replayTestCaseName(test));
   const className = xmlEscape(
-    path.dirname(test.file) === '.' ? test.file : path.dirname(test.file),
+    `${path.dirname(test.file) === '.' ? test.file : path.dirname(test.file)}${formatReplayTestShardSuffix(test)}`,
   );
   const file = xmlEscape(test.file);
   const time = formatJUnitSeconds(test.durationMs);
@@ -450,12 +451,33 @@ function appendReplaySystemOutMetadata(lines: string[], test: ReplaySuiteTestRes
     lines,
     'artifactsDir' in test && test.artifactsDir ? `artifactsDir: ${test.artifactsDir}` : undefined,
   );
+  appendReplayTestShardMetadata(lines, test);
   if (test.status === 'failed') {
     appendReplayFailureSystemOut(lines, test);
   }
   appendOptionalLine(lines, isFlakyReplayTestResult(test) ? 'flaky: true' : undefined);
 }
 
+function formatReplayTestShardSuffix(result: ReplaySuiteTestResult): string {
+  if (!('shardIndex' in result) || typeof result.shardIndex !== 'number') return '';
+  const shardCount = typeof result.shardCount === 'number' ? result.shardCount : '?';
+  const device = typeof result.deviceId === 'string' ? ` ${result.deviceId}` : '';
+  return ` [shard ${result.shardIndex + 1}/${shardCount}${device}]`;
+}
+
+function appendReplayTestShardMetadata(lines: string[], result: ReplaySuiteTestResult): void {
+  if (!('shardIndex' in result) || typeof result.shardIndex !== 'number') return;
+  lines.push(`shardIndex: ${result.shardIndex}`);
+  appendOptionalLine(
+    lines,
+    typeof result.shardCount === 'number' ? `shardCount: ${result.shardCount}` : undefined,
+  );
+  appendOptionalLine(
+    lines,
+    typeof result.deviceId === 'string' ? `deviceId: ${result.deviceId}` : undefined,
+  );
+}
+
 function appendReplayFailureSystemOut(
   lines: string[],
   test: Extract<ReplaySuiteTestResult, { status: 'failed' }>,

src/client-normalizers.ts

@@ -321,6 +321,8 @@ export function buildFlags(options: InternalRequestOptions): CommandFlags {
     retries: options.retries,
     artifactsDir: options.artifactsDir,
     reportJunit: options.reportJunit,
+    shardAll: options.shardAll,
+    shardSplit: options.shardSplit,
     findFirst: options.findFirst,
     findLast: options.findLast,
     networkInclude: options.networkInclude,

src/client-types.ts

@@ -718,6 +718,8 @@ export type ReplayTestOptions = AgentDeviceRequestOverrides &
     retries?: number;
     artifactsDir?: string;
     reportJunit?: string;
+    shardAll?: number;
+    shardSplit?: number;
   };
 
 export type BatchStep = {
@@ -855,6 +857,8 @@ type CommandExecutionOptions = Partial<ScreenshotRequestFlags> & {
   retries?: number;
   artifactsDir?: string;
   reportJunit?: string;
+  shardAll?: number;
+  shardSplit?: number;
   findFirst?: boolean;
   findLast?: boolean;
   networkInclude?: 'summary' | 'headers' | 'body' | 'all';

src/commands/cli-grammar/replay.ts

@@ -21,6 +21,8 @@ export const replayCliReaders = {
     retries: flags.retries,
     artifactsDir: flags.artifactsDir,
     reportJunit: flags.reportJunit,
+    shardAll: flags.shardAll,
+    shardSplit: flags.shardSplit,
   }),
 } satisfies Record<string, CliReader>;
 

src/commands/client-command-metadata.ts

@@ -177,6 +177,8 @@ export const clientCommandMetadata = [
     retries: integerField(),
     artifactsDir: stringField(),
     reportJunit: stringField(),
+    shardAll: integerField(),
+    shardSplit: integerField(),
   }),
   defineClientCommandMetadata('perf', {
     area: enumField(PERF_AREA_VALUES),

src/core/dispatch-context.ts

@@ -22,6 +22,8 @@ export type CommandFlags = Omit<CliFlags, DaemonExcludedCliFlag> & {
   maestro?: MaestroRuntimeFlags;
   postGestureStabilization?: boolean;
   replayBackend?: string;
+  shardCount?: number;
+  shardIndex?: number;
 };
 
 export type DispatchContext = ScreenshotDispatchFlags & {