fix(steps): surface run-scoped per-step error text and stepType (#167)

Author: Andy00L

src/commands/test.test.ts

@@ -2603,6 +2603,65 @@ describe('runSteps', () => {
     expect(step2.outcomeContributesToFailure).toBe(true);
   });
 
+  it('--run-id carries the per-step error text and stepType through to JSON (no silent drop)', async () => {
+    // Regression lock for the "steps discard RunStepDto.error" gap: the wire
+    // already returns the failure text in the same response; it must survive
+    // the CliTestStep mapping instead of forcing an artifact-bundle download.
+    const { credentialsPath } = makeCreds();
+    const runWithStepError = {
+      ...RUN_WITH_STEPS,
+      status: 'failed' as const,
+      failedStepIndex: 2,
+      steps: [
+        RUN_WITH_STEPS.steps[0]!,
+        {
+          ...RUN_WITH_STEPS.steps[1]!,
+          status: 'failed',
+          error: 'Expected heading "Order confirmed" to be visible, got hidden',
+        },
+      ],
+    };
+    const fetchImpl = makeFetch(() => ({ body: runWithStepError }));
+    const page = await runSteps(
+      { profile: 'default', output: 'json', debug: false, testId: 'test_fe', runId: 'run_scoped' },
+      { credentialsPath, fetchImpl, stdout: () => undefined },
+    );
+    const passing = page.items.find(s => s.stepIndex === 1)!;
+    const failing = page.items.find(s => s.stepIndex === 2)!;
+    expect(failing.error).toBe('Expected heading "Order confirmed" to be visible, got hidden');
+    expect(failing.stepType).toBe('assertion');
+    expect(passing.error).toBeNull();
+    expect(passing.stepType).toBe('action');
+  });
+
+  it('--run-id text mode prints an indented error: sub-line under the failed row only', async () => {
+    const { credentialsPath } = makeCreds();
+    const runWithStepError = {
+      ...RUN_WITH_STEPS,
+      status: 'failed' as const,
+      failedStepIndex: 2,
+      steps: [
+        RUN_WITH_STEPS.steps[0]!,
+        {
+          ...RUN_WITH_STEPS.steps[1]!,
+          status: 'failed',
+          error: 'Locator resolved to hidden element\n  at assert heading',
+        },
+      ],
+    };
+    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');
+    // Newlines in the wire error collapse to one displayable line.
+    expect(block).toContain('error: Locator resolved to hidden element at assert heading');
+    // Exactly one sub-line: the passing step must not grow one.
+    expect(block.match(/error: /g)).toHaveLength(1);
+  });
+
   it('--run-id: rejects a runId that belongs to a different test (exit 4)', async () => {
     const { credentialsPath } = makeCreds();
     // The run-scoped endpoint returns a run whose testId differs from the

src/commands/test.ts

@@ -186,6 +186,19 @@ export interface CliTestStep {
    * that don't emit the field still type-check.
    */
   outcomeContributesToFailure?: boolean | null;
+  /**
+   * Per-step failure text, carried from `RunStepDto.error` on the run-scoped
+   * endpoint (`GET /runs/{id}?includeSteps=true`). Only present on `--run-id`
+   * responses; the cumulative `/tests/{id}/steps` rows do not carry it, so the
+   * field stays optional (additive, non-breaking for existing consumers).
+   */
+  error?: string | null;
+  /**
+   * Wire step kind from `RunStepDto.type` on the run-scoped endpoint. Same
+   * availability rules as `error`. Named `stepType` to avoid colliding with
+   * the free-form `action` label above.
+   */
+  stepType?: 'action' | 'assertion';
 }
 
 /**
@@ -3642,6 +3655,12 @@ function mapRunStepToCliTestStep(step: RunStepDto, run: RunResponse): CliTestSte
     // non-contributors. (Per the CliTestStep contract: null ≠ false.)
     outcomeContributesToFailure:
       run.failedStepIndex === null ? null : numericIndex === run.failedStepIndex,
+    // Carry the per-step failure text and the wire step kind through instead
+    // of dropping them: the agent asking "why did this step fail?" would
+    // otherwise have to download the whole artifact bundle to read a string
+    // this very response already contained.
+    error: step.error,
+    stepType: step.type,
   };
 }
 
@@ -3970,6 +3989,14 @@ const RUN_HISTORY_TABLE_COL_WIDTHS = {
  */
 const DESC_COL_MAX = 60;
 
+/**
+ * Cap, in chars, for the one-line `error:` sub-line under a failed step row
+ * in `renderStepsText`. Long enough for a full assertion message, short
+ * enough that a stack-trace blob can't flood the table. Full text is in
+ * `--output json`.
+ */
+const ERROR_SUBLINE_MAX = 200;
+
 /** Max chars to show in the TARGETURL sub-line (excess truncated with …). */
 const HISTORY_TARGET_URL_MAX = 80;
 
@@ -8433,16 +8460,29 @@ 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('  ');
+    // Run-scoped rows carry the per-step failure text; surface it as an
+    // indented sub-line under failed rows (mirrors the history table's
+    // `targetUrl:` sub-line). Collapsed to one line and capped so a huge
+    // stack blob can't wreck the table; full text ships in --output json.
+    if (s.status === 'failed' && typeof s.error === 'string' && s.error.length > 0) {
+      const oneLine = s.error.replace(/\s+/g, ' ').trim();
+      const shown =
+        oneLine.length > ERROR_SUBLINE_MAX
+          ? `${oneLine.slice(0, ERROR_SUBLINE_MAX - 1)}…`
+          : oneLine;
+      return [row, `     error: ${shown}`];
+    }
+    return [row];
   });
 
   const lines: string[] = [header, ...rows, ''];