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);
});
},
}),
);