@alchemy.run/test 0.0.0 → 2.0.0-beta.86

package/src/Bun.ts

@@ -0,0 +1,254 @@
+import bun from "bun:test";
+import type { HookOptions } from "node:test";
+import type { AlchemyContext } from "alchemy/AlchemyContext";
+import type { CompiledStack, StackDefinition } from "alchemy/Stack";
+import type { Stage } from "alchemy/Stage";
+import * as Cause from "effect/Cause";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Scope from "effect/Scope";
+import * as Core from "./Core.ts";
+
+export {
+  executeWhenReady,
+  getWhenReady,
+  guardContentType,
+  guardedFetchLayer,
+  rpcClientLayer,
+  WorkerNotReady,
+  type EdgeGuardOptions,
+  type WhenReadyOptions,
+} from "./Http.ts";
+
+export type MakeOptions<ROut = any> = Core.MakeOptions<ROut>;
+export type ScratchStack = Core.ScratchStack;
+export type TestEffect<A, R = never> = Core.TestEffect<A, R>;
+export const defaultStage = Core.defaultStage;
+export const resolveStage = Core.resolveStage;
+
+export interface TestApi {
+  test: TestFn;
+  beforeAll: BeforeAllFn;
+  beforeEach: BeforeEachFn;
+  afterAll: AfterAllFn;
+  afterEach: AfterEachFn;
+  deploy: Core.Deploy;
+  destroy: <ROut>(
+    stack: StackDefinition<ROut>,
+    options?: { stage?: string; include?: never; exclude?: never },
+  ) => ReturnType<typeof Core.destroy>;
+}
+
+interface TestFn {
+  (name: string, eff: TestEffect<void>, options?: bun.TestOptions): void;
+  skip: (name: string, eff: TestEffect<void>, options?: bun.TestOptions) => void;
+  skipIf: (
+    condition: boolean,
+  ) => (name: string, eff: TestEffect<void>, options?: bun.TestOptions) => void;
+  only: (name: string, eff: TestEffect<void>, options?: bun.TestOptions) => void;
+  todo: (name: string, eff: TestEffect<void>, options?: bun.TestOptions) => void;
+  provider: ProviderFn;
+}
+
+interface ProviderFn {
+  (
+    name: string,
+    fn: (stack: ScratchStack) => Effect.Effect<void, any, any>,
+    options?: bun.TestOptions,
+  ): void;
+  skip: (
+    name: string,
+    fn: (stack: ScratchStack) => Effect.Effect<void, any, any>,
+    options?: bun.TestOptions,
+  ) => void;
+  skipIf: (
+    condition: boolean,
+  ) => (
+    name: string,
+    fn: (stack: ScratchStack) => Effect.Effect<void, any, any>,
+    options?: bun.TestOptions,
+  ) => void;
+}
+
+interface BeforeAllFn {
+  <A>(eff: TestEffect<A>, options?: HookOptions): Effect.Effect<A>;
+}
+
+interface BeforeEachFn {
+  (eff: TestEffect<void>, options?: HookOptions): void;
+}
+
+interface AfterAllFn {
+  (eff: TestEffect<any>, options?: HookOptions): void;
+  skipIf: (predicate: boolean) => (eff: TestEffect<any>, options?: HookOptions) => void;
+}
+
+interface AfterEachFn {
+  (eff: TestEffect<void>, options?: HookOptions): void;
+}
+
+const DEFAULT_HOOK_TIMEOUT: HookOptions = { timeout: 120_000 };
+
+/** The timeout bun applies to a test, from its options. */
+const timeoutOf = (options: bun.TestOptions | undefined): number | undefined =>
+  typeof options === "number" ? options : options?.timeout;
+
+/**
+ * Interrupt `eff` shortly before bun's own timeout. When bun times a test or
+ * hook out it only stops waiting: the effect keeps running, so the file's
+ * `afterAll` destroy races a deploy still creating resources, and whatever
+ * that deploy creates afterwards is never cleaned up. Interrupting it first
+ * lets the engine record what it created, so the destroy that follows finds
+ * it.
+ */
+const DEADLINE_MARGIN_MS = 5_000;
+const withDeadline = <A, E, R>(
+  eff: Effect.Effect<A, E, R>,
+  timeout: number | undefined,
+): Effect.Effect<A, E | Cause.TimeoutError, R> =>
+  timeout === undefined || timeout <= DEADLINE_MARGIN_MS * 2
+    ? eff
+    : eff.pipe(Effect.timeout(Duration.millis(timeout - DEADLINE_MARGIN_MS)));
+
+/**
+ * Build the per-file test API. Configure providers / state once at the top of
+ * the test file:
+ *
+ * ```ts
+ * import * as Test from "@alchemy.run/test/Bun";
+ * import * as Cloudflare from "@alchemy.run/cloudflare";
+ *
+ * const { test, deploy, destroy, beforeAll, afterAll } = Test.make({
+ *   providers: Cloudflare.providers(),
+ *   state: Cloudflare.state(),
+ * });
+ * ```
+ */
+export const make = <ROut = any>(options: MakeOptions<ROut>): TestApi => {
+  // Single scope shared across `beforeAll`, every `test`, and `afterAll`.
+  // Scoped resources in dev mode (the Cloudflare sidecar process and its
+  // workerd children) must outlive a single `Effect.runPromise` boundary,
+  // otherwise the proxy is killed the moment `beforeAll(deploy(Stack))`
+  // resolves and every later `HttpClient.get(workerUrl)` hits a dead port.
+  // The scope is closed by `destroy(...)` (or never — the next test run
+  // reclaims any leaked sidecar via the lock file).
+  const sharedScope = Scope.makeUnsafe("sequential");
+  // In dev mode, run local providers behind one file-scoped RPC sidecar
+  // (the `alchemy dev` topology). Lives in its own scope — NOT sharedScope,
+  // which `destroy(Stack)` closes mid-file in self-contained tests — and is
+  // closed by the fallback afterAll below.
+  const sidecar = Core.makeSidecarHandle(options);
+  const runEff = <A>(eff: TestEffect<A>, timeout?: number) =>
+    Core.run(withDeadline(eff, timeout), options, sharedScope, sidecar);
+
+  const test = ((name, eff, opts) => {
+    bun.test(name, () => runEff(eff, timeoutOf(opts)), opts);
+  }) as TestFn;
+
+  test.skip = (name, eff, opts) => {
+    bun.test.skip(name, () => runEff(eff, timeoutOf(opts)), opts);
+  };
+  test.skipIf = (condition) => (name, eff, opts) => {
+    bun.test.skipIf(condition)(name, () => runEff(eff, timeoutOf(opts)), opts);
+  };
+  test.only = (name, eff, opts) => {
+    bun.test.only(name, () => runEff(eff, timeoutOf(opts)), opts);
+  };
+  test.todo = (name, eff, opts) => {
+    bun.test.todo(name, () => runEff(eff, timeoutOf(opts)), opts);
+  };
+
+  const runProvider = (
+    name: string,
+    fn: (stack: ScratchStack) => Effect.Effect<void, any, any>,
+    timeout?: number,
+  ) => {
+    const scratch = Core.scratchStack(options, name);
+    return Core.run(
+      withDeadline(Core.withProviders(fn(scratch), options, scratch.name), timeout),
+      { ...options, state: scratch.state },
+      sharedScope,
+      sidecar,
+    );
+  };
+
+  const provider = ((name, fn, opts) => {
+    bun.test(name, () => runProvider(name, fn, timeoutOf(opts)), opts);
+  }) as ProviderFn;
+  provider.skip = (name, fn, opts) => {
+    bun.test.skip(name, () => runProvider(name, fn, timeoutOf(opts)), opts);
+  };
+  provider.skipIf = (condition) => (name, fn, opts) => {
+    bun.test.skipIf(condition)(name, () => runProvider(name, fn, timeoutOf(opts)), opts);
+  };
+  test.provider = provider;
+
+  const beforeAll: BeforeAllFn = <A>(eff: TestEffect<A>, hookOptions?: HookOptions) => {
+    let result: A;
+    const options = hookOptions ?? DEFAULT_HOOK_TIMEOUT;
+    bun.beforeAll(() => runEff(eff, options.timeout).then((v) => (result = v)), options);
+    return Effect.sync(() => result);
+  };
+
+  const beforeEach: BeforeEachFn = (eff, hookOptions) => {
+    bun.beforeEach(() => runEff(eff), hookOptions);
+  };
+
+  // bun:test stops running later `afterAll` hooks once one throws, which
+  // would skip the fallback cleanup hook below — leaking the shared scope
+  // and the sidecar for the rest of the process whenever a teardown
+  // assertion fails. Guard every user teardown: on failure, run the
+  // (idempotent) cleanup before rethrowing so the failure still fails the
+  // suite. (`closeAll` is initialized below; hooks only run after `make`
+  // returns.)
+  const guardTeardown = (eff: TestEffect<any>) => () =>
+    runEff(eff).catch(async (error) => {
+      await Effect.runPromise(closeAll);
+      throw error;
+    });
+
+  const afterAll = ((eff, hookOptions) => {
+    bun.afterAll(guardTeardown(eff), hookOptions ?? DEFAULT_HOOK_TIMEOUT);
+  }) as AfterAllFn;
+  afterAll.skipIf = (predicate) => (eff, hookOptions) => {
+    if (predicate) return;
+    bun.afterAll(guardTeardown(eff), hookOptions ?? DEFAULT_HOOK_TIMEOUT);
+  };
+
+  const afterEach: AfterEachFn = (eff, hookOptions) => {
+    bun.afterEach(() => runEff(eff), hookOptions);
+  };
+
+  // `destroy(Stack)` needs the dev sidecar alive so it can call `sidecar.stop`
+  // for each worker. We close the shared scope only AFTER destroy completes.
+  // `Scope.close` on an already-closed scope is a no-op, so it's safe for both
+  // the destroy wrapper AND the fallback cleanup hook below to call it.
+  const closeScope = Effect.suspend(() => Scope.close(sharedScope, Exit.void)).pipe(Effect.ignore);
+
+  // Fallback cleanup: if the user never calls `destroy(Stack)` (e.g.
+  // `NO_DESTROY=1`), nothing else closes the shared scope and the sidecar
+  // child process leaks past the test process. Register an `afterAll` that
+  // closes it (and the RPC sidecar, which lives in its own scope so that
+  // mid-file `destroy(Stack)` calls can't kill it for later tests). We defer
+  // registration to a microtask so it runs AFTER any user-registered
+  // `afterAll` (including `destroy(Stack)`); bun runs afterAll hooks in
+  // registration order.
+  const closeAll = sidecar ? Effect.andThen(closeScope, sidecar.close) : closeScope;
+  queueMicrotask(() => {
+    bun.afterAll(() => Effect.runPromise(closeAll), DEFAULT_HOOK_TIMEOUT);
+  });
+
+  return {
+    test,
+    beforeAll,
+    beforeEach,
+    afterAll,
+    afterEach,
+    deploy: Core.makeDeploy(options, sharedScope),
+    destroy: (stack, callOpts) =>
+      Core.destroy(options, stack, { ...callOpts, scope: sharedScope }).pipe(
+        Effect.ensuring(closeScope),
+      ),
+  };
+};

