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

/**
 * The `alchemy-test` CLI.
 *
 * ```sh
 * alchemy-test [paths...] [-t pattern] [--exclude path]... [--timeout ms]
 *              [--retry n] [--concurrency n] [--sequential] [--tui]
 *              [--profile name] [--stage name] [--fast]
 *              [--tags 'unit || (e2e && !live)']
 * ```
 *
 * Runs every `*.test.ts` under the given paths (default `./test`) in a single
 * bun process. Interactive terminals get the opentui view; otherwise tests
 * are logged line-by-line and failures are dumped at the end.
 */
// The runner executes every test file's effects on ONE event loop, so any
// fiber touching a relative path can race a transient process-wide chdir.
// cross-spawn (bundled in vite/build tools the tests exercise) chdirs the
// whole process to resolve a spawn's binary; `process.chdir.disabled` is
// its own escape hatch (built for worker threads) — with it set, commands
// still resolve via PATH and absolutize against the spawn's `cwd`.
(process.chdir as { disabled?: boolean }).disabled = true;

import * as BunRuntime from "@effect/platform-bun/BunRuntime";
import * as BunServices from "@effect/platform-bun/BunServices";
import * as Argument from "effect/cli/Argument";
import * as Command from "effect/cli/Command";
import * as Flag from "effect/cli/Flag";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Path from "effect/Path";
import * as Runtime from "effect/Runtime";
import * as Schema from "effect/Schema";
import packageJson from "../package.json" with { type: "json" };
import { PlainReporterLive, printSummary } from "./PlainReporter.ts";
import { parsePlan } from "./Plan.ts";
import { Reporter } from "./Reporter.ts";
import { run, type RunOptions } from "./Runner.ts";
import { captureStrayOutput } from "./StrayOutput.ts";
import { worktreeStage } from "./WorktreeStage.ts";

const paths = Argument.String("paths").pipe(
  Argument.withDescription("Test files or directories (default: ./test)"),
  Argument.variadic(),
);

const testNamePattern = Flag.String("test-name-pattern").pipe(
  Flag.withAlias("t"),
  Flag.withDescription("Only run tests whose title matches this regex"),
  Flag.optional,
);

const exclude = Flag.String("exclude").pipe(
  Flag.withDescription(
    "Skip test files under this path (repeatable). Existing files/directories exclude by prefix; anything else is a case-insensitive substring filter. Explicitly passing an excluded path as a positional argument overrides the exclusion.",
  ),
  Flag.atLeast(0),
);

const tagsFilter = Flag.String("tags").pipe(
  Flag.withDescription(
    'Select tags using &&, ||, !, parentheses and * wildcards (e.g. "e2e && provider:aws && !slow"). Repeated filters are ANDed.',
  ),
  Flag.atLeast(0),
);

const plan = Flag.String("plan").pipe(
  Flag.withDescription(
    "JSON array of sequential phases; nested arrays run branches in parallel. Each branch has tags (ANDed expressions) and optional file concurrency. First match wins; shared hooks live until the file's final phase.",
  ),
  Flag.optional,
);

const dryRun = Flag.Boolean("dry-run").pipe(
  Flag.withDescription("Collect tests and show the execution plan without running tests or hooks"),
  Flag.withDefault(false),
);

const timeout = Flag.Int("timeout").pipe(
  Flag.withDescription("Default per-test timeout in milliseconds"),
  Flag.withDefault(120_000),
);

const retry = Flag.Int("retry").pipe(
  Flag.withDescription("Times a failing test is retried before failing the run"),
  Flag.withDefault(2),
);

const concurrency = Flag.String("concurrency").pipe(
  Flag.withAlias("c"),
  Flag.withDescription(
    'Maximum number of files running concurrently: a number (default 32) or "unbounded". Unbounded runs of large suites saturate the event loop and drown real failures in spurious 0ms beforeAll timeouts.',
  ),
  Flag.withDefault("32"),
);

