@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
mdx 248 lines 7.15 KB
Raw
1 ---
2 title: "Part 3: Testing"
3 description: Write integration tests that deploy your stack and make HTTP requests against your live Worker.
4 sidebar:
5 order: 3
6 ---
7
8 In [Part 2](/cloudflare/tutorial/part-2) you deployed a Worker with R2 Bucket
9 bindings. Now you'll write integration tests that deploy the stack,
10 hit the live Worker over HTTP, and verify it works.
11
12 ## Install the test harness
13
14 `Test.make` ships in `@alchemy.run/test`. Add it as a dev dependency:
15
16 ```sh
17 bun add -d @alchemy.run/test
18 ```
19
20 ## Create the test file
21
22 Alchemy ships test utilities for Bun that wrap `bun:test` with Effect
23 support. Configure providers (and state) once at the top of the file
24 with `Test.make({...})` — the same `Cloudflare.providers()` /
25 `Cloudflare.state()` you used in your `Stack`:
26
27 ```typescript
28 // test/integ.test.ts
29 import * as Cloudflare from "@alchemy.run/cloudflare";
30 import * as Test from "@alchemy.run/test/Bun";
31 import { expect } from "bun:test";
32 import * as Effect from "effect/Effect";
33 import Stack from "../alchemy.run.ts";
34
35 const { test, beforeAll, afterAll, deploy, destroy } = Test.make({
36 providers: Cloudflare.providers(),
37 state: Cloudflare.state(),
38 });
39 ```
40
41 `expect` (and any other `bun:test` helpers like `describe`) come
42 from `bun:test` directly — `Test.make` only provides the
43 Effect-aware test runner pieces.
44
45 ## Deploy the stack before tests
46
47 Use `beforeAll` with `deploy` to deploy your stack once before any
48 tests run:
49
50 ```diff lang="typescript"
51 // test/integ.test.ts
52 import * as Cloudflare from "@alchemy.run/cloudflare";
53 import * as Test from "@alchemy.run/test/Bun";
54 import { expect } from "bun:test";
55 import * as Effect from "effect/Effect";
56 import Stack from "../alchemy.run.ts";
57
58 const { test, beforeAll, afterAll, deploy, destroy } = Test.make({
59 providers: Cloudflare.providers(),
60 state: Cloudflare.state(),
61 });
62
63 +const stack = beforeAll(deploy(Stack));
64 ```
65
66 `deploy(Stack)` returns an Effect that plans and applies the stack.
67 `beforeAll` runs it once, then returns a lazy accessor you can
68 `yield*` inside each test to get the stack outputs.
69
70 ## Access the stack outputs
71
72 Write your first test. Use `yield* stack` to get the outputs you
73 returned from your Stack in Part 2:
74
75 ```diff lang="typescript"
76 // test/integ.test.ts
77 import * as Cloudflare from "@alchemy.run/cloudflare";
78 import * as Test from "@alchemy.run/test/Bun";
79 import { expect } from "bun:test";
80 import * as Effect from "effect/Effect";
81 import Stack from "../alchemy.run.ts";
82
83 const { test, beforeAll, afterAll, deploy, destroy } = Test.make({
84 providers: Cloudflare.providers(),
85 state: Cloudflare.state(),
86 });
87
88 const stack = beforeAll(deploy(Stack));
89
90 +test(
91 + "worker returns a url",
92 + Effect.gen(function* () {
93 + const { url } = yield* stack;
94 +
95 + expect(url).toBeString();
96 + }),
97 +);
98 ```
99
100 `test(name, effect)` wraps `bun:test` — you write an Effect generator
101 instead of an async function.
102
103 ## Run the tests
104
105 ```sh
106 bun test test/integ.test.ts
107 ```
108
109 The first run deploys the stack (or reuses the existing one if
110 already deployed). Subsequent runs are fast because Alchemy diffs
111 and skips unchanged resources.
112
113 ## Add HTTP assertions
114
115 The basic test just checks that a URL exists. Let's verify the Worker
116 actually handles requests:
117
118 ```diff lang="typescript"
119 // test/integ.test.ts
120 import * as Cloudflare from "@alchemy.run/cloudflare";
121 import * as Test from "@alchemy.run/test/Bun";
122 import { expect } from "bun:test";
123 import * as Effect from "effect/Effect";
124 +import * as HttpBody from "effect/http/HttpBody";
125 +import * as HttpClient from "effect/http/HttpClient";
126 import Stack from "../alchemy.run.ts";
127
128 const { test, beforeAll, afterAll, deploy, destroy } = Test.make({
129 providers: Cloudflare.providers(),
130 state: Cloudflare.state(),
131 });
132
133 const stack = beforeAll(deploy(Stack));
134
135 -test(
136 - "worker returns a url",
137 - Effect.gen(function* () {
138 - const { url } = yield* stack;
139 -
140 - expect(url).toBeString();
141 - }),
142 -);
143 +test(
144 + "PUT and GET round-trip an object",
145 + Effect.gen(function* () {
146 + const { url } = yield* stack;
147 +
148 + const put = yield* HttpClient.put(`${url}/hello.txt`, {
149 + body: HttpBody.text("Hello, World!"),
150 + });
151 + expect(put.status).toBe(201);
152 +
153 + const get = yield* HttpClient.get(`${url}/hello.txt`);
154 + expect(yield* get.text).toBe("Hello, World!");
155 + }),
156 +);
157 +
158 +test(
159 + "GET missing key returns 404",
160 + Effect.gen(function* () {
161 + const { url } = yield* stack;
162 + const response = yield* HttpClient.get(`${url}/no-such-key`);
163 + expect(response.status).toBe(404);
164 + }),
165 +);
166 ```
167
168 `HttpClient` is provided automatically by the test harness — no
169 extra setup needed.
170
171 ## Allow the Bucket to be destroyed with objects in it
172
173 The PUT test writes `hello.txt` into the Bucket, so the Bucket is no
174 longer empty when the tests finish. R2 refuses to delete a Bucket
175 that still contains objects, and Alchemy keeps that protection by
176 default: destroying a non-empty Bucket fails with `BucketNotEmpty` and
177 leaves the Bucket and its objects in place.
178
179 This Bucket only ever holds test data, so opt in to deleting its
180 objects on destroy with `forceDestroy: true`:
181
182 ```diff lang="typescript"
183 // src/bucket.ts
184 import * as Cloudflare from "@alchemy.run/cloudflare";
185
186 -export const Bucket = Cloudflare.R2.Bucket("Bucket");
187 +export const Bucket = Cloudflare.R2.Bucket("Bucket", {
188 + forceDestroy: true,
189 +});
190 ```
191
192 With `forceDestroy: true`, Alchemy empties the Bucket before deleting
193 it. Reserve it for Buckets whose contents are disposable (test
194 fixtures, caches, previews); leave it off for Buckets that hold data
195 you need to keep.
196
197 ## Destroy after tests on CI
198
199 Right now the stack stays deployed after tests finish. That's great
200 locally — you can re-run tests instantly against the already-deployed
201 stack. But on CI you want to clean up.
202
203 Add `afterAll` with `destroy`, using `skipIf` to only tear down when
204 `CI` is set:
205
206 ```diff lang="typescript"
207 import * as Cloudflare from "@alchemy.run/cloudflare";
208 import * as Test from "@alchemy.run/test/Bun";
209 import { expect } from "bun:test";
210 import * as Effect from "effect/Effect";
211 import * as HttpBody from "effect/http/HttpBody";
212 import * as HttpClient from "effect/http/HttpClient";
213 import Stack from "../alchemy.run.ts";
214
215 const { test, beforeAll, afterAll, deploy, destroy } = Test.make({
216 providers: Cloudflare.providers(),
217 state: Cloudflare.state(),
218 });
219
220 const stack = beforeAll(deploy(Stack));
221
222 +afterAll.skipIf(!process.env.CI)(destroy(Stack));
223
224 test(/* .. */);
225
226 test(/* .. */);
227 ```
228
229 - **Locally** — `CI` is not set, so `skipIf` skips the destroy. You
230 iterate fast against the live stack.
231 - **On CI** — set `CI=true` and the stack is torn down automatically
232 after tests complete.
233
234 ## Recap
235
236 You now have:
237
238 - `Test.make({ providers, state })` to wire your provider Layer and
239 state store into the test runner once per file
240 - `beforeAll(deploy(Stack))` to deploy once before tests
241 - `yield* stack` to access outputs in each test
242 - HTTP assertions using Effect's `HttpClient`
243 - `forceDestroy: true` so destroy can delete a Bucket that tests wrote to
244 - `afterAll.skipIf(!process.env.CI)(destroy(Stack))` for automatic
245 cleanup on CI with fast iteration locally
246
247 In [Part 4](/cloudflare/tutorial/part-4), you'll run your stack locally with
248 `alchemy dev` for instant feedback during development.