import { stripVTControlCharacters } from "node:util";
import { AdoptPolicy } from "alchemy/AdoptPolicy";
import { AlchemyContext, AlchemyContextLive } from "alchemy/AlchemyContext";
import { ArtifactStore, provideFreshArtifactStore } from "alchemy/Artifacts";
import { AuthProviders } from "alchemy/Auth/AuthProvider";
import { CredentialsStoreLive } from "alchemy/Auth/Credentials";
import { ProfileStoreLive } from "alchemy/Auth/Profile";
import { withProfileOverride } from "alchemy/Auth/Resolve";
import { userStage } from "alchemy/Cli/commands/flags";
import { LoggingCli } from "alchemy/Cli/LoggingCli";
import * as Contributions from "alchemy/Contributions";
import * as AlchemyDeploy from "alchemy/Deploy";
import * as AlchemyDestroy from "alchemy/Destroy";
import type { Input } from "alchemy/Input";
import * as Interaction from "alchemy/Interaction";
import * as RpcProviderProxy from "alchemy/Local/RpcProviderProxy";
import * as RpcSpawner from "alchemy/Local/RpcSpawner";
import { ALCHEMY_DEV } from "alchemy/Phase";
import * as Plan from "alchemy/Plan";
import type { ResourceSelection, SelectionOutput } from "alchemy/ResourceSelection";
import {
type CompiledStack,
make as makeStack,
Stack,
type StackDefinition,
type StackEffect,
type StackServices,
} from "alchemy/Stack";
import { Stage } from "alchemy/Stage";
import * as State from "alchemy/State";
import { TelemetryLive } from "alchemy/Telemetry/Layer";
import { loadConfigProvider, StackConfigOverrides } from "alchemy/Util/ConfigProvider";
import { kindOf, recordOf } from "alchemy/Util/LogRecord";
import { PlatformServices } from "alchemy/Util/PlatformServices";
/** @effect-diagnostics anyUnknownInErrorContext:off */
import * as Config from "effect/Config";
import { ConfigProvider } from "effect/ConfigProvider";
import * as Context from "effect/Context";
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
import * as FetchHttpClient from "effect/http/FetchHttpClient";
import * as HttpClient from "effect/http/HttpClient";
import * as Layer from "effect/Layer";
import * as Logger from "effect/Logger";
import * as Option from "effect/Option";
import * as Scope from "effect/Scope";
/**
* Configuration shared by every test in a file. Pass to `Test.make(...)`.
*/
export interface MakeOptions<ROut = any> {
/** Provider layer for the stack — e.g. `AWS.providers()`, `Cloudflare.providers()`. */
providers: Layer.Layer<ROut, never, StackServices>;
/** State store for top-level `deploy(Stack)` / `destroy(Stack)`; defaults to {@link State.localState}. */
state?: Layer.Layer<State.State, never, StackServices>;
/** Override the current profile; otherwise resolved from env or the built-in `default`. */
profile?: string;
/**
* Default stage for deploy/destroy. Defaults to `test_$USER` (or
* `test_$USERNAME` on Windows, `test_unknown` if neither is set) so two
* people running the same suite against one account don't collide.
* Does **not** read `$ALCHEMY_STAGE` — that is the CLI deploy/dev stage.
*/
stage?: string;
/**
* Engine-level adoption policy for this test run. When `true`, resources
* without prior state will be adopted from the cloud via `provider.read`
* (matching the CLI's `--adopt` flag). Defaults to `false`.
*/
adopt?: boolean;
/**
* Run providers in local-dev mode (matching the CLI's `alchemy dev` flag).
* When `true`, resources like Cloudflare Workers run locally via workerd
* instead of being deployed to the cloud. When omitted, falls back to the
* `ALCHEMY_DEV` environment variable (`"1"` / `"true"` enable it).
*
* {@link ALCHEMY_TEST_DEV} (`ALCHEMY_TEST_DEV=1`) overrides this — use it
* to force an entire existing live suite through local providers without
* editing each `Test.make({ dev: true })`.
*/
dev?: boolean;
/**
* Run local providers behind the RPC sidecar proxy, matching the process
* topology of the real `alchemy dev` command: an {@link RpcProviderProxy}
* is installed, so `RpcProvider.providerServicesEffect` layers (e.g.
* Cloudflare's `localRuntimeServices()`) are EMPTY in the test process and
* RPC-backed providers run their lifecycle in a spawned sidecar process.
*
* Defaults to the resolved `dev` flag — dev tests run the real `alchemy
* dev` topology unless they opt out. In-process dev (`sidecar: false`)
* masks missing main-process lifecycle dependencies (the class of bug
* behind #1007, where D1's local migrations only failed under `alchemy
* dev`); it remains available because it IS still a real production path —
* a plain `alchemy deploy` deleting a `providerMode: "local"` state row
* runs the local provider in-process — and because in-process runs are
* easier to debug.
*
* Fully lazy: only the proxy facade is installed up front. The spawner
* HTTP server starts — and a sidecar child process is forked — on the
* first provider session request (a deploy/destroy building an RPC-backed
* local provider); a dev file that never does starts no processes at all.
* Once started, the sidecar lives for the whole test file (its own scope,
* closed by the adapter's final cleanup hook), so `beforeAll(deploy(Stack))`
* + per-test requests work the same way they do under a real `alchemy dev`
* session.
*
* Pass an object to run the sidecar with options: `omitEnv` lists prefixes
* of environment variables the sidecar must not inherit (e.g.
* `["CLOUDFLARE_"]` to exercise credential-free dev while the shell
* exports credentials).
*/
sidecar?: boolean | SidecarOptions;
}
/** Options for the dev sidecar process — see {@link MakeOptions.sidecar}. */
export interface SidecarOptions {
/** Prefixes of environment variables withheld from the sidecar. */
readonly omitEnv?: ReadonlyArray<string>;
}
/**
* The RPC sidecar topology used by the real `alchemy dev` command, in one
* process-local layer: an {@link RpcSpawner} HTTP server that forks sidecar
* processes on demand, and an {@link RpcProviderProxy} pointed at it.
*/
export const sidecarProxy = (options: { profile?: string; omitEnv?: ReadonlyArray<string> }) =>
Layer.unwrap(
Effect.map(RpcSpawner.RpcSpawner, (spawner) => RpcProviderProxy.layer(spawner.url)),
).pipe(
Layer.provideMerge(
RpcSpawner.layerServer({
profile: options.profile ?? process.env.ALCHEMY_PROFILE,
envFile: undefined,
omitEnv: options.omitEnv,
}),
),
);
/**
* Force every `Test.make` into (or out of) local-dev mode, regardless of
* the file's `dev` option. Unset leaves the option / `ALCHEMY_DEV` fallback
* in place. Accepts the usual truthy/falsey strings (`true`/`1`/`yes`/`on`,
* `false`/`0`/`no`/`off`).
*/
export const ALCHEMY_TEST_DEV = Config.Boolean("ALCHEMY_TEST_DEV").pipe(Config.option);
/** The `ALCHEMY_TEST_DEV` override, if the env var is set. */
export const alchemyTestDevOverride = (): Option.Option<boolean> =>
Effect.runSync(ALCHEMY_TEST_DEV);
/** Resolve the effective `dev` flag: `ALCHEMY_TEST_DEV`, then options, then `ALCHEMY_DEV`. */
export const resolveDev = (options: { dev?: boolean }): boolean => {
const override = alchemyTestDevOverride();
if (Option.isSome(override)) return override.value;
if (options.dev !== undefined) return options.dev;
return Effect.runSync(ALCHEMY_DEV);
};
/** Resolve the effective `sidecar` flag: defaults to the resolved `dev` flag. */
export const resolveSidecar = (options: MakeOptions): boolean =>
options.sidecar === undefined ? resolveDev(options) : options.sidecar !== false;
/** The sidecar's withheld env prefixes, sorted so equal sets share a key. */
const sidecarOmitEnv = (options: MakeOptions): ReadonlyArray<string> =>
typeof options.sidecar === "object" ? [...(options.sidecar.omitEnv ?? [])].sort() : [];
/**
* Default test stage: `ALCHEMY_TEST_STAGE`, then `test_$USER` (or
* `test_$USERNAME` / `test_unknown`). The runner sets ALCHEMY_TEST_STAGE to
* `test_$USER_<worktree>` in a linked git worktree, so concurrent worktrees
* sharing a cloud account stay isolated.
* Matches the CLI's `live_$USER` / `dev_$USER` per-developer isolation.
*/
export const defaultStage = (): string =>
process.env.ALCHEMY_TEST_STAGE || Effect.runSync(userStage("test"));
/** File-level stage: a string override, otherwise {@link defaultStage}. */
export const resolveStage = (options: { stage?: string }): string =>
// Configured stacks carry a cross-stack reference proxy, not a stage override.
typeof options.stage === "string" ? options.stage : defaultStage();
/**
* The sidecar runtime handed to each adapter's `make(...)`.
*
* `provide` installs a lazy {@link RpcProviderProxy} facade into an effect.
* Installing the facade is free: the spawner HTTP server only starts (and,
* downstream of it, a sidecar child process is only forked) when a provider
* actually requests a session — i.e. when a deploy/destroy builds an
* RPC-backed local provider. A dev file that never does starts nothing.
*
* The spawner (and the sidecar children it forks) is a PROCESS-WIDE
* SINGLETON shared by every test file, refcounted per handle: all files run
* in one bun process, and a per-file sidecar means a per-file bun child that
* imports the entire alchemy + distilled module graph — dozens of concurrent
* files at hundreds of MB each OOMs the machine. Stack isolation is
* preserved because each RPC session carries its own stack environment (see
* `SESSION_ENV_PARAM` in Local/RpcServerEnvironment.ts) and the child builds
* a provider context per stack. The singleton's scope closes when the LAST
* handle closes; `Test.make` runs at collection time (before any test), so
* the refcount cannot dip to zero while later files still need it. Adapters
* run `close` from the same final cleanup hook that closes the shared scope.
*/
export interface SidecarHandle {
readonly provide: <A, E, R>(eff: Effect.Effect<A, E, R>) => Effect.Effect<A, any, any>;
readonly close: Effect.Effect<void>;
}
interface SidecarSingleton {
readonly real: ReturnType<typeof sidecarProxy>;
readonly memoMap: Layer.MemoMap;
readonly scope: Scope.Closeable;
proxy?: RpcProviderProxy.RpcProviderProxy["Service"];
refs: number;
}
const sidecarSingletons = new Map<string, SidecarSingleton>();
/** Payload-free counts; observing them never starts the singleton. */
export const sidecarDiagnostics = Effect.gen(function* () {
const instances = [...sidecarSingletons.values()];
const counts = { sessions: 0, testSessions: 0, owners: 0, connections: 0 };
for (const instance of instances) {
if (instance.proxy === undefined) continue;
const current = yield* instance.proxy.diagnostics;
counts.sessions += current.sessions;
counts.testSessions += current.testSessions;
counts.owners += current.owners;
counts.connections += current.connections;
}
return {
singletons: instances.length,
reservations: instances.reduce((sum, instance) => sum + instance.refs, 0),
started: instances.filter((instance) => instance.proxy !== undefined).length,
...counts,
};
});
export const makeSidecarHandle = <ROut = any>(
options: MakeOptions<ROut>,
): SidecarHandle | undefined => {
if (!resolveSidecar(options)) return undefined;
const profile = options.profile ?? process.env.ALCHEMY_PROFILE ?? "";
const omitEnv = sidecarOmitEnv(options);
// Files only share a sidecar when it was started with the same environment.
const key = JSON.stringify([profile, omitEnv]);
let singleton = sidecarSingletons.get(key);
if (singleton === undefined) {
singleton = {
real: sidecarProxy({ profile: options.profile, omitEnv }),
memoMap: Layer.makeMemoMapUnsafe(),
scope: Scope.makeUnsafe("sequential"),
refs: 0,
};
sidecarSingletons.set(key, singleton);
}
singleton.refs += 1;
let runtime:
| {
instance: SidecarSingleton;
owner: RpcProviderProxy.SessionOwner;
contexts: Set<{ ambient?: Context.Context<any> }>;
}
| undefined = {
instance: singleton,
owner: RpcProviderProxy.makeSessionOwner(),
contexts: new Set(),
};
const lazy = Layer.effect(
RpcProviderProxy.RpcProviderProxy,
Effect.gen(function* () {
if (runtime === undefined) {
return yield* Effect.die("Test sidecar handle is closed");
}
// Never pin the singleton to a file's scope, artifacts, or layer builds.
const context = {
ambient: Context.omit(
Scope.Scope,
ArtifactStore,
Layer.CurrentMemoMap,
)(yield* Effect.context<never>()) as Context.Context<any> | undefined,
};
if (runtime === undefined) {
return yield* Effect.die("Test sidecar handle is closed");
}
runtime.contexts.add(context);
return RpcProviderProxy.RpcProviderProxy.of({
diagnostics: Effect.suspend(
() =>
runtime?.instance.proxy?.diagnostics ??
Effect.succeed({
sessions: 0,
testSessions: 0,
owners: 0,
connections: 0,
}),
),
serverDiagnostics: Effect.suspend(
() => runtime?.instance.proxy?.serverDiagnostics ?? Effect.succeed(undefined),
),
get: Effect.fn(function* (providersUrl, providerName) {
if (runtime === undefined) {
return yield* Effect.die("Test sidecar handle is closed");
}
const { instance, owner } = runtime;
let proxy = instance.proxy;
if (proxy === undefined) {
const built = yield* Layer.buildWithMemoMap(
instance.real,
instance.memoMap,
instance.scope,
).pipe(
Effect.provideContext(context.ambient!),
Scope.provide(instance.scope),
Effect.orDie,
);
proxy = Context.get(built, RpcProviderProxy.RpcProviderProxy);
instance.proxy = proxy;
}
context.ambient = undefined;
runtime?.contexts.delete(context);
// A handle may have closed while the singleton was building.
return yield* proxy.get(providersUrl, providerName, owner);
}),
});
}),
);
return {
provide: (eff) => Effect.provide(eff, lazy),
close: Effect.suspend(() => {
if (runtime === undefined) return Effect.void;
const { instance, owner, contexts } = runtime;
runtime = undefined;
for (const context of contexts) context.ambient = undefined;
contexts.clear();
return RpcProviderProxy.closeSessionOwner(owner).pipe(
Effect.ensuring(
Effect.suspend(() => {
instance.refs -= 1;
if (instance.refs > 0) return Effect.void;
if (sidecarSingletons.get(key) === instance) sidecarSingletons.delete(key);
instance.proxy = undefined;
return Scope.close(instance.scope, Exit.void);
}),
),
);
}).pipe(Effect.uninterruptible, Effect.ignore),
};
};
const overrideAlchemyContext = (overrides: { dev: boolean }) =>
Layer.effect(
AlchemyContext,
AlchemyContext.pipe(Effect.map((ctx) => ({ ...ctx, ...overrides }))),
);
export type TestEffect<A, Req = never> = StackEffect<A, any, Req>;
const testDev = Option.getOrElse(alchemyTestDevOverride(), () => false);
/**
* Every provider's test services (e.g. AWS's Floci emulator), applied under
* {@link ALCHEMY_TEST_DEV} only.
*/
const testServices: ReadonlyArray<Contributions.TestServices> = testDev
? await Effect.runPromise(
Contributions.load().pipe(
Effect.flatMap((providers) =>
Effect.forEach(providers, (provider) =>
provider.testServices
? Contributions.resolve(provider, "testServices", provider.testServices)
: Effect.succeed(undefined),
),
),
Effect.map((services) => services.filter((service) => service !== undefined)),
Effect.provide(PlatformServices),
),
)
: [];
if (testDev) {
// Emulators rewrite WebSocket invoke URLs onto their self-signed gateway;
// Bun/Node would otherwise reject the upgrade. Scoped to ALCHEMY_TEST_DEV
// only.
process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
// Set here — before the RPC spawner or any vite child forks — so the whole
// dev process tree inherits it.
for (const services of testServices) {
for (const [key, value] of Object.entries(services.env ?? {})) process.env[key] ??= value;
}
}
/** The test services' layers, closest wins over the stack's own. */
const testServicesLayer =
testServices.length === 0
? undefined
: testServices
.map((services) => services.layer)
.reduce((merged, layer) => Layer.merge(merged, layer));
const provideTestServices = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
// Test services override services already present in R.
testServicesLayer === undefined
? effect
: // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- the layer overrides services already present in R
(Effect.provide(effect, testServicesLayer) as Effect.Effect<A, E, R>);
const testHttp = Layer.effect(
HttpClient.HttpClient,
Effect.map(HttpClient.HttpClient, (client) =>
testServices.reduce(
(mapped, services) =>
services.mapRequest ? HttpClient.mapRequest(mapped, services.mapRequest) : mapped,
client,
),
),
).pipe(Layer.provide(FetchHttpClient.layer));
const platformLayer = () =>
Layer.mergeAll(
PlatformServices,
testDev ? testHttp : FetchHttpClient.layer,
Layer.provide(ProfileStoreLive, PlatformServices),
Layer.provide(CredentialsStoreLive, PlatformServices),
);
const alchemyLayer = Layer.mergeAll(
LoggingCli,
Interaction.layerNonInteractive(),
AlchemyContextLive,
);
/** Most lines one capture keeps; older ones are dropped first. */
const RESOURCE_LOG_LIMIT = 5_000;
/** The open {@link captureResourceLog} buffers, by resource fqn. */
const resourceCaptures = new Map<string, Set<Array<string>>>();
/**
* Copies each record tagged with a captured resource (`fqn`) into its open
* captures. Installed beside the runner's loggers, so it also sees the shared
* sidecar's records, which the spawner logs in whichever file started the
* sidecar rather than in the test that deployed the resource.
*/
const resourceRecorder = Logger.make<unknown, void>((options) => {
if (resourceCaptures.size === 0) return;
const record = recordOf(options);
const fqn = record.attributes.fqn;
const captures = typeof fqn === "string" ? resourceCaptures.get(fqn) : undefined;
if (captures === undefined || (record.kind !== "log" && record.kind !== "output")) return;
const line = stripVTControlCharacters(
record.kind === "log" ? record.data.message : record.data.text,
);
for (const lines of captures) {
lines.push(line);
if (lines.length > RESOURCE_LOG_LIMIT) lines.splice(0, lines.length - RESOURCE_LOG_LIMIT);
}
});
/**
* Start capturing what the resource `fqn` logs — its processes' output (a dev
* Worker's console, a Vite dev server) and alchemy's lines about it — whether
* its provider runs in the dev sidecar or in-process. Start it before the
* deploy; the returned effect reads every line since, without ANSI styling.
* The capture ends with the enclosing scope.
*/
export const captureResourceLog = (
fqn: string,
): Effect.Effect<Effect.Effect<string>, never, Scope.Scope> =>
Effect.acquireRelease(
Effect.sync(() => {
const lines: Array<string> = [];
let captures = resourceCaptures.get(fqn);
if (captures === undefined) resourceCaptures.set(fqn, (captures = new Set()));
captures.add(lines);
return lines;
}),
(lines) =>
Effect.sync(() => {
const captures = resourceCaptures.get(fqn);
captures?.delete(lines);
if (captures?.size === 0) resourceCaptures.delete(fqn);
}),
).pipe(Effect.map((lines) => Effect.sync(() => lines.join("\n"))));
/**
* The runner's loggers, minus typed event records: deploys draw their
* progress through `AlchemyDeploy.applyAndRender` (the `LoggingCli` lines), so printing each
* event object too would only repeat it. `onEvent` subscribers installed
* inside still see every event. Adds the {@link resourceRecorder}.
*/
const withoutEventRecords = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
Effect.flatMap(Logger.CurrentLoggers, (loggers) =>
effect.pipe(
Effect.provideService(
Logger.CurrentLoggers,
new Set([
...[...loggers]
.filter((logger) => logger !== resourceRecorder)
.map((logger) =>
Logger.make<unknown, void>((options) => {
if (kindOf(options) !== "event") logger.log(options);
}),
),
resourceRecorder,
]),
),
),
);
/**
* Build the per-test runtime and return a self-contained Effect.
*
* Mirrors {@link "../bin/alchemy.js"} composition: ConfigProvider via
* `loadConfigProvider` + `withProfileOverride`, an empty `AuthProviders`
* registry that the user's `providers` layer populates, the platform layers,
* and the configured state store. Adapters wrap this into runner-specific
* thunks (`bun.test` -> `runPromise`, `it.live` -> as-is).
*
* When `scope` is provided, scoped resources (like the Cloudflare dev
* sidecar) survive past this effect and are tied to the lifetime of the
* provided scope instead. The runner is responsible for closing it.
*
* When `scope` is omitted, the effect runs with `Effect.scoped` and any
* scoped resources are torn down as soon as it resolves.
*/
export const toEffect = <A, ROut = any>(
effect: TestEffect<A>,
options: MakeOptions<ROut>,
scope?: Scope.Scope,
sidecar?: SidecarHandle,
): Effect.Effect<A, any, never> => {
const base = Effect.gen(function* () {
const cfg = yield* loadConfigProvider(Option.none());
const configProvider = withProfileOverride(cfg, options.profile);
// `ALCHEMY_TEST_DEV=1` forces local providers AND points the test
// process's distilled AWS clients at the emulator. Otherwise
// out-of-band `describeTable` / `getFunction` calls still hit the
// live account and fail with ResourceNotFound. Existing
// `Test.make({ dev: true })` files are unchanged (mixed
// `Alchemy.remote()` suites keep their live SDK).
const body = sidecar ? sidecar.provide(effect) : effect;
const locally = testDev ? provideTestServices(body) : body;
return yield* locally.pipe(
withoutEventRecords,
provideFreshArtifactStore,
Effect.provideService(ConfigProvider, configProvider),
Effect.provideService(StackConfigOverrides, { profile: options.profile }),
);
}).pipe(
Effect.provideService(AdoptPolicy, options.adopt ?? false),
Effect.provide(overrideAlchemyContext({ dev: resolveDev(options) })),
// `options.state` (e.g. `Cloudflare.state()`) itself requires
// `AuthProviders` to read credentials, so AuthProviders must be provided
// AFTER the state layer or the state layer's requirement is never
// satisfied — which surfaces as `Service not found: AuthProviders`.
Effect.provide(options.state ?? State.localState()),
Effect.provideService(AuthProviders, {}),
Effect.provide(Layer.provideMerge(alchemyLayer, platformLayer())),
);
return (scope === undefined ? Effect.scoped(base) : Scope.provide(base, scope)) as Effect.Effect<
A,
any,
never
>;
};
/** Promise wrapper around {@link toEffect} for `bun.test`-style runners. */
export const run = <A, ROut = any>(
effect: TestEffect<A>,
options: MakeOptions<ROut>,
scope?: Scope.Scope,
sidecar?: SidecarHandle,
): Promise<A> => Effect.runPromise(toEffect(effect, options, scope, sidecar));
/**
* Wrap an effect so it runs with `options.providers` + a placeholder Stack +
* Stage in scope. Used by `test.provider` so user code can call provider SDK
* APIs (e.g. `DynamoDB.describeTable`) directly inside the test body.
*/
export const withProviders = <A, E, R, ROut>(
effect: Effect.Effect<A, E, R>,
options: MakeOptions<ROut>,
stackName: string,
): Effect.Effect<A, E, Exclude<R, ROut | Stack | Stage>> => {
// Closest wins: when `ALCHEMY_TEST_DEV=1`, pin the test body's
// distilled AWS clients to the emulator BEFORE `options.providers`
// (which still carries the live `AWSEnvironment`).
const body = testDev ? provideTestServices(effect) : effect;
const stage = resolveStage(options);
// oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- providers layer is typed `any`; requirements are satisfied by it
return body.pipe(
Effect.provide(
(options.providers as Layer.Layer<any, never, any>).pipe(
Layer.provideMerge(
Layer.succeed(Stack, {
name: stackName,
stage,
resources: {},
bindings: {},
actions: {},
}),
),
Layer.provideMerge(Layer.succeed(Stage, stage)),
),
),
) as Effect.Effect<A, E, Exclude<R, ROut | Stack | Stage>>;
};
/**
* Curried `deploy` for the test factory: bakes in the configured stage and
* adds the telemetry layer the CLI uses, so `beforeAll(deploy(Stack))` works
* the same way as `alchemy deploy`.
*
* `scope`, when supplied, is forwarded down so the dev sidecar (and other
* scoped resources) lives until the caller closes it instead of dying as
* soon as `deploy` resolves. The test harness uses this to keep workerd
* alive across `beforeAll` → tests → `afterAll`.
*/
export interface DeployCallOptions extends Plan.MakePlanOptions {
stage?: string;
scope?: Scope.Scope;
}
export type DeployResult<A> = Effect.Effect<
Input.Resolve<A>,
Effect.Error<ReturnType<typeof deployStack<A>>>,
Effect.Services<ReturnType<typeof deployStack<A>>>
>;
export interface FilteredDeployCallOptions
extends Omit<DeployCallOptions, keyof ResourceSelection>, ResourceSelection {}
type FullDeployCall = [options?: DeployCallOptions];
/**
* Filtered deploys return void; the whole declaration still evaluates.
* With an explicit output type, filtering also requires the Call tuple type.
*/
export interface Deploy {
<A, Call extends [options?: FilteredDeployCallOptions] = FullDeployCall>(
stack: TestEffect<CompiledStack<A>, Stage | AlchemyContext>,
...call: Call
): DeployResult<SelectionOutput<A, Call[0]>>;
}
export function deploy<A, Call extends [options?: FilteredDeployCallOptions] = FullDeployCall>(
options: MakeOptions,
stack: TestEffect<CompiledStack<A>, Stage | AlchemyContext>,
...call: Call
): DeployResult<SelectionOutput<A, Call[0]>>;
export function deploy<A>(
options: MakeOptions,
stack: TestEffect<CompiledStack<A>, Stage | AlchemyContext>,
callOptions?: FilteredDeployCallOptions,
) {
return deployStack(options, stack, callOptions);
}
const deployStack = <A>(
options: MakeOptions,
stack: TestEffect<CompiledStack<A>, Stage | AlchemyContext>,
callOptions?: FilteredDeployCallOptions,
) =>
AlchemyDeploy.deploy({
stack: stack as Effect.Effect<CompiledStack<A>, never, any>,
stage: callOptions?.stage ?? resolveStage(options),
dev: resolveDev(options),
scope: callOptions?.scope,
force: callOptions?.force,
include: callOptions?.include,
exclude: callOptions?.exclude,
}).pipe(Effect.provide(TelemetryLive));
/** Bind test-file options and the shared runtime scope without erasing output types. */
export const makeDeploy = (options: MakeOptions, scope: Scope.Scope): Deploy => {
function run<A, Call extends [options?: FilteredDeployCallOptions] = FullDeployCall>(
stack: TestEffect<CompiledStack<A>, Stage | AlchemyContext>,
...call: Call
): DeployResult<SelectionOutput<A, Call[0]>>;
function run<A>(
stack: TestEffect<CompiledStack<A>, Stage | AlchemyContext>,
callOptions?: FilteredDeployCallOptions,
) {
return deployStack(options, stack, { ...callOptions, scope });
}
return run;
};
export const destroy = <ROut>(
options: MakeOptions,
stack: StackDefinition<ROut>,
callOptions?: { stage?: string; scope?: Scope.Scope; include?: never; exclude?: never },
) =>
AlchemyDestroy.destroy({
include: callOptions?.include,
exclude: callOptions?.exclude,
stack,
stage: callOptions?.stage ?? resolveStage(options),
dev: resolveDev(options),
scope: callOptions?.scope,
}).pipe(Effect.provide(TelemetryLive));
/**
* In-test scratch stack handed to `test.provider(name, (stack) => ...)`.
*
* Each scratch stack owns a private state store that is shared between
* successive `deploy`/`destroy` calls AND visible to the user's test body
* (so `yield* State` / `state.get(...)` see the same store the deploys
* mutated). This makes create / update / replace / delete paths exercisable
* without polluting other tests in the same file.
*
* When the adapter can name the test file (the alchemy-test runner), the
* store is DURABLE — rows live under `.alchemy/state/{file}-{test}/{stage}`
* on disk. Durability is what makes an interrupted destroy recoverable: the
* engine persists a `deleting` row before every `provider.delete` and only
* drops it on success, so a run killed mid-delete (e.g. the runner's
* teardown-abandonment after a test timeout) leaves resumable rows that the
* NEXT run's leading `stack.destroy()` (or the `Effect.ensuring` teardown)
* picks up and drains. An in-memory scratch dies with the process, silently
* orphaning every cloud resource whose delete was still in flight.
*/
export interface ScratchStack<ROut = any> {
readonly name: string;
/** Stage this scratch deploys to ({@link resolveStage} of the file options). */
readonly stage: string;
/** The shared in-memory state Layer for this scratch. @internal */
readonly state: Layer.Layer<State.State, never, never>;
/** Filters leave other rows and stack outputs untouched; declaration still runs. */
deploy<A, E, R, Call extends [options?: Plan.FilteredPlanOptions] = []>(
effect: Effect.Effect<A, E, R>,
...call: Call
): Effect.Effect<
SelectionOutput<Input.Resolve<A>, Call[0]>,
any,
Exclude<R, ROut | StackServices>
>;
/**
* Build a plan against the scratch's shared state WITHOUT applying it.
*
* Use this to assert on the planned action for a resource (e.g. that a
* downstream dependency stays `noop` when only an upstream resource
* changes) without mutating the cloud. Plans run against whatever state
* prior `deploy(...)` calls persisted.
*/
plan<A, E, R, Call extends [options?: Plan.FilteredPlanOptions] = []>(
effect: Effect.Effect<A, E, R>,
...call: Call
): Effect.Effect<Plan.Plan<SelectionOutput<A, Call[0]>>, any, Exclude<R, ROut | StackServices>>;
destroy(options?: { include?: never; exclude?: never }): Effect.Effect<void, any, never>;
}
const sanitizeStackName = (name: string) =>
name.replaceAll(/[^a-zA-Z0-9_]/g, "-").replace(/-+/g, "-");
/**
* Turn a test-file path (relative to the run root) into a stack-name
* namespace: `test/AWS/Website/Router.test.ts` -> `AWS/Website/Router`.
* Test names repeat across files (e.g. "create and delete bucket with
* default props"), so the durable per-test store MUST be namespaced by file
* or two concurrently-running same-named tests would read, write and — far
* worse — destroy each other's rows.
*/
const scratchNamespace = (file: string) =>
file.replace(/^test[/\\]/, "").replace(/\.test\.ts$/, "");
/**
* Build a fresh `ScratchStack` for `test.provider`.
*
* With `file` (the registration-time test file, supplied by the
* alchemy-test adapter): the store is the durable `.alchemy/state` local
* store and the stack name is namespaced by file so interrupted destroys
* leave resumable rows for the next run (see {@link ScratchStack}).
*
* Without `file` (bun/vitest adapters, which cannot name their file at
* registration time): falls back to a private in-memory store — isolated,
* but discarded with the process.
*/
export const scratchStack = <ROut>(
options: MakeOptions<ROut>,
name: string,
file?: string,
): ScratchStack<ROut> => {
const stage = resolveStage(options);
const stackName = sanitizeStackName(
file === undefined ? name : `${scratchNamespace(file)}-${name}`,
);
const stateLayer: Layer.Layer<State.State> =
file === undefined
? Layer.succeed(State.State, State.InMemoryService({}))
: Layer.provide(State.localState(), PlatformServices);
// `withProviders` already pins the test body to the test services, but the
// stack program and its later plan/apply phase run under the providers'
// live services. Pin both phases separately: Actions execute during apply,
// after the stack program has finished. This override must be inside
// `compiled.services` so Effect's closest-layer precedence selects the test
// services for Action data-plane calls.
const pinToTestServices = <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
testDev ? provideTestServices(effect) : effect;
// TODO(unify stack builds): build scratch stacks through `Alchemist.plan` /
// `Alchemist.apply` instead of `makeStack` and the hand-built destroy layers
// below (which skip the stack's secrets and auth providers); see the TODO in
// `alchemy/src/EvalStack.ts`.
const buildAndApply = (
effect: Effect.Effect<any, any, any>,
planOptions?: Plan.FilteredPlanOptions,
) =>
(pinToTestServices(effect) as Effect.Effect<any, any, never>).pipe(
makeStack({ name: stackName, providers: options.providers, state: stateLayer } as any) as any,
Effect.flatMap((compiled: any) =>
Plan.make(compiled, planOptions ?? {}).pipe(
Effect.flatMap(AlchemyDeploy.applyAndRender),
pinToTestServices,
Effect.provide(compiled.services),
),
),
Effect.provideService(Stage, stage),
provideFreshArtifactStore,
);
const buildPlan = (
effect: Effect.Effect<any, any, any>,
planOptions?: Plan.FilteredPlanOptions,
) =>
(pinToTestServices(effect) as Effect.Effect<any, any, never>).pipe(
makeStack({ name: stackName, providers: options.providers, state: stateLayer } as any) as any,
Effect.flatMap((compiled: any) =>
pinToTestServices(Plan.make(compiled, planOptions ?? {})).pipe(
Effect.provide(compiled.services),
),
),
Effect.provideService(Stage, stage),
provideFreshArtifactStore,
);
return {
name: stackName,
stage,
state: stateLayer,
deploy: ((effect: Effect.Effect<any, any, any>, planOptions?: Plan.FilteredPlanOptions) =>
buildAndApply(effect, planOptions)) as ScratchStack<ROut>["deploy"],
plan: ((effect: Effect.Effect<any, any, any>, planOptions?: Plan.FilteredPlanOptions) =>
buildPlan(effect, planOptions)) as ScratchStack<ROut>["plan"],
destroy: (callOptions) =>
callOptions?.include !== undefined || callOptions?.exclude !== undefined
? Effect.die(
new Plan.InvalidResourceSelection({ message: "Filtered destroy is not supported." }),
)
: (Plan.destroy({ name: stackName, stage }).pipe(
Effect.flatMap(AlchemyDeploy.applyAndRender),
Effect.asVoid,
Effect.provide(
stateLayer.pipe(
Layer.provideMerge(options.providers as Layer.Layer<any, never, any>),
Layer.provideMerge(
Layer.succeed(Stack, {
name: stackName,
stage,
resources: {},
bindings: {},
actions: {},
}),
),
Layer.provideMerge(Layer.succeed(Stage, stage)),
),
),
provideFreshArtifactStore,
) as Effect.Effect<void, any, never>),
};
};