Function runSteps

src/commands/test.ts:3528–3627

(
  opts: StepsOptions,
  deps: TestDeps = {},
)

}

export async function runSteps(
  opts: StepsOptions,
  deps: TestDeps = {},
): Promise<Page<CliTestStep>> {
  const out = makeOutput(opts.output, deps);
  const client = makeClient(opts, deps);
  const stderrFn = deps.stderr ?? ((line: string) => process.stderr.write(`${line}\n`));

  // When --run-id is supplied, use the authoritative run-scoped endpoint
  // `GET /runs/{runId}?includeSteps=true` instead of client-filtering the
  // cumulative `/tests/{id}/steps` response. The cumulative FE Portal step
  // rows don't reliably carry per-run `runIdIfAvailable`, so the old
  // client-side filter always returned empty — even for completed runs.
  if (opts.runId !== undefined) {
    // 404 → NOT_FOUND (exit 4) — unknown or cross-tenant runId.
    // All other errors propagate unchanged (auth, transport, etc.).
    const run = await client.getRun(opts.runId, { includeSteps: true });

    // Restore the implicit test-scoping the old `/tests/{testId}/steps` path
    // had: a runId belonging to a DIFFERENT test (same tenant) must not leak
    // that other test's steps under `test steps <thisTestId> --run-id <id>`.
    // Skipped under --dry-run — the canned sample's testId is fixed, not the
    // caller's argument, so a real comparison would always (falsely) mismatch.
    if (!opts.dryRun && run.testId !== opts.testId) {
      throw ApiError.fromEnvelope(
        {
          code: 'NOT_FOUND',
          message: `Run ${opts.runId} does not belong to test ${opts.testId} (it belongs to ${run.testId}). Use 'testsprite test steps ${run.testId} --run-id ${opts.runId}' or drop --run-id.`,
        },
        404,
      );
    }

    const rawSteps = run.steps ?? [];
    const items: CliTestStep[] = rawSteps.map(s => mapRunStepToCliTestStep(s, run));
    const page: Page<CliTestStep> = { items, nextToken: null };

    if (items.length === 0) {
      // The run exists but has no recorded step rows yet (e.g. a fast
      // code-replay run that finished before any steps were written).
      if (opts.output === 'json') {
        out.print(page, data => renderStepsText(data as Page<CliTestStep>));
      } else {
        stderrFn(
          `[advisory] No step records found for run ${opts.runId}. ` +
            `The run may have completed before steps were written, or this run type does not record per-step data. ` +
            `For the full failure bundle use: testsprite test artifact get ${opts.runId}`,
        );
      }
      return page;
    }

    out.print(page, data => renderStepsText(data as Page<CliTestStep>));
    return page;
  }

  // Bare `test steps <id>` (no --run-id): cumulative path — byte-identical to
  // the original behavior. Pagination flags are honored here.