package/src/Capture.ts

@@ -0,0 +1,72 @@
+import type { LogEntry } from "./Model.ts";
+
+const CAPTURE_BYTES = 256 * 1024;
+const TOTAL_BYTES = 16 * 1024 * 1024;
+const TRUNCATED = "[Earlier output omitted from preview; full output is in the run log.]";
+
+/** Bounded live previews; every original entry is persisted before trimming. */
+export const makeCapture = (limits = { capture: CAPTURE_BYTES, total: TOTAL_BYTES }) => {
+  const buffers = new Map<Array<LogEntry>, number>();
+  let total = 0;
+  const size = (entry: LogEntry) => Buffer.byteLength(entry.message, "utf8") + 64;
+  const release = (buffer: Array<LogEntry>) => {
+    total -= buffers.get(buffer) ?? 0;
+    buffers.delete(buffer);
+    buffer.length = 0;
+  };
+  const trim = (buffer: Array<LogEntry>, limit: number) => {
+    let bytes = buffers.get(buffer) ?? 0;
+    let removed = false;
+    while (bytes > limit && buffer.length > 0) {
+      const entry = buffer.shift()!;
+      const cost = size(entry);
+      bytes -= cost;
+      total -= cost;
+      removed = true;
+    }
+    if (removed && buffer.length > 0 && buffer[0]!.message !== TRUNCATED) {
+      const entry = {
+        level: "info",
+        message: TRUNCATED,
+        time: buffer[0]!.time,
+      };
+      buffer.unshift(entry);
+      bytes += size(entry);
+      total += size(entry);
+    }
+    if (bytes === 0) buffers.delete(buffer);
+    else buffers.set(buffer, bytes);
+  };
+  const create = (persist: (entry: LogEntry) => void): Array<LogEntry> => {
+    const buffer: Array<LogEntry> = [];
+    buffer.push = (...entries) => {
+      for (const entry of entries) {
+        persist(entry);
+        // A single oversized message must not defeat either preview limit.
+        const maxChars = Math.max(
+          0,
+          Math.floor((Math.min(limits.capture, limits.total) - 256) / 4),
+        );
+        const preview =
+          entry.message.length > maxChars
+            ? {
+                ...entry,
+                message: `${TRUNCATED}\n${maxChars === 0 ? "" : entry.message.slice(-maxChars)}`,
+              }
+            : entry;
+        Array.prototype.push.call(buffer, preview);
+        const cost = size(preview);
+        buffers.set(buffer, (buffers.get(buffer) ?? 0) + cost);
+        total += cost;
+        trim(buffer, Math.max(0, limits.capture - 256));
+        while (total > limits.total && buffers.size > 0) {
+          const oldest = buffers.keys().next().value!;
+          release(oldest);
+        }
+      }
+      return buffer.length;
+    };
+    return buffer;
+  };
+  return { create, release };
+};