clover's git

the-knife

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	## Stage isolation
36
37	Tests default to `test_$USER` (e.g. `test_sam`), matching how
38	`alchemy deploy` uses `live_$USER` and `alchemy dev` uses
39	`dev_$USER` — so they never touch your live or local-dev
40	deployments, and two people running the same suite don't collide. A
41	unique stage per PR lets CI suites run in parallel against the same
42	account:
43
44	```typescript
45	Test.make({ providers, stage: "ci-pr-42" });
46	```
47
48	The per-call form is covered in [Test harness → stage](/testing/test-harness#stage).
49
50	## Local mode (`dev: true`)
51
52	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:
53
54	```typescript
55	Test.make({
56	providers: Cloudflare.providers(),
57	dev: true,
58	});
59	```
60
61	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.
62
63	Full option semantics: [Test harness → dev](/testing/test-harness#dev).
64
65	## Where next
66
67	- [Testing a Stack](/testing/testing-a-stack) — deploy a Stack and drive it over HTTP, end to end.
68	- [Testing Providers](/testing/testing-providers) — exercise a provider's create/update/replace/delete with `test.provider`.
69	- [Test harness](/testing/test-harness) — every `Test.make` option, hook, and variant.
70	- [Observability](/testing/observability) — wire exporters, monitors, and alarms into the same Stack.
71	- [Tutorial Part 3](/cloudflare/tutorial/part-3) — your first integration test, walked through step by step.
72	- [Tutorial Part 4](/cloudflare/tutorial/part-4) — running the same tests against local emulators with `dev: true`.