@alchemy.run/test 0.0.0 → 2.0.0-beta.85

package/src/Reporter.ts

@@ -0,0 +1,171 @@
+/**
+ * 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",
+) {}