1# Testing Patterns
2 
3## Choosing a Testing Approach
4 
5| Approach | Use Case | Speed | Setup | Runtime |
6|----------|----------|-------|-------|---------|
7| **getPlatformProxy** | Unit tests, logic testing | Fast | Low | Miniflare |
8| **Miniflare API** | Integration tests, full control | Medium | Medium | Miniflare |
9| **vitest-pool-workers** | Vitest runner integration | Medium | Medium | workerd |
10 
11**Quick guide:**
12- Unit tests → getPlatformProxy
13- Integration tests → Miniflare API
14- Vitest workflows → vitest-pool-workers
15 
16## getPlatformProxy
17 
18Lightweight unit testing - provides bindings without full Worker runtime.
19 
20```js
21// vitest.config.js
22export default { test: { environment: "node" } };
23```
24 
25```js
26import { env } from "cloudflare:test";
27import { describe, it, expect } from "vitest";
28 
29describe("Business logic", () => {
30  it("processes data with KV", async () => {
31    await env.KV.put("test", "value");
32    expect(await env.KV.get("test")).toBe("value");
33  });
34});
35```
36 
37**Pros:** Fast, simple  
38**Cons:** No full runtime, can't test fetch handler
39 
40## vitest-pool-workers
41 
42Full Workers runtime in Vitest. Reads `wrangler.toml`.
43 
44```bash
45npm i -D @cloudflare/vitest-pool-workers
46```
47 
48```js
49// vitest.config.js
50import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";
51 
52export default defineWorkersConfig({
53  test: {
54    poolOptions: { workers: { wrangler: { configPath: "./wrangler.toml" } } },
55  },
56});
57```
58 
59```js
60import { env, SELF } from "cloudflare:test";
61import { it, expect } from "vitest";
62 
63it("handles fetch", async () => {
64  const res = await SELF.fetch("http://example.com/");
65  expect(res.status).toBe(200);
66});
67```
68 
69**Pros:** Full runtime, uses wrangler.toml  
70**Cons:** Requires Wrangler config
71 
72## Miniflare API (node:test)
73 
74```js
75import assert from "node:assert";
76import test, { after, before } from "node:test";
77import { Miniflare } from "miniflare";
78 
79let mf;
80before(() => {
81  mf = new Miniflare({ scriptPath: "src/index.js", kvNamespaces: ["TEST_KV"] });
82});
83 
84test("fetch", async () => {
85  const res = await mf.dispatchFetch("http://localhost/");
86  assert.strictEqual(await res.text(), "Hello");
87});
88 
89after(() => mf.dispose());
90```
91 
92## Testing Durable Objects & Events
93 
94```js
95// Durable Objects
96const ns = await mf.getDurableObjectNamespace("COUNTER");
97const stub = ns.get(ns.idFromName("test-counter"));
98await stub.fetch("http://localhost/increment");
99 
100// Direct storage
101const storage = await mf.getDurableObjectStorage(ns.idFromName("test-counter"));
102const count = await storage.get("count");
103 
104// Queue
105const worker = await mf.getWorker();
106await worker.queue("my-queue", [
107  { id: "msg1", timestamp: new Date(), body: { userId: 123 }, attempts: 1 },
108]);
109 
110// Scheduled
111await worker.scheduled({ cron: "0 0 * * *" });
112```
113 
114## Test Isolation & Mocking
115 
116```js
117// Per-test isolation
118beforeEach(() => { mf = new Miniflare({ kvNamespaces: ["TEST"] }); });
119afterEach(() => mf.dispose());
120 
121// Mock external APIs
122new Miniflare({
123  workers: [
124    { name: "main", serviceBindings: { API: "mock-api" }, script: `...` },
125    { name: "mock-api", script: `export default { async fetch() { return Response.json({mock: true}); } }` },
126  ],
127});
128```
129 
130## Type Safety
131 
132```ts
133import type { KVNamespace } from "@cloudflare/workers-types";
134 
135interface Env {
136  KV: KVNamespace;
137  API_KEY: string;
138}
139 
140const env = await mf.getBindings<Env>();
141await env.KV.put("key", "value"); // Typed!
142 
143export default {
144  async fetch(req: Request, env: Env) {
145    return new Response(await env.KV.get("key"));
146  }
147} satisfies ExportedHandler<Env>;
148```
149 
150## WebSocket Testing
151 
152```js
153const res = await mf.dispatchFetch("http://localhost/ws", {
154  headers: { Upgrade: "websocket" },
155});
156assert.strictEqual(res.status, 101);
157```
158 
159## Migration from unstable_dev
160 
161```js
162// Old (deprecated)
163import { unstable_dev } from "wrangler";
164const worker = await unstable_dev("src/index.ts");
165 
166// New
167import { Miniflare } from "miniflare";
168const mf = new Miniflare({ scriptPath: "src/index.ts" });
169```
170 
171## CI/CD Tips
172 
173```js
174// In-memory storage (faster)
175new Miniflare({ kvNamespaces: ["TEST"] }); // No persist = in-memory
176 
177// Use dispatchFetch (no port conflicts)
178await mf.dispatchFetch("http://localhost/");
179```
180 
181See [gotchas.md](./gotchas.md) for troubleshooting.
182