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, the model at Testing, and the cloud-specific step-by-steps are Cloudflare Tutorial Part 3 and AWS Tutorial Part 3.
Set up the harness
Configure Providers and state once per file — Test.make returns everything the file needs:
import * as Alchemy from "alchemy";
import * as Cloudflare from "@alchemy.run/cloudflare";
import * as Drizzle from "@alchemy.run/drizzle";
import * as Neon from "@alchemy.run/neon";
import * as Test from "@alchemy.run/test/Bun";
import { expect } from "bun:test";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import Stack from "../alchemy.run.ts";
const { test, beforeAll, afterAll, deploy, destroy } = Test.make({
providers: Layer.mergeAll(
Cloudflare.providers(),
Drizzle.providers(),
Neon.providers(),
),
state: Alchemy.localState(),
}); Switching to alchemy-test or Vitest is a two-line import swap — see Runners.
Deploy once with beforeAll
beforeAll(deploy(Stack)) deploys once for the whole file and returns a lazy accessor every test can yield*:
const stack = beforeAll(deploy(Stack));
test(
"worker returns a url",
Effect.gen(function* () {
const { url } = yield* stack;
expect(url).toBeString();
}),
); The default hook timeout is 120s — give slow stacks more room:
// This stack deploys a Container whose image build + push can take
// well over the default 120s hook budget.
const stack = beforeAll(deploy(Stack), { timeout: 600_000 }); beforeAll accessors compose — seed data in a second beforeAll that tests yield* alongside the stack; see Hooks.
Run it
Run the suite with your runner:
bun test test/integ.test.ts # @alchemy.run/test/Bun
bunx alchemy-test test/integ.test.ts # @alchemy.run/test/Alchemy
npx vitest run test/integ.test.ts # @alchemy.run/test/Vitest The first run deploys; re-runs diff and skip unchanged Resources, and tests default to the isolated test_$USER stage so they never clobber your live_$USER / dev_$USER deployments.
Run it locally with dev mode
The same suite can run entirely on your machine. dev: true gives the file alchemy dev 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>:
const { test, beforeAll, afterAll, deploy, destroy } = Test.make({
providers: Cloudflare.providers(),
dev: true,
}); 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 for the full semantics and Tutorial Part 4 for the walkthrough.
Drive the live URL
HttpClient is already in scope in every test Effect:
import * as HttpBody from "effect/http/HttpBody";
import * as HttpClient from "effect/http/HttpClient";
test(
"PUT and GET round-trip an object",
Effect.gen(function* () {
const { url } = yield* stack;
const put = yield* HttpClient.put(`${url}/hello.txt`, {
body: HttpBody.text("Hello, World!"),
});
expect(put.status).toBe(201);
const get = yield* HttpClient.get(`${url}/hello.txt`);
expect(yield* get.text).toBe("Hello, World!");
}),
); How the client is wired is covered in Test harness.
Retry the first request
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:
const { getWhenReady } = Test;
test(
"worker answers once the edge converges",
Effect.gen(function* () {
const { url } = yield* stack;
const response = yield* getWhenReady(url);
expect(response.status).toBe(200);
}),
); 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:
import * as Schedule from "effect/Schedule";
const response = yield* HttpClient.get(`${url}/health`).pipe(
Effect.retry({ schedule: Schedule.exponential("500 millis"), times: 10 }),
); 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.
Poll async effects
Queues drain, workflows complete, and crons fire asynchronously — poll with a bounded declarative schedule, never a deadline loop:
const status = yield* HttpClient.get(`${url}/workflow/status/${instanceId}`).pipe(
Effect.flatMap((res) => res.json),
Effect.map((body) => body as { status: string }),
Effect.repeat({
schedule: Schedule.spaced("2 seconds"),
until: (s) => s.status === "complete",
times: 30,
}),
); Bounded times fails fast instead of leaking into the runner timeout; while (Date.now() < deadline) loops ignore interruption.
Tear down — or don't
Destroy on CI, keep the Stack alive locally for fast iteration:
afterAll.skipIf(!!process.env.NO_DESTROY)(destroy(Stack)); // keep alive with NO_DESTROY=1
afterAll.skipIf(!process.env.CI)(destroy(Stack)); // destroy on CI only Locally, the deployed Stack plus cached state make re-runs near-instant. Hook semantics live in Hooks.
Run against an existing deployment
Already ran alchemy deploy and just want to hit the URL? Swap the deploy for a read of the outputs:
const stack = beforeAll(
process.env.SKIP_DEPLOY
? Effect.succeed({ url: process.env.STACK_URL! })
: deploy(Stack),
); Share one Stack across files
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:
// test/api.integ.test.ts AND test/queue.integ.test.ts
const { test, beforeAll, afterAll, deploy, destroy } = Test.make({
providers: Cloudflare.providers(),
state: Cloudflare.state(), // remote, shared across files and runners
stage: "shared", // same stage → same Stack instance
}); See State store for choosing a remote store.
CI
Give every PR its own stage so suites run in parallel against one account:
const { test, beforeAll, afterAll, deploy, destroy } = Test.make({
providers: Cloudflare.providers(),
stage: `pr-${process.env.PR_NUMBER}`,
}); Harness deploy/destroy never prompt for approval — --yes is only for CI workflows invoking the CLI (alchemy deploy --stage pr-42 --yes); see Stage and the CI guide for full workflow YAML.
Where next
- Testing — the model behind the harness.
- Test harness — every helper, hook, and option on
Test.make. - Testing Providers — lifecycle-testing a custom provider with
test.provider. - CI — running these suites in CI with per-PR stages.
- Cloudflare Tutorial Part 3 / AWS Tutorial Part 3 — your first integration test, step by step.
- State store — local vs remote state.
- Stages — isolating deployments per stage.