const toConcurrency = (value: string): number | "unbounded" => {
  if (value === "unbounded") return "unbounded";
  const parsed = Number.parseInt(value, 10);
  if (!Number.isFinite(parsed) || parsed < 1) {
    throw new Error(`--concurrency must be a positive integer or "unbounded", got: ${value}`);
  }
  return parsed;
};

/** `--tui` was requested but the optional `@opentui/core` peer isn't installed. */
class TuiUnavailable extends Data.TaggedError("TuiUnavailable")<{
  readonly message: string;
  readonly cause: unknown;
}> {}

// The TUI's renderer (`@opentui/core`) is an optional peer, so it loads only
// when `--tui` asks for it.
const tuiReporter = (logFile: string) =>
  Layer.unwrap(
    Effect.tryPromise({
      try: () => import("./Tui.ts"),
      catch: (cause) =>
        new TuiUnavailable({
          message: "--tui needs @opentui/core. Install it with `bun add -d @opentui/core`.",
          cause,
        }),
    }).pipe(Effect.map(({ TuiReporter }) => TuiReporter(logFile))),
  );

const sequential = Flag.Boolean("sequential").pipe(
  Flag.withDescription("Run tests within each file sequentially"),
  Flag.withDefault(false),
);

const tui = Flag.Boolean("tui").pipe(
  Flag.withDescription("Opt in to the interactive TUI (default is plain line output)"),
  Flag.withDefault(false),
);

const profile = Flag.String("profile").pipe(
  Flag.withDescription(
    'Set ALCHEMY_PROFILE for the run (e.g. "testing") before any test module is imported',
  ),
  Flag.optional,
);

const stage = Flag.String("stage").pipe(
  Flag.withSchema(Schema.String.check(Schema.isPattern(/^[a-z0-9]+([-_a-z0-9]+)*$/i))),
  Flag.withDescription(
    'Set ALCHEMY_TEST_STAGE for the run (e.g. "test_sam_feat-x") before any test module is imported',
  ),
  Flag.optional,
);

const fast = Flag.Boolean("fast").pipe(
  Flag.withDescription(
    "Set FAST=1 — suites skip their slow tests (long-provisioning resources, smoke tests)",
  ),
  Flag.withDefault(false),
);

/**
 * Build the `-t` matcher — bun/vitest semantics: the pattern is a regex
 * tested against the full nested title (`file > describe chain > name`).
 * A syntactically INVALID regex (e.g. `-t "[worker"`) degrades to a literal
 * substring match instead of erroring.
 */
