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

package/lib/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * alchemy-test — a minimal, Effect-native, vitest-compatible test harness.
+ *
+ * This entrypoint is safe to import from anywhere (including code that gets
+ * bundled into Workers): it only contains the registration API and the
+ * assertion library. The runner, CLI and TUI live in separate modules that
+ * are only loaded by the `alchemy-test` binary.
+ */
+export { afterAll, afterEach, beforeAll, beforeEach, describe, exclusiveOf, it, layer, registerFileCleanup, registerHook, registerTest, retryOf, test, tagsOf, optInTagsOf, timeoutOf, type DescribeFn, type DescribeOptions, type HookKind, type LayerMethods, type RegisterTestOptions, type TestContext, type Tester, type TestFn, type TestOptions, } from "./Api.ts";
+export { assert, AssertionError, equals, expect, stringify, type Assert, type Expect, type Matchers, } from "./Expect.ts";
+export { currentFile } from "./Registry.ts";
+export type { Tags, TestTag, TestTags } from "./Tags.ts";
+export type { Exclusive, FileSuite, Hook, Limit, LogEntry, Mode, Suite, TestBody, TestCase, } from "./Model.ts";
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,QAAQ,EACR,SAAS,EACT,SAAS,EACT,UAAU,EACV,QAAQ,EACR,WAAW,EACX,EAAE,EACF,KAAK,EACL,mBAAmB,EACnB,YAAY,EACZ,YAAY,EACZ,OAAO,EACP,IAAI,EACJ,MAAM,EACN,WAAW,EACX,SAAS,EACT,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,MAAM,EACX,KAAK,MAAM,EACX,KAAK,WAAW,GACjB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,MAAM,EACN,cAAc,EACd,MAAM,EACN,MAAM,EACN,SAAS,EACT,KAAK,MAAM,EACX,KAAK,MAAM,EACX,KAAK,QAAQ,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACzD,YAAY,EACV,SAAS,EACT,SAAS,EACT,IAAI,EACJ,KAAK,EACL,QAAQ,EACR,IAAI,EACJ,KAAK,EACL,QAAQ,EACR,QAAQ,GACT,MAAM,YAAY,CAAC"}

package/lib/index.js

@@ -0,0 +1,12 @@
+/**
+ * alchemy-test — a minimal, Effect-native, vitest-compatible test harness.
+ *
+ * This entrypoint is safe to import from anywhere (including code that gets
+ * bundled into Workers): it only contains the registration API and the
+ * assertion library. The runner, CLI and TUI live in separate modules that
+ * are only loaded by the `alchemy-test` binary.
+ */
+export { afterAll, afterEach, beforeAll, beforeEach, describe, exclusiveOf, it, layer, registerFileCleanup, registerHook, registerTest, retryOf, test, tagsOf, optInTagsOf, timeoutOf, } from "./Api.js";
+export { assert, AssertionError, equals, expect, stringify, } from "./Expect.js";
+export { currentFile } from "./Registry.js";
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,QAAQ,EACR,SAAS,EACT,SAAS,EACT,UAAU,EACV,QAAQ,EACR,WAAW,EACX,EAAE,EACF,KAAK,EACL,mBAAmB,EACnB,YAAY,EACZ,YAAY,EACZ,OAAO,EACP,IAAI,EACJ,MAAM,EACN,WAAW,EACX,SAAS,GAUV,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,MAAM,EACN,cAAc,EACd,MAAM,EACN,MAAM,EACN,SAAS,GAIV,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alchemy.run/test",
-  "version": "0.0.0",
+  "version": "2.0.0-beta.86",
   "description": "Minimal Effect-native, vitest-compatible test harness and single-process runner for Bun.",
   "keywords": [
     "alchemy",
@@ -10,12 +10,82 @@
     "test-runner",
     "vitest"
   ],
+  "homepage": "https://alchemy.run",
+  "bugs": {
+    "url": "https://github.com/alchemy-run/alchemy/issues"
+  },
   "license": "Apache-2.0",
   "author": "Sam Goodwin <sam@alchemy.run>",
-  "homepage": "https://alchemy.run",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/alchemy-run/alchemy.git",
     "directory": "packages/alchemy-test"
