The best way to control Claude Code, Codex and more from any computer or phone
| 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. |