const toFilter = (pattern: Option.Option<string>): ((fullTitle: string) => boolean) | undefined =>
  Option.match(pattern, {
    onNone: () => undefined,
    onSome: (source) => {
      let regex: RegExp;
      try {
        regex = new RegExp(source);
      } catch {
        // Not a valid regex — treat it as a literal substring.
        regex = new RegExp(source.replace(/[.*+?^${}()|[\]\\]/g, "\\

Loading Sailfork

amp;")); } return (fullTitle) => regex.test(fullTitle); }, }); const rootCommand = Command.make( "alchemy-test", { paths, testNamePattern, tagsFilter, plan, dryRun, exclude, timeout, retry, concurrency, sequential, tui, profile, stage, fast, }, Effect.fn(function* (args) { // Environment knobs — set BEFORE any test module is imported (imports // happen inside `run` during collection), so `skipIf(process.env.FAST)` // gates and profile-dependent layers see the final values. // Inherit CI from the caller: setting it here also disables local auth // profiles, even when the caller explicitly selected one. yield* Effect.sync(() => { if (Option.isSome(args.profile)) { process.env.ALCHEMY_PROFILE = args.profile.value; } if (Option.isSome(args.stage)) { process.env.ALCHEMY_TEST_STAGE = args.stage.value; } if (args.fast) { process.env.FAST = "1"; } // The runner owns the terminal: stdout belongs to the reporter (or // the TUI) and stdin carries TUI keystrokes. Code under test must see // the same non-interactive, colorless process CI gives it, regardless // of the terminal this run was launched from — otherwise assertions // on CLI output and on interactive-vs-plain copy depend on whether a // human or a pipeline started the run. Sigil's detection honors // FORCE_COLOR over everything else, so pin it rather than NO_COLOR. process.env.ALCHEMY_NO_TUI = "1"; process.env.NO_COLOR = "1"; process.env.FORCE_COLOR = "0"; }); // A linked git worktree defaults to its own stage, so two worktrees of // one developer running the same suite never share deployments. An // explicit `--stage` or ALCHEMY_TEST_STAGE wins. if (Option.isNone(args.stage) && !process.env.ALCHEMY_TEST_STAGE) { const stage = yield* worktreeStage(yield* Effect.sync(() => process.cwd())); if (stage !== undefined) { yield* Effect.sync(() => { process.env.ALCHEMY_TEST_STAGE = stage; }); } } // Plain line output by default; the TUI is opt-in (`--tui`) and requires // an interactive terminal. const interactive = !args.dryRun && args.tui && process.stdout.isTTY === true; const path = yield* Path.Path; const root = process.cwd(); // Per-run log file (timestamp + pid) so concurrent runs in different // terminals never trample each other's logs. const timestamp = new Date().toISOString().slice(0, 19).replaceAll(":", "-"); const logFile = path.resolve( root, ".alchemy", "log", "test", `${timestamp}-pid${process.pid}.log`, ); const options: RunOptions = { root, paths: args.paths, exclude: args.exclude, filter: toFilter(args.testNamePattern), tagsFilter: args.tagsFilter, dryRun: args.dryRun, plan: Option.isSome(args.plan) ? parsePlan(args.plan.value) : undefined, timeout: args.timeout, retry: args.retry, concurrency: toConcurrency(args.concurrency), sequential: args.sequential, logFile, }; // In plain mode, divert stray JS-level stdout/stderr writes into the // run log for the duration of the run (the reporter writes through the // real stream); the TUI installs its own diversion after the renderer // is created. const restoreStrayCapture = interactive ? undefined : captureStrayOutput(logFile); const summary = yield* Effect.gen(function* () { const reporter = yield* Reporter; const summary = yield* run(options); yield* reporter.waitForExit(summary); return summary; }).pipe( Effect.provide(interactive ? tuiReporter(logFile) : PlainReporterLive), Effect.scoped, Effect.onExit(() => Effect.sync(() => restoreStrayCapture?.())), ); // After the TUI tears down, leave a plain record in the terminal. if (interactive) { yield* printSummary(summary); } // Point agents/tooling at the full run log, with its size so the reader // knows what they're getting into before opening it. yield* Effect.gen(function* () { const fs = yield* FileSystem.FileSystem; const stats = yield* fs.stat(logFile).pipe(Effect.orElseSucceed(() => undefined)); const kb = stats === undefined ? 0 : Number(stats.size) / 1024; yield* Effect.sync(() => { process.stdout.write(`\nFull log: ${logFile} (${kb.toFixed(1)} KB)\n`); }); }); if (summary.failed > 0) { yield* Effect.sync(() => { process.exitCode = 1; }); } }), ); const cli = Command.run(rootCommand, { version: packageJson.version, }); cli.pipe(Effect.provide(Layer.mergeAll(BunServices.layer)), Effect.scoped, (effect) => BunRuntime.runMain(effect as Effect.Effect<void>, { // ALWAYS exit once the main effect completes. runMain's default only // force-exits on failure/signal — but tests can leak live handles // (vite watchers, workerd sidecar sockets, keep-alive agents) that // keep bun's event loop alive forever after a green run. Everything // is already flushed by now (summary + log written in the main // effect); the macrotask hop lets any buffered stdout drain. teardown: (exit, onExit) => { Runtime.defaultTeardown(exit, (code) => { const finalCode = code !== 0 ? code : Number(process.exitCode ?? 0) || 0; setTimeout(() => process.exit(finalCode), 0); onExit(finalCode); }); }, }), );