fix(steps): surface run-scoped step errors

Author: JerryNee

src/commands/test.test.ts

@@ -2522,11 +2522,81 @@ describe('runSteps', () => {
     // timestamps come from RunStepDto.createdAt
     expect(first.capturedAt).toBe('2026-06-01T10:00:05.000Z');
     expect(first.updatedAt).toBe('2026-06-01T10:00:05.000Z');
+    expect(first.stepType).toBe('action');
+    expect(first.error).toBeNull();
     // outcomeContributesToFailure: null when run passed (failedStepIndex is null)
     expect(first.outcomeContributesToFailure).toBeNull();
     // JSON output should be parseable with 2 items
-    const printed = JSON.parse(out[0]!) as { items: unknown[] };
+    const printed = JSON.parse(out[0]!) as {
+      items: Array<{ stepType?: string; error?: string | null }>;
+    };
     expect(printed.items).toHaveLength(2);
+    expect(printed.items[0]!.stepType).toBe('action');
+    expect(printed.items[0]!.error).toBeNull();
+  });
+
+  it('--run-id preserves per-step error text in JSON output', async () => {
+    const { credentialsPath } = makeCreds();
+    const runWithStepError = {
+      ...RUN_WITH_STEPS,
+      status: 'failed' as const,
+      failedStepIndex: 2,
+      stepSummary: { total: 2, completed: 2, passedCount: 1, failedCount: 1 },
+      steps: RUN_WITH_STEPS.steps.map(step =>
+        step.stepIndex === '0002'
+          ? {
+              ...step,
+              status: 'failed' as const,
+              error: 'AssertionError: expected heading to be visible',
+            }
+          : step,
+      ),
+    };
+    const fetchImpl = makeFetch(() => ({ body: runWithStepError }));
+    const out: string[] = [];
+
+    await runSteps(
+      { profile: 'default', output: 'json', debug: false, testId: 'test_fe', runId: 'run_scoped' },
+      { credentialsPath, fetchImpl, stdout: line => out.push(line) },
+    );
+
+    const printed = JSON.parse(out[0]!) as {
+      items: Array<{ stepIndex: number; stepType?: string; error?: string | null }>;
+    };
+    const failedStep = printed.items.find(step => step.stepIndex === 2)!;
+    expect(failedStep.stepType).toBe('assertion');
+    expect(failedStep.error).toBe('AssertionError: expected heading to be visible');
+  });
+
+  it('--run-id prints per-step error text under failed rows in text mode', async () => {
+    const { credentialsPath } = makeCreds();
+    const runWithStepError = {
+      ...RUN_WITH_STEPS,
+      status: 'failed' as const,
+      failedStepIndex: 2,
+      stepSummary: { total: 2, completed: 2, passedCount: 1, failedCount: 1 },
+      steps: RUN_WITH_STEPS.steps.map(step =>
+        step.stepIndex === '0002'
+          ? {
+              ...step,
+              status: 'failed' as const,
+              error: 'AssertionError: expected heading to be visible',
+            }
+          : step,
+      ),
+    };
+    const fetchImpl = makeFetch(() => ({ body: runWithStepError }));
+    const out: string[] = [];
+
+    await runSteps(
+      { profile: 'default', output: 'text', debug: false, testId: 'test_fe', runId: 'run_scoped' },
+      { credentialsPath, fetchImpl, stdout: line => out.push(line) },
+    );
+
+    const block = out.join('\n');
+    expect(block).toContain('assert heading');
+    expect(block).toContain('failed');
+    expect(block).toContain('  error: AssertionError: expected heading to be visible');
   });
 
   it('--run-id: outcomeContributesToFailure=true on the failedStepIndex step', async () => {

src/commands/test.ts

@@ -159,9 +159,16 @@ export interface CliTestCode {
 export interface CliTestStep {
   testId: string;
   stepIndex: number;
+  /**
+   * Run-scoped steps expose the backend's original plan-step type. Optional so
+   * the cumulative /tests/{id}/steps response remains backward-compatible.
+   */
+  stepType?: 'action' | 'assertion';
   action: string;
   description: string;
   status: 'passed' | 'failed' | null;
+  /** Per-step failure text already returned by GET /runs/{id}?includeSteps=true. */
+  error?: string | null;
   screenshotUrl: string | null;
   htmlSnapshotUrl: string | null;
   runIdIfAvailable: string | null;
@@ -3612,9 +3619,11 @@ function mapRunStepToCliTestStep(step: RunStepDto, run: RunResponse): CliTestSte
   return {
     testId: run.testId,
     stepIndex: numericIndex,
+    stepType: step.type,
     action: step.action,
     description: step.description ?? '',
     status: step.status,
+    error: step.error,
     screenshotUrl: step.screenshotUrl,
     htmlSnapshotUrl: step.htmlSnapshotUrl,
     runIdIfAvailable: run.runId,
@@ -8232,16 +8241,18 @@ function renderStepsText(page: Page<CliTestStep>): string {
     '  ' +
     'UPDATED';
 
-  const rows = page.items.map(s => {
+  const rows = page.items.flatMap(s => {
     const marker = s.outcomeContributesToFailure === true ? '* ' : '  ';
-    return [
+    const row = [
       marker,
       pad(String(s.stepIndex), indexWidth),
       pad(s.action, actionWidth),
       pad(s.status ?? '—', statusWidth),
       pad(descOf(s), descWidth),
       s.updatedAt,
     ].join('  ');
+    const error = s.error?.trim();
+    return error ? [row, `  error: ${error}`] : [row];
   });
 
   const lines: string[] = [header, ...rows, ''];