@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 220 lines 8.43 KB
Raw
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.