sailfork / t3code-github / .repos/ alchemy-effect/ packages/ alchemy-test/ src/ Reporter.ts

/**
 * The Reporter is an Effect service the runner emits structured events into.
 * Two implementations ship with the CLI: a plain line-oriented reporter for
 * non-interactive terminals / CI, and an opentui TUI for interactive use.
 */
import * as Context from "effect/Context";
import type * as Effect from "effect/Effect";
import type { LogEntry } from "./Model.ts";

export type TestStatus = "pass" | "fail" | "skip" | "todo";

export interface TestMeta {
  readonly tags: ReadonlyArray<string>;
  readonly optInTags: ReadonlyArray<string>;
  /** Unique test identity, stable across retries; use titlePath for display. */
  readonly id: string;
  readonly file: string;
  readonly titlePath: ReadonlyArray<string>;
  readonly name: string;
}

export interface TestResult {
  readonly status: TestStatus;
  readonly durationMs: number;
  /** Pretty-printed failure (message + relevant stack), if failed. */
  readonly error?: string | undefined;
  /** Buffered Effect log / Console output captured during the test. */
  readonly logs: ReadonlyArray<LogEntry>;
  /** Number of retries that were attempted before this result. */
  readonly retries: number;
}

export interface RunSummary {
  readonly dryRun?: boolean;
  /** Coverage within the command's path, name, .only and global tag filters. */
  readonly plan?:
    | {
        readonly found: number;
        readonly selected: number;
        readonly excluded: number;
      }
    | undefined;
  readonly files: number;
  readonly passed: number;
  readonly failed: number;
  readonly skipped: number;
  readonly todo: number;
  readonly durationMs: number;
  readonly failures: ReadonlyArray<{ meta: TestMeta; result: TestResult }>;
  /**
   * Files that failed as a whole (import error, or a `beforeAll`/`afterAll`
   * hook failure) rather than through an individual test. Counted in
   * {@link failed} alongside `failures`.
   */
  readonly fileFailures: ReadonlyArray<{ file: string; error: string }>;
}

export type TestEvent =
  | {
      readonly _tag: "PlanPreview";
      readonly phases: ReadonlyArray<
        ReadonlyArray<{
          readonly tags: ReadonlyArray<string>;
          readonly concurrency: number | "unbounded";
          readonly tests: number;
          readonly files: number;
          readonly skipped: number;
        }>
      >;
    }
  | {
      readonly _tag: "PlanPhaseStart";
      readonly phase: number;
      readonly phases: number;
      readonly tests: number;
    }
  | { readonly _tag: "CollectStart"; readonly files: ReadonlyArray<string> }
  | {
      /** Import progress: one per file during the collection phase. */
      readonly _tag: "FileCollected";
      readonly file: string;
    }
  | {
      /**
       * Collection is complete; execution is about to begin. Carries the
       * full (filtered) test list for the whole run.
       */
      readonly _tag: "RunStart";
      readonly files: number;
      readonly tests: ReadonlyArray<TestMeta>;
    }
  | {
      readonly _tag: "FileStart";
      readonly file: string;
      /**
       * LIVE reference to the file's hook log buffer (deploy/destroy). The
       * runner appends to it as hooks execute — single-process, so reporters
       * may read it incrementally (e.g. the TUI tailing a detail pane).
       */
      readonly logs?: ReadonlyArray<LogEntry>;
    }
  | {
      /** A file-level hook (deploy/destroy) started running. */
      readonly _tag: "HookStart";
      readonly file: string;
      readonly hook: "beforeAll" | "afterAll";
    }
  | {
      readonly _tag: "HookEnd";
      readonly file: string;
      readonly hook: "beforeAll" | "afterAll";
    }
  | {
      readonly _tag: "FileEnd";
      readonly file: string;
      /** Buffered output of file-level hooks (deploy/destroy). */
      readonly logs: ReadonlyArray<LogEntry>;
      readonly error?: string | undefined;
    }
  | {
      readonly _tag: "TestStart";
      readonly test: TestMeta;
      /** LIVE reference to the test's captured-output buffer (see FileStart). */
      readonly logs?: ReadonlyArray<LogEntry>;
    }
  | {
      /**
       * The test holds its run lock (`exclusive`) and starts executing. Until
       * then it is queued: an exclusive test can wait out a busy phase.
       */
      readonly _tag: "TestLocked";
      readonly test: TestMeta;
    }
  | {
      readonly _tag: "TestEnd";
      readonly test: TestMeta;
      readonly result: TestResult;
    }
  | { readonly _tag: "RunEnd"; readonly summary: RunSummary };

/**
 * Interactive control over a live (or finished) run. The runner hands this
 * to the Reporter so the TUI can retry and kill tests.
 *
 * Retries re-run the test body as-is: for files whose state was torn down by
 * `afterAll` (deploy-once suites) the retried body may fail on missing
 * infrastructure — `test.provider`-style self-contained tests retry cleanly.
 */
export interface RunController {
  /** Re-run a finished test. No-op while the test is still running/queued. */
  readonly retryTest: (id: string) => void;
  /** Re-run every finished test of a file. */
  readonly retryFile: (file: string) => void;
  /** Interrupt a currently-running test (reported as failed/killed). */
  readonly killTest: (id: string) => void;
}

export interface ReporterService {
  readonly emit: (event: TestEvent) => Effect.Effect<void>;
  /**
   * Runs after RunEnd. The plain reporter returns immediately; the TUI blocks
   * until the user quits so results can be inspected.
   */
  readonly waitForExit: (summary: RunSummary) => Effect.Effect<void>;
  /** Called once by the runner when interactive control becomes available. */
  readonly attachController?: (controller: RunController) => Effect.Effect<void>;
}

export class Reporter extends Context.Service<Reporter, ReporterService>()(
  "alchemy-test/Reporter",
) {}