/**
* The vitest-compatible registration API: `describe`, `it`/`test`, hooks and
* `layer`. Registration builds the {@link Model} tree; execution is the
* runner's job. Everything is Effect-first — plain-function tests are wrapped
* into Effects at registration time.
*/
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
import * as Layer from "effect/Layer";
import * as Scope from "effect/Scope";
import * as TestClock from "effect/testing/TestClock";
import * as TestConsole from "effect/testing/TestConsole";
import type { Exclusive, Hook, Mode, TestBody } from "./Model.ts";
import { makeSuite } from "./Model.ts";
import { currentFileSuite, currentSuite, withSuite } from "./Registry.ts";
import { mergeTags, type Tags } from "./Tags.ts";
// ---------------------------------------------------------------------------
// Shared option handling (vitest accepts `number | { timeout?: number, ... }`)
// ---------------------------------------------------------------------------
export type TestOptions =
| number
| {
/** Labels added to the tags inherited from enclosing suites. */
readonly tags?: Tags;
/** Tags that must each be explicitly named in the filter to enable this test or suite. */
readonly optInTags?: Tags;
readonly timeout?: number;
readonly retry?: number;
readonly repeats?: number;
/**
* `true` runs this test with the whole-process write lock — no other
* test in the run executes concurrently with it. Use for tests that
* mutate process-global state (e.g. `process.env.PATH`): the runner
* executes everything in ONE bun process, so such mutations are
* visible to every other running test.
*
* A label (e.g. `"hetzner"`) only serializes the test with others
* holding the same label, so unrelated tests keep running. Use it for
* a shared cloud quota.
*/
readonly exclusive?: Exclusive;
};
export const timeoutOf = (options?: TestOptions): number | undefined =>
typeof options === "number" ? options : options?.timeout;
export const retryOf = (options?: TestOptions): number | undefined =>
typeof options === "object" && options !== null ? options.retry : undefined;
export const exclusiveOf = (options?: TestOptions): Exclusive =>
typeof options === "object" && options !== null ? (options.exclusive ?? false) : false;
export const tagsOf = (options?: TestOptions): Tags | undefined =>
typeof options === "object" ? options?.tags : undefined;
export const optInTagsOf = (options?: TestOptions): Tags | undefined =>
typeof options === "object" ? options?.optInTags : undefined;
// ---------------------------------------------------------------------------
// describe
// ---------------------------------------------------------------------------
type DescribeBody = (() => void) | undefined;
export interface DescribeOptions {
/** Labels inherited by every nested suite and test. */
readonly tags?: Tags;
/** Tags that must each be explicitly named in the filter to enable this test or suite. */
readonly optInTags?: Tags;
readonly concurrent?: boolean;
readonly sequential?: boolean;
readonly timeout?: number;
}
export interface DescribeFn {
(
name: string | (() => void),
body?: DescribeBody | DescribeOptions | number,
bodyOrTimeout?: DescribeBody | number,
): void;
readonly sequential: DescribeFn;
readonly concurrent: DescribeFn;
readonly skip: DescribeFn;
readonly only: DescribeFn;
readonly todo: DescribeFn;
skipIf(condition: unknown): DescribeFn;
runIf(condition: unknown): DescribeFn;
each<T>(
cases: ReadonlyArray<T>,
): (name: string, fn: (args: T) => void, options?: TestOptions) => void;
}
interface DescribeConfig {
readonly mode: Mode;
readonly sequential: boolean;
}
const makeDescribe = (config: DescribeConfig): DescribeFn => {
const fn = (
nameOrBody: string | (() => void),
second?: DescribeBody | DescribeOptions | number,
third?: DescribeBody | number,
): void => {
// Normalize the vitest signatures:
// describe(name, body)
// describe(name, body, timeout)
// describe(name, options, body)
// describe(body) (via describe.skipIf(...)(() => {}))
let name: string;
let body: DescribeBody;
let sequential = config.sequential;
let tags: Tags | undefined;
let optInTags: Tags | undefined;
if (typeof nameOrBody === "function") {
name = "";
body = nameOrBody;
} else {
name = nameOrBody;
if (typeof second === "function") {
body = second;
} else if (typeof second === "object" && second !== null) {
tags = second.tags;
optInTags = second.optInTags;
if (second.concurrent === true || second.sequential === false) {
sequential = false;
} else if (second.concurrent === false || second.sequential === true) {
sequential = true;
}
body = typeof third === "function" ? third : undefined;
} else {
body = typeof third === "function" ? third : undefined;
}
}
const parent = currentSuite();
const suite = makeSuite(name, parent, config.mode, tags, optInTags);
suite.sequential = sequential;
parent.children.push(suite);
// `describe.skip` still collects its children (they're reported as
// skipped, matching vitest); only `todo` suites skip collection.
if (body !== undefined && config.mode !== "todo") {
withSuite(suite, body);
}
};
const withMethods = Object.assign(fn, {
each:
<T>(cases: ReadonlyArray<T>) =>
(name: string, eachBody: (args: T) => void, options?: TestOptions) => {
cases.forEach((args, index) => {
fn(
formatEachName(name, args, index),
{ tags: tagsOf(options), optInTags: optInTagsOf(options) },
() => eachBody(args),
);
});
},
skipIf: (condition: unknown) => makeDescribe(condition ? { ...config, mode: "skip" } : config),
runIf: (condition: unknown) => makeDescribe(condition ? config : { ...config, mode: "skip" }),
});
// Lazy getters — Object.assign would evaluate them eagerly and recurse
// forever (each modifier constructs another DescribeFn).
Object.defineProperties(withMethods, {
sequential: { get: () => makeDescribe({ ...config, sequential: true }) },
concurrent: { get: () => makeDescribe({ ...config, sequential: false }) },
skip: { get: () => makeDescribe({ ...config, mode: "skip" }) },
only: { get: () => makeDescribe({ ...config, mode: "only" }) },
todo: { get: () => makeDescribe({ ...config, mode: "todo" }) },
});
return withMethods as DescribeFn;
};
export const describe: DescribeFn = makeDescribe({
mode: "run",
sequential: true,
});
// ---------------------------------------------------------------------------
// Test registration primitives
// ---------------------------------------------------------------------------
export interface RegisterTestOptions {
readonly tags?: Tags;
/** Tags that must each be explicitly named in the filter to enable this test or suite. */
readonly optInTags?: Tags;
readonly name: string;
readonly mode: Mode;
readonly fails?: boolean;
readonly exclusive?: Exclusive;
readonly retry?: number | undefined;
readonly timeout?: number | undefined;
readonly body: TestBody | undefined;
}
/** Low-level test registration — used by adapters (e.g. alchemy Test.make). */
export const registerTest = (options: RegisterTestOptions): void => {
const parent = currentSuite();
parent.children.push({
type: "test",
name: options.name,
tags: mergeTags(parent.tags, options.tags),
optInTags: mergeTags(parent.optInTags, options.optInTags),
mode: options.mode,
fails: options.fails ?? false,
exclusive: options.exclusive ?? false,
retry: options.retry,
timeout: options.timeout,
body: options.body,
parent,
});
};
/** Wrap a plain (sync or async) test function into a self-contained Effect. */
const fromFn =
(fn: (ctx: TestContext) => unknown): TestBody =>
() =>
Effect.promise(async () => {
await fn(emptyContext);
});
/** Minimal stand-in for vitest's TestContext (rarely used by our tests). */
export interface TestContext {
readonly signal?: AbortSignal;
}
const emptyContext: TestContext = {};
// ---------------------------------------------------------------------------
// Effect testers (it.effect / it.live)
// ---------------------------------------------------------------------------
/**
* The environment `it.effect` provides, matching @effect/vitest: a TestClock
* and a TestConsole on top of a per-test Scope.
*/
const TestEnv = Layer.mergeAll(TestConsole.layer, TestClock.layer());
export type EffectTestFunction<R> = (ctx: TestContext) => Effect.Effect<unknown, unknown, R>;
export interface Tester<R> {
(name: string, self: EffectTestFunction<R>, options?: TestOptions): void;
skip(name: string, self: EffectTestFunction<R>, options?: TestOptions): void;
skipIf(
condition: unknown,
): (name: string, self: EffectTestFunction<R>, options?: TestOptions) => void;
runIf(
condition: unknown,
): (name: string, self: EffectTestFunction<R>, options?: TestOptions) => void;
only(name: string, self: EffectTestFunction<R>, options?: TestOptions): void;
fails(name: string, self: EffectTestFunction<R>, options?: TestOptions): void;
each<T>(
cases: ReadonlyArray<T>,
): (
name: string,
self: (args: T) => Effect.Effect<unknown, unknown, R>,
options?: TestOptions,
) => void;
}
export const makeTester = <R>(
mapEffect: (self: Effect.Effect<unknown, unknown, R>) => Effect.Effect<unknown, unknown, never>,
): Tester<R> => {
const register = (
name: string,
self: EffectTestFunction<R>,
options: TestOptions | undefined,
overrides?: Partial<RegisterTestOptions>,
) =>
registerTest({
name,
mode: "run",
timeout: timeoutOf(options),
tags: tagsOf(options),
optInTags: optInTagsOf(options),
retry: retryOf(options),
exclusive: exclusiveOf(options),
body: () => mapEffect(Effect.suspend(() => self(emptyContext))),
...overrides,
});
const fn = ((name, self, options) => register(name, self, options)) as Tester<R>;
return Object.assign(fn, {
skip: (name: string, self: EffectTestFunction<R>, options?: TestOptions) =>
register(name, self, options, { mode: "skip" }),
skipIf:
(condition: unknown) => (name: string, self: EffectTestFunction<R>, options?: TestOptions) =>
register(name, self, options, { mode: condition ? "skip" : "run" }),
runIf:
(condition: unknown) => (name: string, self: EffectTestFunction<R>, options?: TestOptions) =>
register(name, self, options, { mode: condition ? "run" : "skip" }),
only: (name: string, self: EffectTestFunction<R>, options?: TestOptions) =>
register(name, self, options, { mode: "only" }),
fails: (name: string, self: EffectTestFunction<R>, options?: TestOptions) =>
register(name, self, options, { fails: true }),
each:
<T>(cases: ReadonlyArray<T>) =>
(
name: string,
self: (args: T) => Effect.Effect<unknown, unknown, R>,
options?: TestOptions,
) => {
cases.forEach((args, index) => {
register(formatEachName(name, args, index), () => self(args), options);
});
},
});
};
const formatEachName = (name: string, args: unknown, index: number): string => {
let out = name;
// `$prop` templating (vitest): "Container (dev: $dev)"
if (out.includes("$") && typeof args === "object" && args !== null) {
out = out.replace(/\$([a-zA-Z_$][\w.$]*)/g, (match, path: string) => {
const value = path
.split(".")
.reduce<unknown>(
(acc, key) =>
acc !== null && typeof acc === "object"
? (acc as Record<string, unknown>)[key]
: undefined,
args,
);
return value === undefined ? match : String(value);
});
}
// printf-style templating: "adds %s"
if (out.includes("%")) {
out = out.replace(/%[sdifjo#]/g, () =>
typeof args === "object" ? JSON.stringify(args) : String(args),
);
}
return out === name ? `${name} [${index}]` : out;
};
// ---------------------------------------------------------------------------
// it / test
// ---------------------------------------------------------------------------
export interface TestFn {
(name: string, fn?: (ctx: TestContext) => unknown, options?: TestOptions): void;
skip(name: string, fn?: (ctx: TestContext) => unknown, options?: TestOptions): void;
only(name: string, fn?: (ctx: TestContext) => unknown, options?: TestOptions): void;
todo(name: string, fn?: (ctx: TestContext) => unknown, options?: TestOptions): void;
fails(name: string, fn?: (ctx: TestContext) => unknown, options?: TestOptions): void;
skipIf(
condition: unknown,
): (name: string, fn?: (ctx: TestContext) => unknown, options?: TestOptions) => void;
runIf(
condition: unknown,
): (name: string, fn?: (ctx: TestContext) => unknown, options?: TestOptions) => void;
each<T>(
cases: ReadonlyArray<T>,
): (name: string, fn: (args: T) => unknown, options?: TestOptions) => void;
/** Effect tester with TestClock + TestConsole (matches @effect/vitest). */
readonly effect: Tester<Scope.Scope | TestClock.TestClock | TestConsole.TestConsole>;
/** Effect tester against the live environment (scope only). */
readonly live: Tester<Scope.Scope>;
}
const registerFnTest = (
name: string,
fn: ((ctx: TestContext) => unknown) | undefined,
options: TestOptions | undefined,
mode: Mode,
fails = false,
): void =>
registerTest({
name,
mode: fn === undefined ? "todo" : mode,
fails,
timeout: timeoutOf(options),
tags: tagsOf(options),
optInTags: optInTagsOf(options),
retry: retryOf(options),
exclusive: exclusiveOf(options),
body: fn === undefined ? undefined : fromFn(fn),
});
const makeTestFn = (): TestFn => {
const fn = ((name, body, options) => registerFnTest(name, body, options, "run")) as TestFn;
return Object.assign(fn, {
skip: (name: string, body?: (ctx: TestContext) => unknown, options?: TestOptions) =>
registerFnTest(name, body, options, "skip"),
only: (name: string, body?: (ctx: TestContext) => unknown, options?: TestOptions) =>
registerFnTest(name, body, options, "only"),
todo: (name: string, body?: (ctx: TestContext) => unknown, options?: TestOptions) =>
registerFnTest(name, body, options, "todo"),
fails: (name: string, body?: (ctx: TestContext) => unknown, options?: TestOptions) =>
registerFnTest(name, body, options, "run", true),
skipIf:
(condition: unknown) =>
(name: string, body?: (ctx: TestContext) => unknown, options?: TestOptions) =>
registerFnTest(name, body, options, condition ? "skip" : "run"),
runIf:
(condition: unknown) =>
(name: string, body?: (ctx: TestContext) => unknown, options?: TestOptions) =>
registerFnTest(name, body, options, condition ? "run" : "skip"),
each:
<T>(cases: ReadonlyArray<T>) =>
(name: string, body: (args: T) => unknown, options?: TestOptions) => {
cases.forEach((args, index) => {
registerFnTest(formatEachName(name, args, index), () => body(args), options, "run");
});
},
effect: makeTester<Scope.Scope | TestClock.TestClock | TestConsole.TestConsole>(
(self) =>
self.pipe(Effect.scoped, Effect.provide(TestEnv)) as Effect.Effect<unknown, unknown, never>,
),
live: makeTester<Scope.Scope>((self) => Effect.scoped(self)),
});
};
export const it: TestFn = makeTestFn();
export const test: TestFn = it;
// ---------------------------------------------------------------------------
// Hooks
// ---------------------------------------------------------------------------
export type HookKind = "beforeAll" | "afterAll" | "beforeEach" | "afterEach";
/** Framework cleanup after user teardown, including files with no runnable tests. */
export const registerFileCleanup = (hook: Hook): void => {
currentFileSuite().cleanups.push(hook);
};
/** Low-level hook registration with an Effect body — used by adapters. */
export const registerHook = (kind: HookKind, hook: Hook): void => {
currentSuite()[kind].push(hook);
};
const hookFromFn =
(fn: () => unknown): Hook["body"] =>
() =>
Effect.promise(async () => {
await fn();
});
export const beforeAll = (fn: () => unknown, timeout?: number): void =>
registerHook("beforeAll", { body: hookFromFn(fn), timeout });
export const afterAll = (fn: () => unknown, timeout?: number): void =>
registerHook("afterAll", { body: hookFromFn(fn), timeout });
export const beforeEach = (fn: () => unknown, timeout?: number): void =>
registerHook("beforeEach", { body: hookFromFn(fn), timeout });
export const afterEach = (fn: () => unknown, timeout?: number): void =>
registerHook("afterEach", { body: hookFromFn(fn), timeout });
// ---------------------------------------------------------------------------
// layer — share a Layer across the tests of a block (@effect/vitest parity)
// ---------------------------------------------------------------------------
export interface LayerMethods<R> {
effect: Tester<R | Scope.Scope | TestClock.TestClock | TestConsole.TestConsole>;
layer<R2, E2>(
nested: Layer.Layer<R2, E2, R>,
options?: { readonly timeout?: number },
): {
(f: (it: LayerMethods<R | R2>) => void): void;
(name: string, f: (it: LayerMethods<R | R2>) => void): void;
};
}
export const layer =
<R, E>(
layer_: Layer.Layer<R, E>,
options?: {
readonly memoMap?: Layer.MemoMap;
readonly timeout?: number;
readonly excludeTestServices?: boolean;
},
): {
(f: (it: LayerMethods<R>) => void): void;
(name: string, f: (it: LayerMethods<R>) => void): void;
} =>
(
...args: [name: string, f: (it: LayerMethods<R>) => void] | [f: (it: LayerMethods<R>) => void]
): void => {
const excludeTestServices = options?.excludeTestServices ?? false;
const withTestEnv = excludeTestServices
? (layer_ as Layer.Layer<R, E>)
: Layer.provideMerge(layer_, TestEnv);
const memoMap = options?.memoMap ?? Effect.runSync(Layer.makeMemoMap);
const scope = Scope.makeUnsafe();
const contextEffect = Layer.buildWithMemoMap(withTestEnv, memoMap, scope).pipe(
Effect.orDie,
Effect.cached,
Effect.runSync,
);
const makeMethods = (): LayerMethods<R> => ({
effect: makeTester<R | Scope.Scope | TestClock.TestClock | TestConsole.TestConsole>(
(self) =>
Effect.flatMap(contextEffect, (context) =>
self.pipe(Effect.scoped, Effect.provide(context)),
) as Effect.Effect<unknown, unknown, never>,
),
layer: (nested, nestedOptions) =>
layer(Layer.provideMerge(nested, withTestEnv) as Layer.Layer<any, any>, {
...nestedOptions,
memoMap: Layer.forkMemoMapUnsafe(memoMap),
excludeTestServices,
}) as any,
});
const register = (): void => {
const cleanup: Hook = {
body: () => Scope.close(scope, Exit.void),
timeout: options?.timeout,
};
registerHook("afterAll", cleanup);
registerFileCleanup(cleanup);
const f = (args.length === 1 ? args[0] : args[1]) as (it: LayerMethods<R>) => void;
f(makeMethods());
};
if (args.length === 2) {
describe(args[0], register);
} else {
register();
}
};