@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 330 lines 12 KB
Raw
1 /**
2 * The `alchemy-test` CLI.
3 *
4 * ```sh
5 * alchemy-test [paths...] [-t pattern] [--exclude path]... [--timeout ms]
6 * [--retry n] [--concurrency n] [--sequential] [--tui]
7 * [--profile name] [--stage name] [--fast]
8 * [--tags 'unit || (e2e && !live)']
9 * ```
10 *
11 * Runs every `*.test.ts` under the given paths (default `./test`) in a single
12 * bun process. Interactive terminals get the opentui view; otherwise tests
13 * are logged line-by-line and failures are dumped at the end.
14 */
15 // The runner executes every test file's effects on ONE event loop, so any
16 // fiber touching a relative path can race a transient process-wide chdir.
17 // cross-spawn (bundled in vite/build tools the tests exercise) chdirs the
18 // whole process to resolve a spawn's binary; `process.chdir.disabled` is
19 // its own escape hatch (built for worker threads) — with it set, commands
20 // still resolve via PATH and absolutize against the spawn's `cwd`.
21 (process.chdir as { disabled?: boolean }).disabled = true;
22
23 import * as BunRuntime from "@effect/platform-bun/BunRuntime";
24 import * as BunServices from "@effect/platform-bun/BunServices";
25 import * as Argument from "effect/cli/Argument";
26 import * as Command from "effect/cli/Command";
27 import * as Flag from "effect/cli/Flag";
28 import * as Data from "effect/Data";
29 import * as Effect from "effect/Effect";
30 import * as FileSystem from "effect/FileSystem";
31 import * as Layer from "effect/Layer";
32 import * as Option from "effect/Option";
33 import * as Path from "effect/Path";
34 import * as Runtime from "effect/Runtime";
35 import * as Schema from "effect/Schema";
36 import packageJson from "../package.json" with { type: "json" };
37 import { PlainReporterLive, printSummary } from "./PlainReporter.ts";
38 import { parsePlan } from "./Plan.ts";
39 import { Reporter } from "./Reporter.ts";
40 import { run, type RunOptions } from "./Runner.ts";
41 import { captureStrayOutput } from "./StrayOutput.ts";
42 import { worktreeStage } from "./WorktreeStage.ts";
43
44 const paths = Argument.String("paths").pipe(
45 Argument.withDescription("Test files or directories (default: ./test)"),
46 Argument.variadic(),
47 );
48
49 const testNamePattern = Flag.String("test-name-pattern").pipe(
50 Flag.withAlias("t"),
51 Flag.withDescription("Only run tests whose title matches this regex"),
52 Flag.optional,
53 );
54
55 const exclude = Flag.String("exclude").pipe(
56 Flag.withDescription(
57 "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.",
58 ),
59 Flag.atLeast(0),
60 );
61
62 const tagsFilter = Flag.String("tags").pipe(
63 Flag.withDescription(
64 'Select tags using &&, ||, !, parentheses and * wildcards (e.g. "e2e && provider:aws && !slow"). Repeated filters are ANDed.',
65 ),
66 Flag.atLeast(0),
67 );
68
69 const plan = Flag.String("plan").pipe(
70 Flag.withDescription(
71 "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.",
72 ),
73 Flag.optional,
74 );
75
76 const dryRun = Flag.Boolean("dry-run").pipe(
77 Flag.withDescription("Collect tests and show the execution plan without running tests or hooks"),
78 Flag.withDefault(false),
79 );
80
81 const timeout = Flag.Int("timeout").pipe(
82 Flag.withDescription("Default per-test timeout in milliseconds"),
83 Flag.withDefault(120_000),
84 );
85
86 const retry = Flag.Int("retry").pipe(
87 Flag.withDescription("Times a failing test is retried before failing the run"),
88 Flag.withDefault(2),
89 );
90
91 const concurrency = Flag.String("concurrency").pipe(
92 Flag.withAlias("c"),
93 Flag.withDescription(
94 '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.',
95 ),
96 Flag.withDefault("32"),
97 );
98
99 const toConcurrency = (value: string): number | "unbounded" => {
100 if (value === "unbounded") return "unbounded";
101 const parsed = Number.parseInt(value, 10);
102 if (!Number.isFinite(parsed) || parsed < 1) {
103 throw new Error(`--concurrency must be a positive integer or "unbounded", got: ${value}`);
104 }
105 return parsed;
106 };
107
108 /** `--tui` was requested but the optional `@opentui/core` peer isn't installed. */
109 class TuiUnavailable extends Data.TaggedError("TuiUnavailable")<{
110 readonly message: string;
111 readonly cause: unknown;
112 }> {}
113
114 // The TUI's renderer (`@opentui/core`) is an optional peer, so it loads only
115 // when `--tui` asks for it.
116 const tuiReporter = (logFile: string) =>
117 Layer.unwrap(
118 Effect.tryPromise({
119 try: () => import("./Tui.ts"),
120 catch: (cause) =>
121 new TuiUnavailable({
122 message: "--tui needs @opentui/core. Install it with `bun add -d @opentui/core`.",
123 cause,
124 }),
125 }).pipe(Effect.map(({ TuiReporter }) => TuiReporter(logFile))),
126 );
127
128 const sequential = Flag.Boolean("sequential").pipe(
129 Flag.withDescription("Run tests within each file sequentially"),
130 Flag.withDefault(false),
131 );
132
133 const tui = Flag.Boolean("tui").pipe(
134 Flag.withDescription("Opt in to the interactive TUI (default is plain line output)"),
135 Flag.withDefault(false),
136 );
137
138 const profile = Flag.String("profile").pipe(
139 Flag.withDescription(
140 'Set ALCHEMY_PROFILE for the run (e.g. "testing") before any test module is imported',
141 ),
142 Flag.optional,
143 );
144
145 const stage = Flag.String("stage").pipe(
146 Flag.withSchema(Schema.String.check(Schema.isPattern(/^[a-z0-9]+([-_a-z0-9]+)*$/i))),
147 Flag.withDescription(
148 'Set ALCHEMY_TEST_STAGE for the run (e.g. "test_sam_feat-x") before any test module is imported',
149 ),
150 Flag.optional,
151 );
152
153 const fast = Flag.Boolean("fast").pipe(
154 Flag.withDescription(
155 "Set FAST=1 — suites skip their slow tests (long-provisioning resources, smoke tests)",
156 ),
157 Flag.withDefault(false),
158 );
159
160 /**
161 * Build the `-t` matcher — bun/vitest semantics: the pattern is a regex
162 * tested against the full nested title (`file > describe chain > name`).
163 * A syntactically INVALID regex (e.g. `-t "[worker"`) degrades to a literal
164 * substring match instead of erroring.
165 */
166 const toFilter = (pattern: Option.Option<string>): ((fullTitle: string) => boolean) | undefined =>
167 Option.match(pattern, {
168 onNone: () => undefined,
169 onSome: (source) => {
170 let regex: RegExp;
171 try {
172 regex = new RegExp(source);
173 } catch {
174 // Not a valid regex — treat it as a literal substring.
175 regex = new RegExp(source.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
176 }
177 return (fullTitle) => regex.test(fullTitle);
178 },
179 });
180
181 const rootCommand = Command.make(
182 "alchemy-test",
183 {
184 paths,
185 testNamePattern,
186 tagsFilter,
187 plan,
188 dryRun,
189 exclude,
190 timeout,
191 retry,
192 concurrency,
193 sequential,
194 tui,
195 profile,
196 stage,
197 fast,
198 },
199 Effect.fn(function* (args) {
200 // Environment knobs — set BEFORE any test module is imported (imports
201 // happen inside `run` during collection), so `skipIf(process.env.FAST)`
202 // gates and profile-dependent layers see the final values.
203 // Inherit CI from the caller: setting it here also disables local auth
204 // profiles, even when the caller explicitly selected one.
205 yield* Effect.sync(() => {
206 if (Option.isSome(args.profile)) {
207 process.env.ALCHEMY_PROFILE = args.profile.value;
208 }
209 if (Option.isSome(args.stage)) {
210 process.env.ALCHEMY_TEST_STAGE = args.stage.value;
211 }
212 if (args.fast) {
213 process.env.FAST = "1";
214 }
215 // The runner owns the terminal: stdout belongs to the reporter (or
216 // the TUI) and stdin carries TUI keystrokes. Code under test must see
217 // the same non-interactive, colorless process CI gives it, regardless
218 // of the terminal this run was launched from — otherwise assertions
219 // on CLI output and on interactive-vs-plain copy depend on whether a
220 // human or a pipeline started the run. Sigil's detection honors
221 // FORCE_COLOR over everything else, so pin it rather than NO_COLOR.
222 process.env.ALCHEMY_NO_TUI = "1";
223 process.env.NO_COLOR = "1";
224 process.env.FORCE_COLOR = "0";
225 });
226 // A linked git worktree defaults to its own stage, so two worktrees of
227 // one developer running the same suite never share deployments. An
228 // explicit `--stage` or ALCHEMY_TEST_STAGE wins.
229 if (Option.isNone(args.stage) && !process.env.ALCHEMY_TEST_STAGE) {
230 const stage = yield* worktreeStage(yield* Effect.sync(() => process.cwd()));
231 if (stage !== undefined) {
232 yield* Effect.sync(() => {
233 process.env.ALCHEMY_TEST_STAGE = stage;
234 });
235 }
236 }
237
238 // Plain line output by default; the TUI is opt-in (`--tui`) and requires
239 // an interactive terminal.
240 const interactive = !args.dryRun && args.tui && process.stdout.isTTY === true;
241 const path = yield* Path.Path;
242 const root = process.cwd();
243 // Per-run log file (timestamp + pid) so concurrent runs in different
244 // terminals never trample each other's logs.
245 const timestamp = new Date().toISOString().slice(0, 19).replaceAll(":", "-");
246 const logFile = path.resolve(
247 root,
248 ".alchemy",
249 "log",
250 "test",
251 `${timestamp}-pid${process.pid}.log`,
252 );
253
254 const options: RunOptions = {
255 root,
256 paths: args.paths,
257 exclude: args.exclude,
258 filter: toFilter(args.testNamePattern),
259 tagsFilter: args.tagsFilter,
260 dryRun: args.dryRun,
261 plan: Option.isSome(args.plan) ? parsePlan(args.plan.value) : undefined,
262 timeout: args.timeout,
263 retry: args.retry,
264 concurrency: toConcurrency(args.concurrency),
265 sequential: args.sequential,
266 logFile,
267 };
268
269 // In plain mode, divert stray JS-level stdout/stderr writes into the
270 // run log for the duration of the run (the reporter writes through the
271 // real stream); the TUI installs its own diversion after the renderer
272 // is created.
273 const restoreStrayCapture = interactive ? undefined : captureStrayOutput(logFile);
274
275 const summary = yield* Effect.gen(function* () {
276 const reporter = yield* Reporter;
277 const summary = yield* run(options);
278 yield* reporter.waitForExit(summary);
279 return summary;
280 }).pipe(
281 Effect.provide(interactive ? tuiReporter(logFile) : PlainReporterLive),
282 Effect.scoped,
283 Effect.onExit(() => Effect.sync(() => restoreStrayCapture?.())),
284 );
285
286 // After the TUI tears down, leave a plain record in the terminal.
287 if (interactive) {
288 yield* printSummary(summary);
289 }
290
291 // Point agents/tooling at the full run log, with its size so the reader
292 // knows what they're getting into before opening it.
293 yield* Effect.gen(function* () {
294 const fs = yield* FileSystem.FileSystem;
295 const stats = yield* fs.stat(logFile).pipe(Effect.orElseSucceed(() => undefined));
296 const kb = stats === undefined ? 0 : Number(stats.size) / 1024;
297 yield* Effect.sync(() => {
298 process.stdout.write(`\nFull log: ${logFile} (${kb.toFixed(1)} KB)\n`);
299 });
300 });
301
302 if (summary.failed > 0) {
303 yield* Effect.sync(() => {
304 process.exitCode = 1;
305 });
306 }
307 }),
308 );
309
310 const cli = Command.run(rootCommand, {
311 version: packageJson.version,
312 });
313
314 cli.pipe(Effect.provide(Layer.mergeAll(BunServices.layer)), Effect.scoped, (effect) =>
315 BunRuntime.runMain(effect as Effect.Effect<void>, {
316 // ALWAYS exit once the main effect completes. runMain's default only
317 // force-exits on failure/signal — but tests can leak live handles
318 // (vite watchers, workerd sidecar sockets, keep-alive agents) that
319 // keep bun's event loop alive forever after a green run. Everything
320 // is already flushed by now (summary + log written in the main
321 // effect); the macrotask hop lets any buffered stdout drain.
322 teardown: (exit, onExit) => {
323 Runtime.defaultTeardown(exit, (code) => {
324 const finalCode = code !== 0 ? code : Number(process.exitCode ?? 0) || 0;
325 setTimeout(() => process.exit(finalCode), 0);
326 onExit(finalCode);
327 });
328 },
329 }),
330 );