@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.21 KB
Raw
1 ---
2 title: "Part 3: Testing"
3 description: Write integration tests that deploy your stack and make HTTP requests against your live Lambda Function URL.
4 sidebar:
5 order: 3
6 ---
7
8 In [Part 2](/aws/tutorial/part-2) you deployed a Lambda with S3
9 bindings. Now you'll write integration tests that deploy the stack,
10 hit the live Function URL 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 `AWS.providers()` / `AWS.state()`
25 you used in your `Stack`:
26
27 ```typescript
28 // test/integ.test.ts
29 import * as AWS from "@alchemy.run/aws";
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: AWS.providers(),
37 state: AWS.state(),
38 });
39 ```
40
41 `expect` (and any other `bun:test` helpers like `describe`) come from
42 `bun:test` directly — `Test.make` only provides the Effect-aware test
43 runner pieces.
44
45 :::note[Using Vitest or alchemy-test?]
46 `@alchemy.run/test/Vitest` and `@alchemy.run/test/Alchemy` expose the exact same
47 API — swap the import and take `expect` from `@effect/vitest` or
48 `@alchemy.run/test` instead. See
49 [Test harness → Runners](/testing/test-harness#runners).
50 :::
51
52 ## Deploy the stack before tests
53
54 Use `beforeAll` with `deploy` to deploy your stack once before any
55 tests run:
56
57 ```diff lang="typescript"
58 const { test, beforeAll, afterAll, deploy, destroy } = Test.make({
59 providers: AWS.providers(),
60 state: AWS.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 const stack = beforeAll(deploy(Stack));
77
78 +test(
79 + "stack exposes a function url",
80 + Effect.gen(function* () {
81 + const { url } = yield* stack;
82 +
83 + expect(url).toBeString();
84 + }),
85 +);
86 ```
87
88 `test(name, effect)` wraps `bun:test` — you write an Effect generator
89 instead of an async function.
90
91 ## Run the tests
92
93 ```sh
94 bun test test/integ.test.ts
95 ```
96
97 The first run deploys the stack (or reuses the existing one if
98 already deployed). Subsequent runs are fast because Alchemy diffs and
99 skips unchanged resources.
100
101 :::note[Which stage do tests deploy to?]
102 The test harness defaults to `test_$USER` (e.g. `test_sam`),
103 separate from the `live_$USER` / `dev_$USER` stages your
104 `alchemy deploy` / `alchemy dev` runs target — so tests never
105 clobber your working deployment, and two people running the suite
106 don't collide. More on stages in [Part 4](/aws/tutorial/part-4).
107 :::
108
109 ## Add HTTP assertions
110
111 The basic test just checks that a URL exists. Let's verify the
112 function actually handles requests:
113
114 ```diff lang="typescript"
115 // test/integ.test.ts
116 import * as AWS from "@alchemy.run/aws";
117 import * as Test from "@alchemy.run/test/Bun";
118 import { expect } from "bun:test";
119 import * as Effect from "effect/Effect";
120 +import * as HttpBody from "effect/http/HttpBody";
121 +import * as HttpClient from "effect/http/HttpClient";
122 import Stack from "../alchemy.run.ts";
123
124 const { test, beforeAll, afterAll, deploy, destroy } = Test.make({
125 providers: AWS.providers(),
126 state: AWS.state(),
127 });
128
129 const stack = beforeAll(deploy(Stack));
130
131 -test(
132 - "stack exposes a function url",
133 - Effect.gen(function* () {
134 - const { url } = yield* stack;
135 -
136 - expect(url).toBeString();
137 - }),
138 -);
139 +test(
140 + "PUT and GET round-trip an object",
141 + Effect.gen(function* () {
142 + const { url } = yield* stack;
143 +
144 + const put = yield* HttpClient.put(`${url}/hello.txt`, {
145 + body: HttpBody.text("Hello, World!"),
146 + });
147 + expect(put.status).toBe(204);
148 +
149 + const get = yield* HttpClient.get(`${url}/hello.txt`);
150 + expect(yield* get.text).toBe("Hello, World!");
151 + }),
152 +);
153 +
154 +test(
155 + "GET missing key returns 404",
156 + Effect.gen(function* () {
157 + const { url } = yield* stack;
158 + const response = yield* HttpClient.get(`${url}/no-such-key`);
159 + expect(response.status).toBe(404);
160 + }),
161 +);
162 ```
163
164 `HttpClient` is provided automatically by the test harness — no extra
165 setup needed.
166
167 :::tip[Cold starts]
168 A freshly created Function URL can take a few seconds before it
169 serves its first request — DNS propagation, IAM propagation, and the
170 function's own cold start all stack up. If the very first request in
171 a fresh stage flakes, retry it with a bounded schedule:
172
173 ```typescript
174 import * as Schedule from "effect/Schedule";
175
176 const get = yield* HttpClient.get(`${url}/hello.txt`).pipe(
177 Effect.retry({ schedule: Schedule.exponential("500 millis"), times: 10 }),
178 );
179 ```
180 :::
181
182 ## Allow the Bucket to be destroyed with objects in it
183
184 The PUT test writes `hello.txt` into the Bucket, so the Bucket is no
185 longer empty when the tests finish. S3 refuses to delete a Bucket
186 that still contains objects, and Alchemy keeps that protection by
187 default: destroying a non-empty Bucket fails with `BucketNotEmpty` and
188 leaves the Bucket and its objects in place.
189
190 This Bucket only ever holds test data, so opt in to deleting its
191 objects on destroy with `forceDestroy: true`:
192
193 ```diff lang="typescript"
194 // src/api.ts
195 Effect.gen(function* () {
196 - const bucket = yield* S3.Bucket("Bucket");
197 + const bucket = yield* S3.Bucket("Bucket", {
198 + forceDestroy: true,
199 + });
200 const putObject = yield* S3.PutObject(bucket);
201 const getObject = yield* S3.GetObject(bucket);
202 ```
203
204 With `forceDestroy: true`, Alchemy empties the Bucket before deleting
205 it. Reserve it for Buckets whose contents are disposable (test
206 fixtures, caches, previews); leave it off for Buckets that hold data
207 you need to keep.
208
209 ## Destroy after tests on CI
210
211 Right now the stack stays deployed after tests finish. That's great
212 locally — you can re-run tests instantly against the already-deployed
213 stack. But on CI you want to clean up.
214
215 Add `afterAll` with `destroy`, using `skipIf` to only tear down when
216 `CI` is set:
217
218 ```diff lang="typescript"
219 const stack = beforeAll(deploy(Stack));
220
221 +afterAll.skipIf(!process.env.CI)(destroy(Stack));
222
223 test(/* .. */);
224
225 test(/* .. */);
226 ```
227
228 - **Locally** — `CI` is not set, so `skipIf` skips the destroy. You
229 iterate fast against the live stack.
230 - **On CI** — set `CI=true` and the stack is torn down automatically
231 after tests complete.
232
233 ## Recap
234
235 You now have:
236
237 - `Test.make({ providers, state })` to wire your provider Layer and
238 state store into the test runner once per file
239 - `beforeAll(deploy(Stack))` to deploy once before tests
240 - `yield* stack` to access outputs in each test
241 - HTTP assertions using Effect's `HttpClient`
242 - `forceDestroy: true` so destroy can delete a Bucket that tests wrote to
243 - `afterAll.skipIf(!process.env.CI)(destroy(Stack))` for automatic
244 cleanup on CI with fast iteration locally
245
246 In [Part 4](/aws/tutorial/part-4), you'll use stages to give every
247 developer, environment, and pull request its own isolated copy of the
248 stack.