+  },
+  "bin": {
+    "alchemy-test": "./bin/alchemy-test.ts"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "src"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "bun": "./src/index.ts",
+      "default": "./lib/index.js"
+    },
+    "./*": {
+      "types": "./lib/*.d.ts",
+      "bun": "./src/*.ts",
+      "default": "./lib/*.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@effect/platform-bun": "^4.1.4"
+  },
+  "devDependencies": {
+    "@effect/vitest": "^4.1.4",
+    "@opentui/core": "^0.6.6",
+    "@types/bun": "1.4.3",
+    "alchemy": "2.0.0-beta.86",
+    "effect": "^4.1.4",
+    "typescript": "^7.1.0-dev.20261105.1",
+    "vitest": "^5.0.4"
+  },
+  "peerDependencies": {
+    "@effect/vitest": "^4.1.4",
+    "@opentui/core": "^0.6.6",
+    "alchemy": "2.0.0-beta.86",
+    "effect": "^4.1.4",
+    "vitest": "^5.0.4"
+  },
+  "peerDependenciesMeta": {
+    "@effect/vitest": {
+      "optional": true
+    },
+    "@opentui/core": {
+      "optional": true
+    },
+    "alchemy": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "bun": ">=1.3"
+  },
+  "scripts": {
+    "build": "pnpm -r --filter \"{.}...\" run build:package",
+    "build:package": "node scripts/build.ts",
+    "test:vitest": "vitest run --config vitest/vitest.config.ts"
   }
-}
+}

package/src/Alchemy.ts

