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

/**
 * Core data model for the alchemy-test harness.
 *
 * A test file is collected into a tree of {@link Suite}s and {@link TestCase}s
 * by evaluating its module body (describe/test calls register nodes). The
 * runner then walks the tree and executes every test as an Effect.
 */
import type * as Effect from "effect/Effect";
import { mergeTags, type Tags } from "./Tags.ts";

/** Execution mode attached to a suite or test at registration time. */
export type Mode = "run" | "skip" | "only" | "todo";

/** A single log line captured from a test's Effect Logger or Console. */
export interface LogEntry {
  readonly level: string;
  readonly message: string;
  readonly time: Date;
}

/**
 * The body of a test. Always an Effect — plain-function tests are wrapped
 * at registration time. The Effect must be self-contained (R = never);
 * wrapping (scope, TestClock/TestConsole, shared layers) happens in the
 * harness closures, NOT in the runner.
 */
export type TestBody = () => Effect.Effect<unknown, unknown, never>;

/** A hook body. Same contract as {@link TestBody}. */
export type HookBody = () => Effect.Effect<unknown, unknown, never>;

/** `true` for the whole-process lock, or a label naming a narrower lock. */
export type Exclusive = boolean | string;

export interface Hook {
  readonly body: HookBody;
  readonly timeout?: number | undefined;
  /**
   * `true` takes the whole-process write lock for this hook. A label (e.g.
   * `"hetzner"`) only serializes the hook with tests and hooks holding the
   * same label — use it for deploys that consume a scarce cloud quota.
   */
  readonly exclusive?: Exclusive;
}

export interface TestCase {
  /** Deduplicated labels, including tags inherited from suites. */
  readonly tags: ReadonlyArray<string>;
  /** Inherited tags requiring explicit selection. */
  readonly optInTags: ReadonlyArray<string>;
  readonly type: "test";
  readonly name: string;
  readonly mode: Mode;
  /** Invert the result: the test passes only if the body fails. */
  readonly fails?: boolean;
  /**
   * `true` runs this test with the whole-process write lock: no other test
   * in the run executes concurrently with it. Required for tests that mutate
   * process-global state (e.g. `process.env.PATH`) — the runner executes
   * everything in ONE bun process, so such mutations are visible everywhere.
   *
   * A label (e.g. `"hetzner"`) only serializes the test with others holding
   * the same label — use it for a shared cloud quota, not global state.
   */
  readonly exclusive?: Exclusive;
  /** Override the run-wide retry budget for this test. */
  readonly retry?: number | undefined;
  readonly timeout?: number | undefined;
  readonly body: TestBody | undefined;
  readonly parent: Suite;
}

export interface Suite {
  /** Deduplicated labels, including tags inherited from parent suites. */
  readonly tags: ReadonlyArray<string>;
  /** Inherited tags requiring explicit selection. */
  readonly optInTags: ReadonlyArray<string>;
  readonly type: "suite";
  readonly name: string;
  mode: Mode;
  /** When true, children run one at a time (the default; describe.concurrent opts out). */
  sequential: boolean;
  readonly children: Array<Suite | TestCase>;
  readonly beforeAll: Array<Hook>;
  readonly afterAll: Array<Hook>;
  readonly beforeEach: Array<Hook>;
  readonly afterEach: Array<Hook>;
  readonly parent: Suite | undefined;
}

/** The root suite of a single test file. */
export interface FileSuite extends Suite {
  /** Path relative to the run root, e.g. `test/Cloudflare/R2/Bucket.test.ts`. */
  readonly file: string;
  /** Framework resources, disposed even when user hooks are skipped. */
  readonly cleanups: Array<Hook>;
}

export const makeSuite = (
  name: string,
  parent: Suite | undefined,
  mode: Mode = "run",
  tags?: Tags,
  optInTags?: Tags,
): Suite => ({
  tags: mergeTags(parent?.tags ?? [], tags),
  optInTags: mergeTags(parent?.optInTags ?? [], optInTags),
  type: "suite",
  name,
  mode,
  sequential: true,
  children: [],
  beforeAll: [],
  afterAll: [],
  beforeEach: [],
  afterEach: [],
  parent,
});

export const makeFileSuite = (file: string): FileSuite => ({
  ...makeSuite(file, undefined),
  file,
  cleanups: [],
});

/** Full title path from the file root down to (and including) this node. */
export const titlePath = (node: Suite | TestCase): ReadonlyArray<string> => {
  const parts: Array<string> = [];
  let current: Suite | TestCase | undefined = node;
  while (current !== undefined) {
    // Skip the file-root suite name (it's reported separately as `file`).
    if (current.parent !== undefined || current.type === "test") {
      parts.unshift(current.name);
    } else if (current.parent === undefined && current.type === "suite") {
      // file root — stop
    }
    current = current.parent;
  }
  return parts;
};

export const fullTitle = (node: Suite | TestCase): string => titlePath(node).join(" > ");

/** Walk every test in a suite subtree (depth-first, registration order). */
export const forEachTest = (suite: Suite, f: (test: TestCase) => void): void => {
  for (const child of suite.children) {
    if (child.type === "test") f(child);
    else forEachTest(child, f);
  }
};

/** True if the subtree contains a node marked `only`. */
export const containsOnly = (suite: Suite): boolean => {
  if (suite.mode === "only") return true;
  for (const child of suite.children) {
    if (child.type === "test" && child.mode === "only") return true;
    if (child.type === "suite" && containsOnly(child)) return true;
  }
  return false;
};