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
| 1 | --- |
| 2 | title: Testing a Stack |
| 3 | description: Deploy your real Stack once per suite, drive it over HTTP, tear it down. |
| 4 | --- |
| 5 | |
| 6 | This is the end-to-end pattern for integration-testing a deployed Stack against the real cloud: deploy once in `beforeAll`, drive the live URL from Effect-aware tests, destroy (or don't) in `afterAll`. The harness API is documented at [Test harness](/testing/test-harness), the model at [Testing](/testing), and the cloud-specific step-by-steps are [Cloudflare Tutorial Part 3](/cloudflare/tutorial/part-3) and [AWS Tutorial Part 3](/aws/tutorial/part-3). |
| 7 | |
| 8 | ## Set up the harness |
| 9 | |
| 10 | Configure Providers and state once per file — `Test.make` returns everything the file needs: |
| 11 | |
| 12 | ```typescript |
| 13 | import * as Alchemy from "alchemy"; |
| 14 | import * as Cloudflare from "@alchemy.run/cloudflare"; |
| 15 | import * as Drizzle from "@alchemy.run/drizzle"; |
| 16 | import * as Neon from "@alchemy.run/neon"; |
| 17 | import * as Test from "@alchemy.run/test/Bun"; |
| 18 | import { expect } from "bun:test"; |
| 19 | import * as Effect from "effect/Effect"; |
| 20 | import * as Layer from "effect/Layer"; |
| 21 | import Stack from "../alchemy.run.ts"; |
| 22 | |
| 23 | const { test, beforeAll, afterAll, deploy, destroy } = Test.make({ |
| 24 | providers: Layer.mergeAll( |
| 25 | Cloudflare.providers(), |
| 26 | Drizzle.providers(), |
| 27 | Neon.providers(), |
| 28 | ), |
| 29 | state: Alchemy.localState(), |
| 30 | }); |
| 31 | ``` |
| 32 | |
| 33 | Switching to `alchemy-test` or Vitest is a two-line import swap — see [Runners](/testing/test-harness#runners). |
| 34 | |
| 35 | ## Deploy once with beforeAll |
| 36 | |
| 37 | `beforeAll(deploy(Stack))` deploys once for the whole file and returns a lazy accessor every test can `yield*`: |
| 38 | |
| 39 | ```typescript |
| 40 | const stack = beforeAll(deploy(Stack)); |
| 41 | |
| 42 | test( |
| 43 | "worker returns a url", |
| 44 | Effect.gen(function* () { |
| 45 | const { url } = yield* stack; |
| 46 | |
| 47 | expect(url).toBeString(); |
| 48 | }), |
| 49 | ); |
| 50 | ``` |
| 51 | |
| 52 | The default hook timeout is 120s — give slow stacks more room: |
| 53 | |
| 54 | ```typescript |
| 55 | // This stack deploys a Container whose image build + push can take |
| 56 | // well over the default 120s hook budget. |
| 57 | const stack = beforeAll(deploy(Stack), { timeout: 600_000 }); |
| 58 | ``` |
| 59 | |
| 60 | `beforeAll` accessors compose — seed data in a second `beforeAll` that tests `yield*` alongside the stack; see [Hooks](/testing/test-harness#hooks). |
| 61 | |
| 62 | ## Run it |
| 63 | |
| 64 | Run the suite with your runner: |
| 65 | |
| 66 | ```sh |
| 67 | bun test test/integ.test.ts # @alchemy.run/test/Bun |
| 68 | bunx alchemy-test test/integ.test.ts # @alchemy.run/test/Alchemy |
| 69 | npx vitest run test/integ.test.ts # @alchemy.run/test/Vitest |
| 70 | ``` |
| 71 | |
| 72 | The first run deploys; re-runs diff and skip unchanged Resources, and tests default to the isolated `test_$USER` [stage](/environments/stages) so they never clobber your `live_$USER` / `dev_$USER` deployments. |
| 73 | |
| 74 | ## Run it locally with dev mode |
| 75 | |
| 76 | The same suite can run entirely on your machine. `dev: true` gives the file [`alchemy dev`](/environments/local-development) semantics — Workers, Durable Objects, KV, R2, D1, Queues, and Workflows run in workerd, AWS Lambda and its emulated services run in Docker — so `deploy(Stack)` boots local simulators and the `url` output points at `http://localhost:<port>`: |
| 77 | |
| 78 | ```typescript |
| 79 | const { test, beforeAll, afterAll, deploy, destroy } = Test.make({ |
| 80 | providers: Cloudflare.providers(), |
| 81 | dev: true, |
| 82 | }); |
| 83 | ``` |
| 84 | |
| 85 | Every assertion below works unchanged against the local stack. To keep one file that runs locally on your laptop and live in CI, omit the flag and set `ALCHEMY_DEV=1` in your shell instead — see [Test harness → dev](/testing/test-harness#dev) for the full semantics and [Tutorial Part 4](/cloudflare/tutorial/part-4) for the walkthrough. |
| 86 | |
| 87 | ## Drive the live URL |
| 88 | |
| 89 | `HttpClient` is already in scope in every test Effect: |
| 90 | |
| 91 | ```typescript |
| 92 | import * as HttpBody from "effect/http/HttpBody"; |
| 93 | import * as HttpClient from "effect/http/HttpClient"; |
| 94 | |
| 95 | test( |
| 96 | "PUT and GET round-trip an object", |
| 97 | Effect.gen(function* () { |
| 98 | const { url } = yield* stack; |
| 99 | |
| 100 | const put = yield* HttpClient.put(`${url}/hello.txt`, { |
| 101 | body: HttpBody.text("Hello, World!"), |
| 102 | }); |
| 103 | expect(put.status).toBe(201); |
| 104 | |
| 105 | const get = yield* HttpClient.get(`${url}/hello.txt`); |
| 106 | expect(yield* get.text).toBe("Hello, World!"); |
| 107 | }), |
| 108 | ); |
| 109 | ``` |
| 110 | |
| 111 | How the client is wired is covered in [Test harness](/testing/test-harness#httpclient-is-in-scope). |
| 112 | |
| 113 | ## Retry the first request |
| 114 | |
| 115 | Fresh `workers.dev` URLs and Lambda Function URLs transiently 404/5xx while routes, bindings, DNS, and IAM propagate — ride out the cold-start window on the first request of each test: |
| 116 | |
| 117 | ```typescript |
| 118 | const { getWhenReady } = Test; |
| 119 | |
| 120 | test( |
| 121 | "worker answers once the edge converges", |
| 122 | Effect.gen(function* () { |
| 123 | const { url } = yield* stack; |
| 124 | |
| 125 | const response = yield* getWhenReady(url); |
| 126 | expect(response.status).toBe(200); |
| 127 | }), |
| 128 | ); |
| 129 | ``` |
| 130 | |
| 131 | `getWhenReady` (and `executeWhenReady` for arbitrary requests) retries only 404/5xx — 20 attempts by default, exponential from 500ms — so deliberate `400`/`401`/`403` assertions observe those statuses immediately. For arbitrary effects, use a bounded manual retry: |
| 132 | |
| 133 | ```typescript |
| 134 | import * as Schedule from "effect/Schedule"; |
| 135 | |
| 136 | const response = yield* HttpClient.get(`${url}/health`).pipe( |
| 137 | Effect.retry({ schedule: Schedule.exponential("500 millis"), times: 10 }), |
| 138 | ); |
| 139 | ``` |
| 140 | |
| 141 | A Cloudflare Durable Object that stayed busy through a redeploy can answer with the old code for up to 5 minutes. Deploy test stages with `codeUpdateStrategy: { mode: "immediate" }`, or address a new object in each test. See [Tests can see the old code](/cloudflare/compute/code-updates#tests-can-see-the-old-code). |
| 142 | |
| 143 | ## Poll async effects |
| 144 | |
| 145 | Queues drain, workflows complete, and crons fire asynchronously — poll with a bounded declarative schedule, never a deadline loop: |
| 146 | |
| 147 | ```typescript |
| 148 | const status = yield* HttpClient.get(`${url}/workflow/status/${instanceId}`).pipe( |
| 149 | Effect.flatMap((res) => res.json), |
| 150 | Effect.map((body) => body as { status: string }), |
| 151 | Effect.repeat({ |
| 152 | schedule: Schedule.spaced("2 seconds"), |
| 153 | until: (s) => s.status === "complete", |
| 154 | times: 30, |
| 155 | }), |
| 156 | ); |
| 157 | ``` |
| 158 | |
| 159 | Bounded `times` fails fast instead of leaking into the runner timeout; `while (Date.now() < deadline)` loops ignore interruption. |
| 160 | |
| 161 | ## Tear down — or don't |
| 162 | |
| 163 | Destroy on CI, keep the Stack alive locally for fast iteration: |
| 164 | |
| 165 | ```typescript |
| 166 | afterAll.skipIf(!!process.env.NO_DESTROY)(destroy(Stack)); // keep alive with NO_DESTROY=1 |
| 167 | afterAll.skipIf(!process.env.CI)(destroy(Stack)); // destroy on CI only |
| 168 | ``` |
| 169 | |
| 170 | Locally, the deployed Stack plus cached state make re-runs near-instant. Hook semantics live in [Hooks](/testing/test-harness#hooks). |
| 171 | |
| 172 | ## Run against an existing deployment |
| 173 | |
| 174 | Already ran `alchemy deploy` and just want to hit the URL? Swap the deploy for a read of the outputs: |
| 175 | |
| 176 | ```typescript |
| 177 | const stack = beforeAll( |
| 178 | process.env.SKIP_DEPLOY |
| 179 | ? Effect.succeed({ url: process.env.STACK_URL! }) |
| 180 | : deploy(Stack), |
| 181 | ); |
| 182 | ``` |
| 183 | |
| 184 | ## Share one Stack across files |
| 185 | |
| 186 | Give every file's `Test.make` the same remote state and the same stage — identical state + stage means the second file's `deploy(Stack)` is a no-op diff. The default `test_$USER` stage already does this for a single developer; pin an explicit stage when files must share a stack across users or CI jobs: |
| 187 | |
| 188 | ```typescript |
| 189 | // test/api.integ.test.ts AND test/queue.integ.test.ts |
| 190 | const { test, beforeAll, afterAll, deploy, destroy } = Test.make({ |
| 191 | providers: Cloudflare.providers(), |
| 192 | state: Cloudflare.state(), // remote, shared across files and runners |
| 193 | stage: "shared", // same stage → same Stack instance |
| 194 | }); |
| 195 | ``` |
| 196 | |
| 197 | See [State store](/state-store) for choosing a remote store. |
| 198 | |
| 199 | ## CI |
| 200 | |
| 201 | Give every PR its own stage so suites run in parallel against one account: |
| 202 | |
| 203 | ```typescript |
| 204 | const { test, beforeAll, afterAll, deploy, destroy } = Test.make({ |
| 205 | providers: Cloudflare.providers(), |
| 206 | stage: `pr-${process.env.PR_NUMBER}`, |
| 207 | }); |
| 208 | ``` |
| 209 | |
| 210 | Harness `deploy`/`destroy` never prompt for approval — `--yes` is only for CI workflows invoking the CLI (`alchemy deploy --stage pr-42 --yes`); see [Stage](/testing/test-harness#stage) and the [CI guide](/environments/ci) for full workflow YAML. |
| 211 | |
| 212 | ## Where next |
| 213 | |
| 214 | - [Testing](/testing) — the model behind the harness. |
| 215 | - [Test harness](/testing/test-harness) — every helper, hook, and option on `Test.make`. |
| 216 | - [Testing Providers](/testing/testing-providers) — lifecycle-testing a custom provider with `test.provider`. |
| 217 | - [CI](/environments/ci) — running these suites in CI with per-PR stages. |
| 218 | - [Cloudflare Tutorial Part 3](/cloudflare/tutorial/part-3) / [AWS Tutorial Part 3](/aws/tutorial/part-3) — your first integration test, step by step. |
| 219 | - [State store](/state-store) — local vs remote state. |
| 220 | - [Stages](/environments/stages) — isolating deployments per stage. |