1# DO Storage Testing
2 
3Testing Durable Objects with storage using `vitest-pool-workers`.
4 
5## Setup
6 
7**vitest.config.ts:**
8```typescript
9import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";
10 
11export default defineWorkersConfig({
12  test: {
13    poolOptions: {
14      workers: { wrangler: { configPath: "./wrangler.toml" } }
15    }
16  }
17});
18```
19 
20**package.json:** Add `@cloudflare/vitest-pool-workers` and `vitest` to devDependencies
21 
22## Basic Testing
23 
24```typescript
25import { env, runInDurableObject } from "cloudflare:test";
26import { describe, it, expect } from "vitest";
27 
28describe("Counter DO", () => {
29  it("increments counter", async () => {
30    const id = env.COUNTER.idFromName("test");
31    const result = await runInDurableObject(env.COUNTER, id, async (instance, state) => {
32      const val1 = await instance.increment();
33      const val2 = await instance.increment();
34      return { val1, val2 };
35    });
36    expect(result.val1).toBe(1);
37    expect(result.val2).toBe(2);
38  });
39});
40```
41 
42## Testing SQL Storage
43 
44```typescript
45it("creates and queries users", async () => {
46  const id = env.USER_MANAGER.idFromName("test");
47  await runInDurableObject(env.USER_MANAGER, id, async (instance, state) => {
48    await instance.createUser("[email protected]", "Alice");
49    const user = await instance.getUser("[email protected]");
50    expect(user).toEqual({ email: "[email protected]", name: "Alice" });
51  });
52});
53 
54it("handles schema migrations", async () => {
55  const id = env.USER_MANAGER.idFromName("migration-test");
56  await runInDurableObject(env.USER_MANAGER, id, async (instance, state) => {
57    const version = state.storage.sql.exec(
58      "SELECT value FROM _meta WHERE key = 'schema_version'"
59    ).one()?.value;
60    expect(version).toBe("1");
61  });
62});
63```
64 
65## Testing Alarms
66 
67```typescript
68import { runDurableObjectAlarm } from "cloudflare:test";
69 
70it("processes batch on alarm", async () => {
71  const id = env.BATCH_PROCESSOR.idFromName("test");
72  
73  // Add items
74  await runInDurableObject(env.BATCH_PROCESSOR, id, async (instance) => {
75    await instance.addItem("item1");
76    await instance.addItem("item2");
77  });
78  
79  // Trigger alarm
80  await runDurableObjectAlarm(env.BATCH_PROCESSOR, id);
81  
82  // Verify processed
83  await runInDurableObject(env.BATCH_PROCESSOR, id, async (instance, state) => {
84    const count = state.storage.sql.exec(
85      "SELECT COUNT(*) as count FROM processed_items"
86    ).one().count;
87    expect(count).toBe(2);
88  });
89});
90```
91 
92## Testing Concurrency
93 
94```typescript
95it("handles concurrent increments safely", async () => {
96  const id = env.COUNTER.idFromName("concurrent-test");
97  
98  // Parallel increments
99  const results = await Promise.all([
100    runInDurableObject(env.COUNTER, id, (i) => i.increment()),
101    runInDurableObject(env.COUNTER, id, (i) => i.increment()),
102    runInDurableObject(env.COUNTER, id, (i) => i.increment())
103  ]);
104  
105  // All should get unique values
106  expect(new Set(results).size).toBe(3);
107  expect(Math.max(...results)).toBe(3);
108});
109```
110 
111## Test Isolation
112 
113```typescript
114// Per-test unique IDs
115let testId: string;
116beforeEach(() => { testId = crypto.randomUUID(); });
117 
118it("isolated test", async () => {
119  const id = env.MY_DO.idFromName(testId);
120  // Uses unique DO instance
121});
122 
123// Cleanup pattern
124it("with cleanup", async () => {
125  const id = env.MY_DO.idFromName("cleanup-test");
126  try {
127    await runInDurableObject(env.MY_DO, id, async (instance) => {});
128  } finally {
129    await runInDurableObject(env.MY_DO, id, async (instance, state) => {
130      await state.storage.deleteAll();
131    });
132  }
133});
134```
135 
136## Testing PITR
137 
138```typescript
139it("restores from bookmark", async () => {
140  const id = env.MY_DO.idFromName("pitr-test");
141  
142  // Create checkpoint
143  const bookmark = await runInDurableObject(env.MY_DO, id, async (instance, state) => {
144    await state.storage.put("value", 1);
145    return await state.storage.getCurrentBookmark();
146  });
147  
148  // Modify and restore
149  await runInDurableObject(env.MY_DO, id, async (instance, state) => {
150    await state.storage.put("value", 2);
151    await state.storage.onNextSessionRestoreBookmark(bookmark);
152    state.abort();
153  });
154  
155  // Verify restored
156  await runInDurableObject(env.MY_DO, id, async (instance, state) => {
157    const value = await state.storage.get("value");
158    expect(value).toBe(1);
159  });
160});
161```
162 
163## Testing Transactions
164 
165```typescript
166it("rolls back on error", async () => {
167  const id = env.BANK.idFromName("transaction-test");
168  
169  await runInDurableObject(env.BANK, id, async (instance, state) => {
170    await state.storage.put("balance", 100);
171    
172    await expect(
173      state.storage.transaction(async () => {
174        await state.storage.put("balance", 50);
175        throw new Error("Cancel");
176      })
177    ).rejects.toThrow("Cancel");
178    
179    const balance = await state.storage.get("balance");
180    expect(balance).toBe(100); // Rolled back
181  });
182});
183```
184