@@ -0,0 +1,337 @@
+import type { AlchemyContext } from "alchemy/AlchemyContext";
+import type { CompiledStack, StackDefinition } from "alchemy/Stack";
+import type { Stage } from "alchemy/Stage";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Scope from "effect/Scope";
+import * as Semaphore from "effect/Semaphore";
+import * as Core from "./Core.ts";
+/**
+ * Test adapter for the `alchemy-test` runner (see `packages/alchemy-test`).
+ *
+ * Same shape as {@link "./Vitest.ts"} / {@link "./Bun.ts"}, but registers
+ * tests as raw Effects with the alchemy-test harness so the single-process
+ * runner can inject a buffering Logger/Console per test and manage
+ * concurrency + timeouts itself.
+ */
+import {
+  currentFile,
+  exclusiveOf,
+  registerFileCleanup,
+  registerHook,
+  registerTest,
+  retryOf,
+  tagsOf,
+  optInTagsOf,
+  timeoutOf,
+  type Exclusive,
+  type TestOptions,
+} from "./index.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 ALCHEMY_TEST_DEV = Core.ALCHEMY_TEST_DEV;
+export const resolveDev = Core.resolveDev;
+export const defaultStage = Core.defaultStage;
+export const resolveStage = Core.resolveStage;
+export const captureResourceLog = Core.captureResourceLog;
+
+interface TestFn {
+  (name: string, eff: TestEffect<void>, options?: TestOptions): void;
+  skip: (name: string, eff: TestEffect<void>, options?: TestOptions) => void;
+  skipIf: (
+    condition: boolean,
+  ) => (name: string, eff: TestEffect<void>, options?: TestOptions) => void;
+  only: (name: string, eff: TestEffect<void>, options?: TestOptions) => void;
+  todo: (name: string, eff: TestEffect<void>, options?: TestOptions) => void;
+  provider: ProviderFn;
+}
+
+interface ProviderFn {
+  (
+    name: string,
+    fn: (stack: ScratchStack) => Effect.Effect<void, any, any>,
+    options?: TestOptions,
+  ): void;
+  skip: (
+    name: string,
+    fn: (stack: ScratchStack) => Effect.Effect<void, any, any>,
+    options?: TestOptions,
+  ) => void;
+  skipIf: (
+    condition: boolean,
+  ) => (
+    name: string,
+    fn: (stack: ScratchStack) => Effect.Effect<void, any, any>,
+    options?: TestOptions,
+  ) => void;
+  todo: (
+    name: string,
+    fn: (stack: ScratchStack) => Effect.Effect<void, any, any>,
+    options?: TestOptions,
+  ) => void;
+}
+
+interface BeforeAllFn {
+  <A>(eff: TestEffect<A>, options?: TestOptions): Effect.Effect<A>;
+}
+
+interface BeforeEachFn {
+  (eff: TestEffect<void>, options?: TestOptions): void;
+}
+
+interface AfterAllFn {
+  (eff: TestEffect<any>, options?: TestOptions): void;
+  skipIf: (predicate: boolean) => (eff: TestEffect<any>, options?: TestOptions) => void;
+}
+
+interface AfterEachFn {
+  (eff: TestEffect<void>, options?: TestOptions): void;
+}
+
+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>;
+}
+
+const DEFAULT_TIMEOUT = 120_000;
+
+/**
+ * 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/Alchemy";
+ * 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 dev proxy and its workerd
+  // children) must outlive a single test 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 by file cleanup below).
+  let sharedScope: Scope.Closeable | undefined = Scope.makeUnsafe("sequential");
+  // Session ownership outlives a mid-file destroy, but not file cleanup.
+  let sidecar = Core.makeSidecarHandle(options);
+  const clearResults = new Set<() => void>();
+  // Every test and beforeAll/afterAll hook also holds the file's limit.
+  const exclusive = (opts: TestOptions | undefined): Exclusive =>
+    options.limit === undefined ? exclusiveOf(opts) : [exclusiveOf(opts), options.limit].flat();
+  const wrap = <A>(eff: TestEffect<A>) =>
+    sharedScope === undefined
+      ? Effect.die("Test runtime is closed")
+      : Core.toEffect(eff, options, sharedScope, sidecar);
+
+  const addTest = (
+    name: string,
+    eff: TestEffect<void>,
+    opts: TestOptions | undefined,
+    mode: "run" | "skip" | "only" | "todo",
+  ) =>
+    registerTest({
+      name,
+      mode,
+      exclusive: exclusive(opts),
+      retry: retryOf(opts),
+      timeout: timeoutOf(opts),
+      tags: tagsOf(opts),
+      optInTags: optInTagsOf(opts),
+      body: mode === "skip" || mode === "todo" ? undefined : () => wrap(eff),
+    });
+
+  const test = ((name, eff, opts) => {
+    addTest(name, eff, opts, "run");
+  }) as TestFn;
+
+  test.skip = (name, eff, opts) => addTest(name, eff, opts, "skip");
+  test.skipIf = (condition) => (name, eff, opts) =>
+    addTest(name, eff, opts, condition ? "skip" : "run");
+  test.only = (name, eff, opts) => addTest(name, eff, opts, "only");
+  test.todo = (name, eff, opts) => addTest(name, eff, opts, "todo");
+
+  // One lock per scratch stack. When an attempt times out, the runner fires
+  // an interrupt and ABANDONS the attempt's fiber after a short grace — but
+  // the fiber keeps running its teardown (`scratch.destroy()` below) in the
+  // background, e.g. a CloudFront disable-wait. Without this lock the retry
+  // starts concurrently on the SAME scratch state: the stale teardown then
+  // deletes the state rows the retry just wrote for the same logical ids,
+  // orphaning the retry's cloud resources (observed: two leaked CloudFront
+  // distributions + buckets + OACs from one retried test). Holding the lock
+  // across body + teardown makes a retry wait (on its own timeout clock)
+  // until the previous attempt's teardown has fully settled.
+  const scratchLocks = new Map<string, Semaphore.Semaphore>();
+  const scratchLock = (name: string) => {
+    let lock = scratchLocks.get(name);
+    if (lock === undefined) {
+      lock = Semaphore.makeUnsafe(1);
+      scratchLocks.set(name, lock);
+    }
+    return lock;
+  };
+
+  const wrapProvider = (
+    name: string,
+    fn: (stack: ScratchStack) => Effect.Effect<void, any, any>,
+    file: string | undefined,
+  ) => {
+    if (sharedScope === undefined) return Effect.die("Test runtime is closed");
+    // Durable, file-namespaced scratch state (`.alchemy/state`). A run that
+    // dies mid-delete — e.g. the runner abandons teardown 10s after a test
+    // timeout while a CloudFront disable-wait is still in flight — leaves
+    // its `deleting` rows on disk, so the NEXT run's leading
+    // `stack.destroy()` (or the ensuring teardown below) resumes and drains
+    // them instead of planning "no changes" and silently orphaning the
+    // cloud resource.
+    const scratch = Core.scratchStack(options, name, file);
+    // Guarantee teardown. `test.provider` has no built-in cleanup, so a body
+    // that fails (assertion, API error like a 409/Unauthorized) or is
+    // interrupted (timeout) BEFORE its trailing `stack.destroy()` would
+    // otherwise leak every cloud resource it deployed.
+    // `scratch.destroy()` is idempotent — a no-op when the body already
+    // destroyed, and it reclaims the orphans otherwise. `Effect.ensuring`
+    // runs the finalizer on success, failure, AND interruption.
+    const body = Core.withProviders(fn(scratch), options, scratch.name).pipe(
+      Effect.ensuring(scratch.destroy().pipe(Effect.ignore)),
+      scratchLock(scratch.name).withPermits(1),
+    );
+    return Core.toEffect(body, { ...options, state: scratch.state }, sharedScope, sidecar);
+  };
+
+  const addProvider = (
+    name: string,
+    fn: (stack: ScratchStack) => Effect.Effect<void, any, any>,
+    opts: TestOptions | undefined,
+    mode: "run" | "skip" | "todo",
+  ) => {
+    // Captured at registration (module evaluation during collection) — the
+    // collection context is gone by the time the body runs.
+    const file = currentFile();
+    registerTest({
+      name,
+      mode,
+      exclusive: exclusive(opts),
+      retry: retryOf(opts),
+      timeout: timeoutOf(opts),
+      tags: tagsOf(opts),
+      optInTags: optInTagsOf(opts),
+      body: mode === "run" ? () => wrapProvider(name, fn, file) : undefined,
+    });
+  };
+
+  const provider = ((name, fn, opts) => {
+    addProvider(name, fn, opts, "run");
+  }) as ProviderFn;
+  provider.skip = (name, fn, opts) => addProvider(name, fn, opts, "skip");
+  provider.skipIf = (condition) => (name, fn, opts) =>
+    addProvider(name, fn, opts, condition ? "skip" : "run");
+  provider.todo = (name, fn, opts) => addProvider(name, fn, opts, "todo");
+  test.provider = provider;
+
+  const beforeAll: BeforeAllFn = <A>(eff: TestEffect<A>, hookOptions?: TestOptions) => {
+    let result: A | undefined;
+    clearResults.add(() => {
+      result = undefined;
+    });
+    registerHook("beforeAll", {
+      body: () =>
+        wrap(eff).pipe(
+          Effect.map((value) => {
+            if (sharedScope !== undefined) result = value;
+          }),
+        ),
+      timeout: timeoutOf(hookOptions) ?? DEFAULT_TIMEOUT,
+      exclusive: exclusive(hookOptions),
+    });
+    return Effect.sync(() => result as A);
+  };
+
+  const beforeEach: BeforeEachFn = (eff, hookOptions) => {
+    registerHook("beforeEach", { body: () => wrap(eff), timeout: timeoutOf(hookOptions) });
+  };
+
+  const afterAll = ((eff, hookOptions) => {
+    registerHook("afterAll", {
+      body: () => wrap(eff),
+      timeout: timeoutOf(hookOptions) ?? DEFAULT_TIMEOUT,
+      exclusive: exclusive(hookOptions),
+    });
+  }) as AfterAllFn;
+  afterAll.skipIf = (predicate) => (eff, hookOptions) => {
+    if (predicate) return;
+    registerHook("afterAll", {
+      body: () => wrap(eff),
+      timeout: timeoutOf(hookOptions) ?? DEFAULT_TIMEOUT,
+      exclusive: exclusive(hookOptions),
+    });
+  };
+
+  const afterEach: AfterEachFn = (eff, hookOptions) => {
+    registerHook("afterEach", { body: () => wrap(eff), timeout: timeoutOf(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(() =>
+    sharedScope === undefined ? Effect.void : Scope.close(sharedScope, Exit.void),
+  ).pipe(Effect.ignore);
+
+  // File cleanup runs after user afterAll, including skipped/failed imports.
+  // Interactive retries retain the runtime until the runner releases the file.
+  registerFileCleanup({
+    body: () =>
+      closeScope.pipe(
+        Effect.ensuring(Effect.suspend(() => sidecar?.close ?? Effect.void)),
+        Effect.ensuring(
+          Effect.sync(() => {
+            sharedScope = undefined;
+            sidecar = undefined;
+            for (const clear of clearResults) clear();
+            clearResults.clear();
+          }),
+        ),
+      ),
+    timeout: DEFAULT_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),
+      ),
+  };
+};