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

main
mdx 201 lines 5.44 KB
Raw
1 ---
2 title: "Part 3: Testing"
3 description: Write integration tests that deploy your stack and make HTTP requests against the live Cloud Run service.
4 sidebar:
5 order: 3
6 ---
7
8 In [Part 2](/gcp/tutorial/part-2) you deployed a Cloud Run service
9 bound to a Bucket. Now you write tests that deploy the Stack, call the
10 live service, and check 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 `Test.make` takes the same providers and state as your Stack:
23
24 ```typescript
25 // test/integ.test.ts
26 import * as Alchemy from "alchemy";
27 import * as GCP from "@alchemy.run/gcp";
28 import * as Test from "@alchemy.run/test/Bun";
29 import { expect } from "bun:test";
30 import * as Effect from "effect/Effect";
31 import Stack from "../alchemy.run.ts";
32
33 const { test, beforeAll, afterAll, deploy, destroy } = Test.make({
34 providers: GCP.providers(),
35 state: GCP.state(),
36 });
37 ```
38
39 :::note[Using Vitest or alchemy-test?]
40 `@alchemy.run/test/Vitest` and `@alchemy.run/test/Alchemy` have the same API.
41 Take `expect` from `@effect/vitest` or `@alchemy.run/test` instead. See
42 [Test harness → Runners](/testing/test-harness#runners).
43 :::
44
45 ## Deploy before the tests
46
47 Deploy the Stack once, before any test runs:
48
49 ```diff lang="typescript"
50 const { test, beforeAll, afterAll, deploy, destroy } = Test.make({
51 providers: GCP.providers(),
52 state: GCP.state(),
53 });
54
55 +const stack = beforeAll(deploy(Stack), { timeout: 600_000 });
56 ```
57
58 `beforeAll` returns a handle. `yield*` it inside a test to get the
59 Stack outputs. The first deploy builds an image, so give it a long
60 timeout.
61
62 ## Read the outputs
63
64 ```diff lang="typescript"
65 const stack = beforeAll(deploy(Stack), { timeout: 600_000 });
66
67 +test(
68 + "stack exposes a service url",
69 + Effect.gen(function* () {
70 + const { url } = yield* stack;
71 +
72 + expect(url).toStartWith("https://");
73 + }),
74 +);
75 ```
76
77 ## Run the tests
78
79 ```sh
80 bun test test/integ.test.ts
81 ```
82
83 The first run deploys. Later runs reuse the deployment and only change
84 what you changed.
85
86 :::note[Which stage do tests use?]
87 Tests deploy to `test_$USER` (e.g. `test_sam`), apart from the
88 `live_$USER` stage `alchemy deploy` uses. Your working deployment is
89 never touched. More on stages in [Part 4](/gcp/tutorial/part-4).
90 :::
91
92 ## Call the service
93
94 Replace the first test with a round trip through the Bucket:
95
96 ```diff lang="typescript"
97 // test/integ.test.ts
98 import * as Alchemy from "alchemy";
99 import * as GCP from "@alchemy.run/gcp";
100 import * as Test from "@alchemy.run/test/Bun";
101 import { expect } from "bun:test";
102 import * as Effect from "effect/Effect";
103 +import * as HttpBody from "effect/http/HttpBody";
104 +import * as HttpClient from "effect/http/HttpClient";
105 +import * as Schedule from "effect/Schedule";
106 import Stack from "../alchemy.run.ts";
107
108 const { test, beforeAll, afterAll, deploy, destroy } = Test.make({
109 providers: GCP.providers(),
110 state: GCP.state(),
111 });
112
113 const stack = beforeAll(deploy(Stack), { timeout: 600_000 });
114
115 -test(
116 - "stack exposes a service url",
117 - Effect.gen(function* () {
118 - const { url } = yield* stack;
119 -
120 - expect(url).toStartWith("https://");
121 - }),
122 -);
123 +test(
124 + "PUT and GET round-trip an object",
125 + Effect.gen(function* () {
126 + const { url } = yield* stack;
127 +
128 + const put = yield* HttpClient.put(`${url}/hello.txt`, {
129 + body: HttpBody.text("Hello, World!"),
130 + }).pipe(
131 + Effect.retry({ schedule: Schedule.exponential("500 millis"), times: 10 }),
132 + );
133 + expect(put.status).toBe(204);
134 +
135 + const get = yield* HttpClient.get(`${url}/hello.txt`);
136 + expect(yield* get.text).toBe("Hello, World!");
137 + }),
138 + { timeout: 120_000 },
139 +);
140 +
141 +test(
142 + "GET a missing key returns 404",
143 + Effect.gen(function* () {
144 + const { url } = yield* stack;
145 + const response = yield* HttpClient.get(`${url}/no-such-key`);
146 + expect(response.status).toBe(404);
147 + }),
148 +);
149 ```
150
151 `HttpClient` comes with the test harness.
152
153 :::tip[Retry the first request]
154 A new service's Bucket grant can take a few seconds to reach Cloud
155 Storage. Retry the first request with a bounded schedule, as above.
156 :::
157
158 ## Let destroy empty the Bucket
159
160 The PUT test leaves `hello.txt` in the Bucket. Cloud Storage won't
161 delete a Bucket that still has objects, so destroy would fail. This
162 Bucket only holds test data, so let destroy empty it first:
163
164 ```diff lang="typescript"
165 // src/api.ts
166 Effect.gen(function* () {
167 - const bucket = yield* GCP.Storage.Bucket("Bucket", {});
168 + const bucket = yield* GCP.Storage.Bucket("Bucket", {
169 + forceDestroy: true,
170 + });
171 const files = yield* GCP.Storage.ReadWriteBucket(bucket);
172 ```
173
174 Leave `forceDestroy` off for Buckets that hold data you need to keep.
175
176 ## Destroy after tests in CI
177
178 Locally, keep the Stack deployed between runs so tests start fast. In
179 CI, tear it down:
180
181 ```diff lang="typescript"
182 const stack = beforeAll(deploy(Stack), { timeout: 600_000 });
183
184 +afterAll.skipIf(!process.env.CI)(destroy(Stack), { timeout: 600_000 });
185 ```
186
187 With `CI=true` the Stack is destroyed after the tests. Without it,
188 `skipIf` skips the destroy.
189
190 ## Recap
191
192 You now have:
193
194 - `Test.make({ providers, state })` wiring GCP into the test runner
195 - `beforeAll(deploy(Stack))` deploying once before the tests
196 - HTTP assertions against the live Cloud Run URL
197 - `forceDestroy: true` so destroy can delete a Bucket tests wrote to
198 - `afterAll.skipIf(!process.env.CI)(destroy(Stack))` cleaning up in CI
199
200 In [Part 4](/gcp/tutorial/part-4), you give every developer,
201 environment, and pull request its own copy of the Stack.