@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 97 lines 4.06 KB
Raw
1 ---
2 title: Testing
3 description: How Alchemy tests work — real clouds by default, local emulators on demand, one Stack deploy per suite, isolated stages, deploy → assert → destroy.
4 ---
5
6 Alchemy tests run against real clouds by default — no mocks. A suite deploys a real Stack once, runs assertions against live resources, and tears it back down: deploy → assert → destroy. The same suite can also run entirely on your machine — see [Local mode](#local-mode-dev-true) below.
7
8 ## One deploy per suite
9
10 Deploy once in `beforeAll`, share the outputs handle across every test, destroy in `afterAll`:
11
12 ```typescript
13 const { test, beforeAll, afterAll, deploy, destroy } = Test.make({
14 providers: Cloudflare.providers(),
15 state: Cloudflare.state(),
16 });
17
18 const stack = beforeAll(deploy(Stack));
19 afterAll(destroy(Stack));
20
21 test(
22 "serves the deployed URL",
23 Effect.gen(function* () {
24 const { url } = yield* stack;
25 const res = yield* HttpClient.get(url);
26 expect(res.status).toBe(200);
27 }),
28 );
29 ```
30
31 For the full walkthrough, see [Testing a Stack](/testing/testing-a-stack).
32
33 For every option, hook, and variant, see the [Test harness](/testing/test-harness) reference.
34
35 ## Pick a runner
36
37 `Test.make` ships in `@alchemy.run/test` and runs on three test runners with the same API:
38
39 ```sh
40 bun add -d @alchemy.run/test
41 ```
42
43 Import it from the adapter for your runner:
44
45 ```typescript
46 import * as Test from "@alchemy.run/test/Alchemy"; // alchemy-test
47 import * as Test from "@alchemy.run/test/Bun"; // bun test
48 import * as Test from "@alchemy.run/test/Vitest"; // Vitest
49 ```
50
51 `alchemy-test` runs every file in one bun process with tests in flight concurrently, built for slow tests against real clouds. Install and run each one as shown in [Test harness → Runners](/testing/test-harness#runners).
52
53 ## Stage isolation
54
55 Tests default to `test_$USER` (e.g. `test_sam`), matching how
56 `alchemy deploy` uses `live_$USER` and `alchemy dev` uses
57 `dev_$USER` — so they never touch your live or local-dev
58 deployments, and two people running the same suite don't collide. A
59 unique stage per PR lets CI suites run in parallel against the same
60 account:
61
62 ```typescript
63 Test.make({ providers, stage: "ci-pr-42" });
64 ```
65
66 Or set it for the whole run from the command line:
67
68 ```sh
69 bunx alchemy-test --stage ci-pr-42
70 ALCHEMY_TEST_STAGE=ci-pr-42 bun test
71 ```
72
73 Running several git worktrees at once? See [Worktrees](/environments/worktrees). The per-call form is covered in [Test harness → stage](/testing/test-harness#stage).
74
75 ## Local mode (`dev: true`)
76
77 The harness has the same local-dev mode as [`alchemy dev`](/environments/local-development). It's off by default; flip it on and the whole suite runs against local emulators — Cloudflare Workers, Durable Objects, KV, R2, D1, Queues, and Workflows in workerd, AWS Lambda/ECS and the emulated AWS surface in a local Docker emulator — with no cloud calls:
78
79 ```typescript
80 Test.make({
81 providers: Cloudflare.providers(),
82 dev: true,
83 });
84 ```
85
86 Nothing else changes: `deploy(Stack)` boots the stack locally and the tests drive `http://localhost:<port>` instead of the cloud. There's no need for a separate testing setup (e.g. workerd + a vitest plugin) — the harness runs your real Stack in the same local runtimes `alchemy dev` uses. Omit the flag and set `ALCHEMY_DEV=1` in your shell to keep one test file that runs locally on your laptop and live in CI.
87
88 Full option semantics: [Test harness → dev](/testing/test-harness#dev).
89
90 ## Where next
91
92 - [Testing a Stack](/testing/testing-a-stack) — deploy a Stack and drive it over HTTP, end to end.
93 - [Testing Providers](/testing/testing-providers) — exercise a provider's create/update/replace/delete with `test.provider`.
94 - [Test harness](/testing/test-harness) — every `Test.make` option, hook, and variant.
95 - [Observability](/testing/observability) — wire exporters, monitors, and alarms into the same Stack.
96 - [Tutorial Part 3](/cloudflare/tutorial/part-3) — your first integration test, walked through step by step.
97 - [Tutorial Part 4](/cloudflare/tutorial/part-4) — running the same tests against local emulators with `dev: true`.