cf-bun-mocks 0.1.0-alpha.2 → 0.2.0

package/README.md

@@ -26,12 +26,12 @@ const db = new D1Mock("./test.db");
 
 ### With Migrations
 
-Use `initD1` to create an in-memory database and run your migrations:
+Use `createD1Mock` to create an in-memory database and run your migrations:
 
 ```typescript
-import { initD1 } from "cf-bun-mocks";
+import { createD1Mock } from "cf-bun-mocks";
 
-const db = await initD1("./migrations");
+const db = await createD1Mock("./migrations");
 ```
 
 This reads all `.sql` files from the migrations directory in sorted order and executes them.
@@ -107,30 +107,79 @@ const env: Env = {
 const response = await worker.fetch(request, env);
 ```
 
-## Environment Mock
+## Workers Environment
 
-Use `useEnv` to mock `cloudflare:env` imports in your tests:
+For testing Cloudflare Workers, use the `useWorkersEnv` helper to create test environments:
 
 ```typescript
 import { describe, test, expect } from "bun:test";
-import { useEnv, D1Mock } from "cf-bun-mocks";
+import { useWorkersEnv, D1Mock } from "cf-bun-mocks";
 import type { Env } from "./worker";
 
 describe("my worker", () => {
-  useEnv<Env>(async () => ({
+  const { env } = useWorkersEnv<Env>(() => ({
     DB: new D1Mock(":memory:"),
     MY_SECRET: "test-secret",
   }));
 
-  test("uses mocked env", async () => {
-    // Your worker code that imports from "cloudflare:env" will get the mock
-    const { myFunction } = await import("./worker");
-    const result = await myFunction();
-    expect(result).toBeDefined();
+  test("uses test environment", async () => {
+    // Pass the env to your worker handler
+    const response = await worker.fetch(request, env);
+    expect(response.status).toBe(200);
   });
 });
 ```
 
+### Module Mocking (Advanced)
+
+For mocking `cloudflare:workers` module imports, use `setupWorkersMock` in a preload script and combine it with `useWorkersEnv`:
+
+Create a `test-setup.ts` file:
+
+```typescript
+// test-setup.ts
+import { setupWorkersMock } from "cf-bun-mocks";
+
+// Set up module mocks before any test files load
+await setupWorkersMock();
+```
+
+Then run tests with preload:
+
+```bash
+bun test --preload ./test-setup.ts
+```
+
+Or configure it in `bunfig.toml`:
+
+```toml
+[test]
+preload = ["./test-setup.ts"]
+```
+
+Then use in your tests:
+
+```typescript
+import { describe, test, expect } from "bun:test";
+import { useWorkersEnv, D1Mock } from "cf-bun-mocks";
+
+describe("worker with module imports", () => {
+  useWorkersEnv(() => ({
+    DB: new D1Mock(":memory:"),
+    API_KEY: "test-key",
+  }));
+
+  test("uses mocked module", async () => {
+    // The env object reference stays the same, only properties change
+    const { env } = await import("cloudflare:workers");
+    expect(env.DB).toBeDefined();
+    expect(env.API_KEY).toBe("test-key");
+  });
+});
+```
+
+> **Note**: `setupWorkersMock` uses Bun's `mock.module()` function. Module mocks must be set up before any imports happen. See [Bun's test lifecycle docs](https://bun.com/docs/test/lifecycle#global-setup-and-teardown) for preload details and [Bun's mocking docs](https://bun.sh/docs/test/mocking) for more on module mocking.
+
 ## API
 
 ### `D1Mock`
@@ -139,17 +188,21 @@ Implements the full `D1Database` interface from `@cloudflare/workers-types`:
 
 - `prepare(query: string)` - Create a prepared statement
 - `batch(statements: D1PreparedStatement[])` - Execute multiple statements
-- `exec(query: string)` - Execute raw SQL
+- `exec(query: string)` - Execute raw SQL (supports multiple statements)
 - `dump()` - Serialize the database to an ArrayBuffer
 - `withSession(constraint?)` - Get a session (bookmark tracking is stubbed)
 
-### `initD1(migrationsPath: string)`
+### `createD1Mock(migrationsPath: string)`
+
+Creates an in-memory D1Mock and runs all `.sql` migration files from the specified directory in sorted order.
+
+### `useWorkersEnv<TEnv>(createEnv: () => Partial<TEnv> | Promise<Partial<TEnv>>)`
 
-Creates an in-memory D1Mock and runs all `.sql` files from the specified directory.
+Updates the global workers mock environment for each test. Must be used with `setupWorkersMock()`.
 
-### `useEnv<TEnv>(setup: () => TEnv | Promise<TEnv>)`
+### `setupWorkersMock<TEnv>(createMock?: () => WorkersModuleMock<TEnv> | Promise<WorkersModuleMock<TEnv>>)`
 
-Registers `beforeEach`/`afterEach` hooks to mock `cloudflare:env` for each test. Call at the top of your `describe` block.
+Sets up the `cloudflare:workers` module mock using Bun's `mock.module()`. **Must be called in a preload script before any test files load.** Use Bun's `--preload` flag or configure it in `bunfig.toml`. Call once at the start of your test suite, then use `useWorkersEnv()` to update the environment per test.
 
 ## Requirements
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cf-bun-mocks",
-  "version": "0.1.0-alpha.2",
+  "version": "0.2.0",
   "description": "Cloudflare Workers mocks and helpers for Bun testing",
   "type": "module",
   "main": "src/index.ts",
@@ -15,9 +15,9 @@
       "import": "./src/d1.ts",
       "types": "./src/d1.ts"
     },
-    "./env": {
-      "import": "./src/env.ts",
-      "types": "./src/env.ts"
+    "./workers": {
+      "import": "./src/workers.ts",
+      "types": "./src/workers.ts"
     }
   },
   "files": [

package/src/d1.ts

@@ -147,12 +147,20 @@ export class D1Mock implements D1Database {
 
   async exec(query: string): Promise<D1ExecResult> {
     const start = performance.now();
-    const { changes: count } = this.#db.run(query);
-    const duration = performance.now() - start;
-    return {
-      count,
-      duration,
-    };
+    try {
+      const { changes: count } = this.#db.run(query);
+      const duration = performance.now() - start;
+      return {
+        count,
+        duration,
+      };
+    } catch (error) {
+      throw new Error(
+        `D1Mock exec failed: ${
+          error instanceof Error ? error.message : String(error)
+        }\nQuery: ${query}`
+      );
+    }
   }
 
   withSession(
@@ -173,14 +181,22 @@ export class D1Mock implements D1Database {
   }
 }
 
-export async function initD1(migrationsPath: string): Promise<D1Mock> {
+export async function createD1Mock(migrationsPath: string): Promise<D1Mock> {
   const files = readdirSync(migrationsPath)
     .filter((file) => file.endsWith(".sql"))
     .sort();
   const db = new D1Mock(":memory:");
   for (const file of files) {
     const migration = await Bun.file(path.join(migrationsPath, file)).text();
-    await db.exec(migration);
+    try {
+      await db.exec(migration);
+    } catch (error) {
+      throw new Error(
+        `Failed to execute migration ${file}: ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+    }
   }
   return db;
 }

package/src/index.ts

@@ -1,2 +1,2 @@
 export * from "./d1.ts";
-export * from "./env.ts";
+export * from "./workers.ts";

package/src/workers.ts

@@ -0,0 +1,33 @@
+/// <reference types="@cloudflare/workers-types" />
+import { beforeEach, mock, afterAll } from "bun:test";
+
+type WorkersModuleMock<TEnv extends Cloudflare.Env = Cloudflare.Env> = {
+  env: Partial<TEnv>;
+};
+
+let moduleMock: WorkersModuleMock = { env: {} };
+
+export async function setupWorkersMock<
+  TEnv extends Cloudflare.Env = Cloudflare.Env
+>(createMock?: () => Bun.MaybePromise<WorkersModuleMock<TEnv>>) {
+  if (createMock) {
+    moduleMock = await createMock();
+  }
+  mock.module("cloudflare:workers", () => moduleMock);
+}
+
+export function useWorkersEnv<TEnv extends Cloudflare.Env = Cloudflare.Env>(
+  createEnv: () => Bun.MaybePromise<Partial<TEnv>>
+) {
+  beforeEach(async () => {
+    const env = await createEnv();
+    for (const key in moduleMock.env) {
+      delete (moduleMock.env as any)[key];
+    }
+    Object.assign(moduleMock.env, env);
+  });
+
+  afterAll(() => {
+    moduleMock.env = {};
+  });
+}

package/src/env.ts

@@ -1,17 +0,0 @@
-/// <reference types="@cloudflare/workers-types" />
-import { beforeEach, afterEach, mock } from "bun:test";
-
-const MODULE_NAME = "cloudflare:workers";
-
-export function useEnv<TEnv extends Cloudflare.Env = Cloudflare.Env>(
-  setup: () => Bun.MaybePromise<Partial<TEnv>>
-) {
-  beforeEach(async () => {
-    const env = await setup();
-    mock.module(MODULE_NAME, () => env);
-  });
-
-  afterEach(() => {
-    mock.module(MODULE_NAME, () => {});
-  });
-}