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

main
ts 335 lines 11.6 KB
Raw
1 /** @effect-diagnostics anyUnknownInErrorContext:off */
2
3 import type { AlchemyContext } from "alchemy/AlchemyContext";
4 import type { CompiledStack, StackDefinition } from "alchemy/Stack";
5 import type { Stage } from "alchemy/Stage";
6 import * as Effect from "effect/Effect";
7 import * as Exit from "effect/Exit";
8 import * as Scope from "effect/Scope";
9 import * as Semaphore from "effect/Semaphore";
10 import * as Core from "./Core.ts";
11 /**
12 * Test adapter for the `alchemy-test` runner (see `packages/alchemy-test`).
13 *
14 * Same shape as {@link "./Vitest.ts"} / {@link "./Bun.ts"}, but registers
15 * tests as raw Effects with the alchemy-test harness so the single-process
16 * runner can inject a buffering Logger/Console per test and manage
17 * concurrency + timeouts itself.
18 */
19 import {
20 currentFile,
21 exclusiveOf,
22 registerFileCleanup,
23 registerHook,
24 registerTest,
25 retryOf,
26 tagsOf,
27 optInTagsOf,
28 timeoutOf,
29 type TestOptions,
30 } from "./index.ts";
31
32 export {
33 executeWhenReady,
34 getWhenReady,
35 guardContentType,
36 guardedFetchLayer,
37 rpcClientLayer,
38 WorkerNotReady,
39 type EdgeGuardOptions,
40 type WhenReadyOptions,
41 } from "./Http.ts";
42
43 export type MakeOptions<ROut = any> = Core.MakeOptions<ROut>;
44 export type ScratchStack = Core.ScratchStack;
45 export type TestEffect<A, R = never> = Core.TestEffect<A, R>;
46 export const ALCHEMY_TEST_DEV = Core.ALCHEMY_TEST_DEV;
47 export const resolveDev = Core.resolveDev;
48 export const defaultStage = Core.defaultStage;
49 export const resolveStage = Core.resolveStage;
50 export const captureResourceLog = Core.captureResourceLog;
51
52 interface TestFn {
53 (name: string, eff: TestEffect<void>, options?: TestOptions): void;
54 skip: (name: string, eff: TestEffect<void>, options?: TestOptions) => void;
55 skipIf: (
56 condition: boolean,
57 ) => (name: string, eff: TestEffect<void>, options?: TestOptions) => void;
58 only: (name: string, eff: TestEffect<void>, options?: TestOptions) => void;
59 todo: (name: string, eff: TestEffect<void>, options?: TestOptions) => void;
60 provider: ProviderFn;
61 }
62
63 interface ProviderFn {
64 (
65 name: string,
66 fn: (stack: ScratchStack) => Effect.Effect<void, any, any>,
67 options?: TestOptions,
68 ): void;
69 skip: (
70 name: string,
71 fn: (stack: ScratchStack) => Effect.Effect<void, any, any>,
72 options?: TestOptions,
73 ) => void;
74 skipIf: (
75 condition: boolean,
76 ) => (
77 name: string,
78 fn: (stack: ScratchStack) => Effect.Effect<void, any, any>,
79 options?: TestOptions,
80 ) => void;
81 todo: (
82 name: string,
83 fn: (stack: ScratchStack) => Effect.Effect<void, any, any>,
84 options?: TestOptions,
85 ) => void;
86 }
87
88 interface BeforeAllFn {
89 <A>(eff: TestEffect<A>, options?: TestOptions): Effect.Effect<A>;
90 }
91
92 interface BeforeEachFn {
93 (eff: TestEffect<void>, options?: TestOptions): void;
94 }
95
96 interface AfterAllFn {
97 (eff: TestEffect<any>, options?: TestOptions): void;
98 skipIf: (predicate: boolean) => (eff: TestEffect<any>, options?: TestOptions) => void;
99 }
100
101 interface AfterEachFn {
102 (eff: TestEffect<void>, options?: TestOptions): void;
103 }
104
105 export interface TestApi {
106 test: TestFn;
107 beforeAll: BeforeAllFn;
108 beforeEach: BeforeEachFn;
109 afterAll: AfterAllFn;
110 afterEach: AfterEachFn;
111 deploy: Core.Deploy;
112 destroy: <ROut>(
113 stack: StackDefinition<ROut>,
114 options?: { stage?: string; include?: never; exclude?: never },
115 ) => ReturnType<typeof Core.destroy>;
116 }
117
118 const DEFAULT_TIMEOUT = 120_000;
119
120 /**
121 * Build the per-file test API. Configure providers / state once at the top of
122 * the test file:
123 *
124 * ```ts
125 * import * as Test from "@alchemy.run/test/Alchemy";
126 * import * as Cloudflare from "@alchemy.run/cloudflare";
127 *
128 * const { test, deploy, destroy, beforeAll, afterAll } = Test.make({
129 * providers: Cloudflare.providers(),
130 * state: Cloudflare.state(),
131 * });
132 * ```
133 */
134 export const make = <ROut = any>(options: MakeOptions<ROut>): TestApi => {
135 // Single scope shared across `beforeAll`, every `test`, and `afterAll`.
136 // Scoped resources in dev mode (the Cloudflare dev proxy and its workerd
137 // children) must outlive a single test boundary, otherwise the proxy is
138 // killed the moment `beforeAll(deploy(Stack))` resolves and every later
139 // `HttpClient.get(workerUrl)` hits a dead port. The scope is closed by
140 // `destroy(...)` (or by file cleanup below).
141 let sharedScope: Scope.Closeable | undefined = Scope.makeUnsafe("sequential");
142 // Session ownership outlives a mid-file destroy, but not file cleanup.
143 let sidecar = Core.makeSidecarHandle(options);
144 const clearResults = new Set<() => void>();
145 const wrap = <A>(eff: TestEffect<A>) =>
146 sharedScope === undefined
147 ? Effect.die("Test runtime is closed")
148 : Core.toEffect(eff, options, sharedScope, sidecar);
149
150 const addTest = (
151 name: string,
152 eff: TestEffect<void>,
153 opts: TestOptions | undefined,
154 mode: "run" | "skip" | "only" | "todo",
155 ) =>
156 registerTest({
157 name,
158 mode,
159 exclusive: exclusiveOf(opts),
160 retry: retryOf(opts),
161 timeout: timeoutOf(opts),
162 tags: tagsOf(opts),
163 optInTags: optInTagsOf(opts),
164 body: mode === "skip" || mode === "todo" ? undefined : () => wrap(eff),
165 });
166
167 const test = ((name, eff, opts) => {
168 addTest(name, eff, opts, "run");
169 }) as TestFn;
170
171 test.skip = (name, eff, opts) => addTest(name, eff, opts, "skip");
172 test.skipIf = (condition) => (name, eff, opts) =>
173 addTest(name, eff, opts, condition ? "skip" : "run");
174 test.only = (name, eff, opts) => addTest(name, eff, opts, "only");
175 test.todo = (name, eff, opts) => addTest(name, eff, opts, "todo");
176
177 // One lock per scratch stack. When an attempt times out, the runner fires
178 // an interrupt and ABANDONS the attempt's fiber after a short grace — but
179 // the fiber keeps running its teardown (`scratch.destroy()` below) in the
180 // background, e.g. a CloudFront disable-wait. Without this lock the retry
181 // starts concurrently on the SAME scratch state: the stale teardown then
182 // deletes the state rows the retry just wrote for the same logical ids,
183 // orphaning the retry's cloud resources (observed: two leaked CloudFront
184 // distributions + buckets + OACs from one retried test). Holding the lock
185 // across body + teardown makes a retry wait (on its own timeout clock)
186 // until the previous attempt's teardown has fully settled.
187 const scratchLocks = new Map<string, Semaphore.Semaphore>();
188 const scratchLock = (name: string) => {
189 let lock = scratchLocks.get(name);
190 if (lock === undefined) {
191 lock = Semaphore.makeUnsafe(1);
192 scratchLocks.set(name, lock);
193 }
194 return lock;
195 };
196
197 const wrapProvider = (
198 name: string,
199 fn: (stack: ScratchStack) => Effect.Effect<void, any, any>,
200 file: string | undefined,
201 ) => {
202 if (sharedScope === undefined) return Effect.die("Test runtime is closed");
203 // Durable, file-namespaced scratch state (`.alchemy/state`). A run that
204 // dies mid-delete — e.g. the runner abandons teardown 10s after a test
205 // timeout while a CloudFront disable-wait is still in flight — leaves
206 // its `deleting` rows on disk, so the NEXT run's leading
207 // `stack.destroy()` (or the ensuring teardown below) resumes and drains
208 // them instead of planning "no changes" and silently orphaning the
209 // cloud resource.
210 const scratch = Core.scratchStack(options, name, file);
211 // Guarantee teardown. `test.provider` has no built-in cleanup, so a body
212 // that fails (assertion, API error like a 409/Unauthorized) or is
213 // interrupted (timeout) BEFORE its trailing `stack.destroy()` would
214 // otherwise leak every cloud resource it deployed.
215 // `scratch.destroy()` is idempotent — a no-op when the body already
216 // destroyed, and it reclaims the orphans otherwise. `Effect.ensuring`
217 // runs the finalizer on success, failure, AND interruption.
218 const body = Core.withProviders(fn(scratch), options, scratch.name).pipe(
219 Effect.ensuring(scratch.destroy().pipe(Effect.ignore)),
220 scratchLock(scratch.name).withPermits(1),
221 );
222 return Core.toEffect(body, { ...options, state: scratch.state }, sharedScope, sidecar);
223 };
224
225 const addProvider = (
226 name: string,
227 fn: (stack: ScratchStack) => Effect.Effect<void, any, any>,
228 opts: TestOptions | undefined,
229 mode: "run" | "skip" | "todo",
230 ) => {
231 // Captured at registration (module evaluation during collection) — the
232 // collection context is gone by the time the body runs.
233 const file = currentFile();
234 registerTest({
235 name,
236 mode,
237 exclusive: exclusiveOf(opts),
238 retry: retryOf(opts),
239 timeout: timeoutOf(opts),
240 tags: tagsOf(opts),
241 optInTags: optInTagsOf(opts),
242 body: mode === "run" ? () => wrapProvider(name, fn, file) : undefined,
243 });
244 };
245
246 const provider = ((name, fn, opts) => {
247 addProvider(name, fn, opts, "run");
248 }) as ProviderFn;
249 provider.skip = (name, fn, opts) => addProvider(name, fn, opts, "skip");
250 provider.skipIf = (condition) => (name, fn, opts) =>
251 addProvider(name, fn, opts, condition ? "skip" : "run");
252 provider.todo = (name, fn, opts) => addProvider(name, fn, opts, "todo");
253 test.provider = provider;
254
255 const beforeAll: BeforeAllFn = <A>(eff: TestEffect<A>, hookOptions?: TestOptions) => {
256 let result: A | undefined;
257 clearResults.add(() => {
258 result = undefined;
259 });
260 registerHook("beforeAll", {
261 body: () =>
262 wrap(eff).pipe(
263 Effect.map((value) => {
264 if (sharedScope !== undefined) result = value;
265 }),
266 ),
267 timeout: timeoutOf(hookOptions) ?? DEFAULT_TIMEOUT,
268 exclusive: exclusiveOf(hookOptions),
269 });
270 return Effect.sync(() => result as A);
271 };
272
273 const beforeEach: BeforeEachFn = (eff, hookOptions) => {
274 registerHook("beforeEach", { body: () => wrap(eff), timeout: timeoutOf(hookOptions) });
275 };
276
277 const afterAll = ((eff, hookOptions) => {
278 registerHook("afterAll", {
279 body: () => wrap(eff),
280 timeout: timeoutOf(hookOptions) ?? DEFAULT_TIMEOUT,
281 exclusive: exclusiveOf(hookOptions),
282 });
283 }) as AfterAllFn;
284 afterAll.skipIf = (predicate) => (eff, hookOptions) => {
285 if (predicate) return;
286 registerHook("afterAll", {
287 body: () => wrap(eff),
288 timeout: timeoutOf(hookOptions) ?? DEFAULT_TIMEOUT,
289 exclusive: exclusiveOf(hookOptions),
290 });
291 };
292
293 const afterEach: AfterEachFn = (eff, hookOptions) => {
294 registerHook("afterEach", { body: () => wrap(eff), timeout: timeoutOf(hookOptions) });
295 };
296
297 // `destroy(Stack)` needs the dev sidecar alive so it can call `sidecar.stop`
298 // for each worker. We close the shared scope only AFTER destroy completes.
299 // `Scope.close` on an already-closed scope is a no-op, so it's safe for both
300 // the destroy wrapper AND the fallback cleanup hook below to call it.
301 const closeScope = Effect.suspend(() =>
302 sharedScope === undefined ? Effect.void : Scope.close(sharedScope, Exit.void),
303 ).pipe(Effect.ignore);
304
305 // File cleanup runs after user afterAll, including skipped/failed imports.
306 // Interactive retries retain the runtime until the runner releases the file.
307 registerFileCleanup({
308 body: () =>
309 closeScope.pipe(
310 Effect.ensuring(Effect.suspend(() => sidecar?.close ?? Effect.void)),
311 Effect.ensuring(
312 Effect.sync(() => {
313 sharedScope = undefined;
314 sidecar = undefined;
315 for (const clear of clearResults) clear();
316 clearResults.clear();
317 }),
318 ),
319 ),
320 timeout: DEFAULT_TIMEOUT,
321 });
322
323 return {
324 test,
325 beforeAll,
326 beforeEach,
327 afterAll,
328 afterEach,
329 deploy: Core.makeDeploy(options, sharedScope),
330 destroy: (stack, callOpts) =>
331 Core.destroy(options, stack, { ...callOpts, scope: sharedScope }).pipe(
332 Effect.ensuring(closeScope),
333 ),
334 };
335 };