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 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. |