sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare-test-tools/ src/ e2e
- Cli.ts
- CloudflareTarget.ts
- Cwd.ts
- Framework.ts
- Options.ts
- Playwright.ts
- README.md
- Runtime.ts
- Server.ts
- TailwindNodeCompat.ts
- Vite.ts
.repos/alchemy-effect/packages/cloudflare-test-tools/src/e2e/README.md
@alchemy.run/cloudflare-test-tools/e2e
The e2e harness that drives a fixture's dev server, production build, and
miniflare preview, and exposes them to Playwright. The harness is
framework-pluggable: every fixture is driven through framework-core's
Framework service, and a fixture selects its implementation in
e2e.config.ts. When no framework is named, the built-in Vite implementation
(over @alchemy.run/cloudflare-runtime/vite) is used — existing Vite
fixtures need no changes.
How a fixture uses the harness
A fixture's package.json scripts call the e2e bin:
{
"scripts": {
"dev": "e2e dev", // Framework.dev — the framework's dev server
"build": "e2e build", // Framework.build; the harness persists dist/build.json
"preview": "e2e preview", // miniflare over dist/build.json
"test": "playwright test",
},
} e2e.config.ts at the fixture root default-exports Options.make({...}) (or
an Effect of it, for config that reads env via Config):
import * as Options from "@alchemy.run/cloudflare-test-tools/e2e/Options";
export default Options.make({
framework: "@alchemy.run/frontend-frameworks/waku", // ← optional; omit for the Vite default
target: {
// name: "cloudflare" is the default (the only implemented target today)
cloudflare: {
worker: {
compatibilityDate: "2026-03-10",
compatibilityFlags: ["nodejs_compat"],
worker: { name: "fixtures-waku", bindings: [], assets: {} },
},
preview: {
compatibilityDate: "2026-03-10",
compatibilityFlags: ["nodejs_compat"],
assets: {
/* router/asset config */
},
},
},
},
}); Config is target-scoped: target.<platform> carries everything that
platform's deploy target needs, opaque to the rest of the harness (a future
AWS target adds target.aws without touching the plumbing). The pre-target
top-level fields remain as deprecated aliases — vite ≙
target.cloudflare.worker, miniflare ≙ target.cloudflare.preview — and
Options.resolveCloudflareOptions(options) is the single accessor that
merges them (target-scoped wins). Existing fixture configs work unchanged.
Playwright fixtures come from @alchemy.run/cloudflare-test-tools/e2e/Playwright:
Playwright.make("live") boots the miniflare preview (building first if
dist/build.json is absent), Playwright.make("dev") boots the framework dev
server. Both dispatch through the Framework service.
The framework option
Options.framework selects the Framework-service implementation. Accepted
forms:
- Omitted — the built-in Vite implementation, configured by
options.vite. Zero behavior change for existing fixtures. - A package specifier string (e.g.
"@alchemy.run/frontend-frameworks/waku") — resolved and imported from the fixture's ownnode_modulesvia framework-core'sloadProjectModule(cwd, specifier), so the fixture's installed copy of the framework (itswaku,astro,next, ... dependency tree) is the one driven — never whatever is hoisted next to the harness. Relative specifiers that the fixture's resolution can reach work too. - A factory function — called with the fixture's full
Options. - A
Layer<Framework>— used as-is. Build it yourself ine2e.config.tsby importing the framework package directly; this is the fully-typed path for framework-specific options that don't fit the sharedOptionsshape.
What a framework package must export
A package named by the string form must default-export (or named-export
framework) one of:
- a factory
(options: Options) => Layer<Framework>— the primary contract; - a factory returning
Effect<Layer<Framework>>(for effectful setup); - a
Layer<Framework>directly (for packages with no per-fixture options).
// @alchemy.run/frontend-frameworks/waku — src/waku/index.ts
import type { Options } from "@alchemy.run/cloudflare-test-tools/e2e/Options";
import { Framework } from "@alchemy.run/frontend-frameworks/core";
import * as Layer from "effect/Layer";
export default (options: Options): Layer.Layer<Framework> =>
Layer.effect(Framework /* ... build/dev over waku ... */); Options flow
The factory receives the entire parsed Options object from the fixture's
e2e.config.ts. Conventions:
options.target.cloudflare.worker(CloudflareVitePluginOptions) carries the cloudflare worker configuration — compatibility date/flags, worker name, bindings, assets behavior. Framework packages should readoptions.target?.cloudflare?.worker ?? options.vite(the deprecated top-level alias) so fixtures stay uniform.options.target.cloudflare.preview(alias:options.miniflare) is consumed by the harness's preview server only; framework packages should not read it.- Anything richer than the shared worker config (framework-specific knobs) should be taken via the Layer/factory forms (3)/(4) above, where the fixture calls your typed API directly.
Layer environment
The Layer is built inside the harness runtime, which provides
@effect/platform-node's NodeServices (so FileSystem.FileSystem and
Path.Path may appear in the Layer's requirements — the
Options.FrameworkServices type) and a dotenv/env ConfigProvider. The
process working directory is the fixture root. Anything else the layer needs,
it must provide itself.
Load the project's framework module (its vite, waku, astro, ...) with
framework-core's loadProjectModule(root, specifier) /
resolveProjectPackageDirectory — never a bare import from your own
dependency tree.
The Framework service contract
Defined in @alchemy.run/frontend-frameworks/core (Framework.ts):
class Framework extends Context.Service<
Framework,
{
readonly build: (options?: FrameworkBuildOptions) => Effect<BuildOutput, FrameworkError>;
readonly dev: (
options?: FrameworkDevOptions,
) => Effect<FrameworkDevServer, FrameworkError, Scope.Scope>; // { url: string }
}
>()("@alchemy.run/frontend-frameworks/core/Framework") {} Semantics every implementation must honor:
buildruns the framework's production build and returns theBuildOutputcontract purely in-memory — implementations write nothing beyond the framework's own build output (nodist/build.json; persistence is the harness's job, see below). Errors surface asFrameworkError(set theframeworkfield to your framework name).devstarts the framework's dev server and returns{ url }. It is scoped: closing theScopemust stop the server. HonorFrameworkDevOptions.portwhen given.FrameworkBuildOptions.root/FrameworkDevOptions.rootoverride the project root (default: the configured root / cwd).
The dist/build.json convention (BuildOutput)
dist/build.json is the harness's E2E persistence mechanism, not part of
the Framework contract: e2e build persists the returned BuildOutput
there itself (framework-core's writeBuildOutput), and e2e preview reads
it back (framework-core's readBuildOutput), so preview stays uniform across
frameworks without any framework writing files into user projects.
BuildOutput (framework-core BuildOutput.ts) is the cross-framework build
contract:
clientDirectory— the static-assets directory, captured as a path so files written after the bundler finishes (SSG HTML, prerendered pages) ride along.undefinedif there are no client assets.serverModules— the worker modules asOutputFiles (namerelative todistDirectory,content, sha256hash), entry module first (sortServerModulesenforces this ordering).undefinedfor assets-only builds.externalWorkspaces— workspace roots of modules imported from outside the project root (for watch/memoization); collect withcollectExternalWorkspaces.distDirectory— the build's root output directory (e.g.<root>/dist).
The harness persists with writeBuildOutput(path, output) and reads with
readBuildOutput(path) — they handle the JSON round-trip (Buffer revival for
binary modules, externalWorkspaces Set). Vite-based frameworks can produce
the whole shape with makeBuildOutputCollector; frameworks whose final
bundles land on disk after the bundler (SvelteKit, Next.js) can use
readServerModulesFromDisk.
How the harness consumes the contract
e2e build→Framework.build(), then the harness persists the returnedBuildOutputto<fixture>/dist/build.json(Server.buildAndPersist).e2e dev(andServer.dev()/Playwright.make("dev")) →Framework.dev(); the harness wraps the returnedurlwith fetch helpers.e2e preview(andServer.live()/Playwright.make("live")) → readsdist/build.json(framework-core'sreadBuildOutput), falling back toFramework.build()+ persist when it is missing or unreadable; then hands theBuildOutputto the cloudflare deploy target'sserve(src/e2e/CloudflareTarget.ts, a framework-coreDeployTargetvalue), which boots miniflare (@alchemy.run/cloudflare-test-tools/miniflare) with the fixture'starget.cloudflare.previewoptions. Serving built output is the target's concern; the framework implementation is only involved in producing a correctBuildOutput.