@glubean/sdk 0.2.0 → 0.2.2

package/dist/test/each-builder.d.ts

@@ -0,0 +1,244 @@
+/**
+ * @module each-builder
+ *
+ * Data-driven builder for multi-step tests (`EachBuilder`).
+ *
+ * Entry point: `test.each(table)("id-$key")` (no callback) returns an `EachBuilder`.
+ * Same fluent API as `TestBuilder`, but each step/setup/teardown also receives
+ * the data row (`row`) as a third argument. One `Test` is generated per row.
+ * Also exports `EachStepFunction`, `EachSetupFunction`, `EachTeardownFunction` types.
+ */
+import type { ExtensionFn, StepMeta, Test, TestContext, TestMeta } from "../types.js";
+/**
+ * Step function for data-driven builder tests.
+ * Receives context, current state, and the data row for this test.
+ *
+ * @template S The state type passed between steps
+ * @template T The data row type
+ * @template Ctx The context type (defaults to TestContext)
+ *
+ * @example
+ * ```ts
+ * const stepFn: EachStepFunction<{ token: string }, { userId: number }> =
+ *   async (ctx, state, row) => {
+ *     const res = await ctx.http.get(`/users/${row.userId}`);
+ *     ctx.assert(res.ok, `user ${row.userId} found`);
+ *     return state; // pass state to next step
+ *   };
+ * ```
+ */
+export type EachStepFunction<S, T, Ctx extends TestContext = TestContext> = (ctx: Ctx, state: S, row: T) => Promise<S | void>;
+/**
+ * Setup function for data-driven builder tests.
+ * Receives context and the data row, returns initial state.
+ *
+ * @template S The state type to return
+ * @template T The data row type
+ * @template Ctx The context type (defaults to TestContext)
+ *
+ * @example
+ * ```ts
+ * const setupFn: EachSetupFunction<{ api: HttpClient }, { env: string }> =
+ *   async (ctx, row) => {
+ *     const api = ctx.http.extend({ prefixUrl: row.env });
+ *     return { api };
+ *   };
+ * ```
+ */
+export type EachSetupFunction<S, T, Ctx extends TestContext = TestContext> = (ctx: Ctx, row: T) => Promise<S>;
+/**
+ * Teardown function for data-driven builder tests.
+ *
+ * @template S The state type received from setup
+ * @template T The data row type
+ * @template Ctx The context type (defaults to TestContext)
+ *
+ * @example
+ * ```ts
+ * const teardownFn: EachTeardownFunction<{ sessionId: string }, { userId: number }> =
+ *   async (ctx, state, row) => {
+ *     await ctx.http.delete(`/sessions/${state.sessionId}`);
+ *     ctx.log(`cleaned up session for user ${row.userId}`);
+ *   };
+ * ```
+ */
+export type EachTeardownFunction<S, T, Ctx extends TestContext = TestContext> = (ctx: Ctx, state: S, row: T) => Promise<void>;
+/**
+ * Builder for data-driven tests with multi-step workflow support.
+ *
+ * Created by `test.each(table)(idTemplate)` (without a callback).
+ * Provides the same fluent `.step()` / `.setup()` / `.teardown()` API
+ * as `TestBuilder`, but each step/setup/teardown also receives the
+ * data row for the current test.
+ *
+ * On finalization, creates one `Test` per row in the table, each with
+ * full step definitions visible in `glubean scan` metadata and dashboards.
+ *
+ * @template S The state type for multi-step tests
+ * @template T The data row type
+ *
+ * @example
+ * ```ts
+ * export const userFlows = test.each([
+ *   { userId: 1 },
+ *   { userId: 2 },
+ * ])("user-flow-$userId")
+ *   .step("fetch user", async (ctx, state, { userId }) => {
+ *     const res = await ctx.http.get(`/users/${userId}`);
+ *     ctx.assert(res.ok, "user exists");
+ *     return { user: await res.json() };
+ *   })
+ *   .step("verify posts", async (ctx, { user }) => {
+ *     const res = await ctx.http.get(`/users/${user.id}/posts`);
+ *     ctx.assert(res.ok, "posts accessible");
+ *   });
+ * ```
+ */
+export declare class EachBuilder<S = unknown, T extends Record<string, unknown> = Record<string, unknown>, Ctx extends TestContext = TestContext> {
+    private _baseMeta;
+    private _table;
+    private _setup?;
+    private _teardown?;
+    private _steps;
+    private _built;
+    private _parallel;
+    _fixtures?: Record<string, ExtensionFn<any>>;
+    /**
+     * Marker property so the runner and scanner can detect EachBuilder exports.
+     */
+    readonly __glubean_type: "each-builder";
+    constructor(baseMeta: TestMeta, table: readonly T[], fixtures?: Record<string, ExtensionFn<any>>, parallel?: boolean);
+    /**
+     * Set additional metadata for all generated tests.
+     *
+     * @example
+     * ```ts
+     * test.each(table)("user-$userId")
+     *   .meta({ tags: ["smoke"], timeout: 10000 })
+     *   .step("fetch", async (ctx, state, row) => { ... });
+     * ```
+     */
+    meta(meta: Omit<TestMeta, "id">): EachBuilder<S, T, Ctx>;
+    /**
+     * Mark all generated tests from this data set as focused.
+     * If `skip` is also set, skipped tests are still excluded.
+     */
+    only(): EachBuilder<S, T, Ctx>;
+    /**
+     * Mark all generated tests from this data set as skipped.
+     * Skip takes precedence over `only` when both are present.
+     */
+    skip(): EachBuilder<S, T, Ctx>;
+    /**
+     * Set the setup function. Receives context and data row, returns state.
+     *
+     * @example
+     * ```ts
+     * test.each(table)("id-$key")
+     *   .setup(async (ctx, row) => {
+     *     const api = ctx.http.extend({ headers: { "X-User": row.userId } });
+     *     return { api };
+     *   })
+     *   .step("use api", async (ctx, { api }) => { ... });
+     * ```
+     */
+    setup<NewS>(fn: (ctx: Ctx, row: T) => Promise<NewS>): EachBuilder<NewS, T, Ctx>;
+    /**
+     * Set the teardown function. Runs after all steps (even on failure).
+     *
+     * @example
+     * ```ts
+     * test.each(table)("user-$userId")
+     *   .setup(async (ctx, row) => ({ token: await login(ctx, row) }))
+     *   .step("test", async (ctx, { token }) => { ... })
+     *   .teardown(async (ctx, state, row) => {
+     *     await ctx.http.post("/logout", { body: { token: state.token } });
+     *   });
+     * ```
+     */
+    teardown(fn: (ctx: Ctx, state: S, row: T) => Promise<void>): EachBuilder<S, T, Ctx>;
+    /**
+     * Add a step that does not return state (void).
+     *
+     * @example
+     * ```ts
+     * test.each(users)("user-$id")
+     *   .step("verify", async (ctx, state, row) => {
+     *     const res = await ctx.http.get(`/users/${row.id}`);
+     *     ctx.expect(res.status).toBe(200);
+     *   });
+     * ```
+     */
+    step(name: string, fn: (ctx: Ctx, state: S, row: T) => Promise<void>): EachBuilder<S, T, Ctx>;
+    /**
+     * Add a step that returns new state, replacing the current state type.
+     */
+    step<NewS>(name: string, fn: (ctx: Ctx, state: S, row: T) => Promise<NewS>): EachBuilder<NewS, T, Ctx>;
+    /**
+     * Add a step with options (void return).
+     */
+    step(name: string, options: Omit<StepMeta, "name">, fn: (ctx: Ctx, state: S, row: T) => Promise<void>): EachBuilder<S, T, Ctx>;
+    /**
+     * Add a step with options, returning new state.
+     */
+    step<NewS>(name: string, options: Omit<StepMeta, "name">, fn: (ctx: Ctx, state: S, row: T) => Promise<NewS>): EachBuilder<NewS, T, Ctx>;
+    /**
+     * Apply a builder transform function for step composition.
+     *
+     * Works the same as `TestBuilder.use()` — reusable step sequences
+     * are plain functions that take a builder and return a builder.
+     *
+     * @param fn Transform function that receives this builder and returns a (possibly re-typed) builder
+     *
+     * @example
+     * ```ts
+     * const withVerify = (b: EachBuilder<{ id: string }, { userId: number }>) => b
+     *   .step("verify", async (ctx, { id }, row) => {
+     *     ctx.expect(id).toBeTruthy();
+     *   });
+     *
+     * export const users = test.each(table)("user-$userId")
+     *   .setup(async (ctx, row) => ({ id: String(row.userId) }))
+     *   .use(withVerify);
+     * ```
+     */
+    use<NewS>(fn: (builder: EachBuilder<S, T, Ctx>) => EachBuilder<NewS, T, Ctx>): EachBuilder<NewS, T, Ctx>;
+    /**
+     * Apply a builder transform and tag all newly added steps with a group ID.
+     *
+     * Works the same as `TestBuilder.group()` — steps added by `fn` are marked
+     * with `group` metadata for visual grouping in reports.
+     *
+     * @param id Group identifier (displayed in reports as a section header)
+     * @param fn Transform function that adds steps to the builder
+     *
+     * @example
+     * ```ts
+     * export const users = test.each(table)("user-$userId")
+     *   .group("setup", b => b
+     *     .step("init", async (ctx, state, row) => ({ id: String(row.userId) }))
+     *   )
+     *   .step("verify", async (ctx, { id }) => { ... });
+     * ```
+     */
+    group<NewS>(id: string, fn: (builder: EachBuilder<S, T, Ctx>) => EachBuilder<NewS, T, Ctx>): EachBuilder<NewS, T, Ctx>;
+    /** @internal */
+    private _filteredTable;
+    /** @internal */
+    private _tagsForRow;
+    /**
+     * Finalize and register all tests in the global registry.
+     * Called automatically via microtask if not explicitly invoked via build().
+     * Idempotent — safe to call multiple times.
+     * @internal
+     */
+    private _finalize;
+    /**
+     * Build and register all tests. Returns a `Test[]` array.
+     *
+     * **Optional** — if omitted, the builder auto-finalizes via microtask
+     * and the runner will auto-detect the EachBuilder export.
+     */
+    build(): Test<S>[];
+}
+//# sourceMappingURL=each-builder.d.ts.map

package/dist/test/each-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"each-builder.d.ts","sourceRoot":"","sources":["../../src/test/each-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EACV,WAAW,EAGX,QAAQ,EAER,IAAI,EACJ,WAAW,EACX,QAAQ,EACT,MAAM,aAAa,CAAC;AAKrB;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,SAAS,WAAW,GAAG,WAAW,IAAI,CAC1E,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,CAAC,EACR,GAAG,EAAE,CAAC,KACH,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;AAEvB;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,SAAS,WAAW,GAAG,WAAW,IAAI,CAC3E,GAAG,EAAE,GAAG,EACR,GAAG,EAAE,CAAC,KACH,OAAO,CAAC,CAAC,CAAC,CAAC;AAEhB;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,oBAAoB,CAC9B,CAAC,EACD,CAAC,EACD,GAAG,SAAS,WAAW,GAAG,WAAW,IACnC,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,WAAW,CACtB,CAAC,GAAG,OAAO,EACX,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3D,GAAG,SAAS,WAAW,GAAG,WAAW;IAErC,OAAO,CAAC,SAAS,CAAW;IAC5B,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,MAAM,CAAC,CAA+B;IAC9C,OAAO,CAAC,SAAS,CAAC,CAAkC;IAEpD,OAAO,CAAC,MAAM,CAA+D;IAC7E,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAU;IAE3B,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;IAE7C;;OAEG;IACH,QAAQ,CAAC,cAAc,EAAG,cAAc,CAAU;gBAGhD,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,EAC3C,QAAQ,UAAQ;IAUlB;;;;;;;;;OASG;IACH,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC;IAKxD;;;OAGG;IACH,IAAI,IAAI,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC;IAK9B;;;OAGG;IACH,IAAI,IAAI,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC;IAK9B;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,IAAI,EACR,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GACtC,WAAW,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC;IAK5B;;;;;;;;;;;;OAYG;IACH,QAAQ,CACN,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAChD,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC;IAKzB;;;;;;;;;;;OAWG;IACH,IAAI,CACF,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAChD,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC;IACzB;;OAEG;IACH,IAAI,CAAC,IAAI,EACP,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAChD,WAAW,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC;IAC5B;;OAEG;IACH,IAAI,CACF,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,EAC/B,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAChD,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC;IACzB;;OAEG;IACH,IAAI,CAAC,IAAI,EACP,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,EAC/B,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAChD,WAAW,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC;IAmB5B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,GAAG,CAAC,IAAI,EACN,EAAE,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,KAAK,WAAW,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,GACjE,WAAW,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC;IAI5B;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CAAC,IAAI,EACR,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,KAAK,WAAW,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,GACjE,WAAW,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC;IAS5B,gBAAgB;IAChB,OAAO,CAAC,cAAc;IAMtB,gBAAgB;IAChB,OAAO,CAAC,WAAW;IAYnB;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IA+BjB;;;;;OAKG;IACH,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE;CAiCnB"}

package/dist/test/each-builder.js

@@ -0,0 +1,268 @@
+import { registerTest } from "../internal.js";
+import { toArray } from "../data.js";
+import { interpolateTemplate } from "./utils.js";
+/**
+ * Builder for data-driven tests with multi-step workflow support.
+ *
+ * Created by `test.each(table)(idTemplate)` (without a callback).
+ * Provides the same fluent `.step()` / `.setup()` / `.teardown()` API
+ * as `TestBuilder`, but each step/setup/teardown also receives the
+ * data row for the current test.
+ *
+ * On finalization, creates one `Test` per row in the table, each with
+ * full step definitions visible in `glubean scan` metadata and dashboards.
+ *
+ * @template S The state type for multi-step tests
+ * @template T The data row type
+ *
+ * @example
+ * ```ts
+ * export const userFlows = test.each([
+ *   { userId: 1 },
+ *   { userId: 2 },
+ * ])("user-flow-$userId")
+ *   .step("fetch user", async (ctx, state, { userId }) => {
+ *     const res = await ctx.http.get(`/users/${userId}`);
+ *     ctx.assert(res.ok, "user exists");
+ *     return { user: await res.json() };
+ *   })
+ *   .step("verify posts", async (ctx, { user }) => {
+ *     const res = await ctx.http.get(`/users/${user.id}/posts`);
+ *     ctx.assert(res.ok, "posts accessible");
+ *   });
+ * ```
+ */
+export class EachBuilder {
+    _baseMeta;
+    _table;
+    _setup;
+    _teardown;
+    _steps = [];
+    _built = false;
+    _parallel;
+    _fixtures;
+    /**
+     * Marker property so the runner and scanner can detect EachBuilder exports.
+     */
+    __glubean_type = "each-builder";
+    constructor(baseMeta, table, fixtures, parallel = false) {
+        this._baseMeta = baseMeta;
+        this._table = table;
+        this._fixtures = fixtures;
+        this._parallel = parallel;
+        // Auto-finalize after all synchronous chaining completes.
+        queueMicrotask(() => this._finalize());
+    }
+    /**
+     * Set additional metadata for all generated tests.
+     *
+     * @example
+     * ```ts
+     * test.each(table)("user-$userId")
+     *   .meta({ tags: ["smoke"], timeout: 10000 })
+     *   .step("fetch", async (ctx, state, row) => { ... });
+     * ```
+     */
+    meta(meta) {
+        this._baseMeta = { ...this._baseMeta, ...meta };
+        return this;
+    }
+    /**
+     * Mark all generated tests from this data set as focused.
+     * If `skip` is also set, skipped tests are still excluded.
+     */
+    only() {
+        this._baseMeta = { ...this._baseMeta, only: true };
+        return this;
+    }
+    /**
+     * Mark all generated tests from this data set as skipped.
+     * Skip takes precedence over `only` when both are present.
+     */
+    skip() {
+        this._baseMeta = { ...this._baseMeta, skip: true };
+        return this;
+    }
+    /**
+     * Set the setup function. Receives context and data row, returns state.
+     *
+     * @example
+     * ```ts
+     * test.each(table)("id-$key")
+     *   .setup(async (ctx, row) => {
+     *     const api = ctx.http.extend({ headers: { "X-User": row.userId } });
+     *     return { api };
+     *   })
+     *   .step("use api", async (ctx, { api }) => { ... });
+     * ```
+     */
+    setup(fn) {
+        this._setup = fn;
+        return this;
+    }
+    /**
+     * Set the teardown function. Runs after all steps (even on failure).
+     *
+     * @example
+     * ```ts
+     * test.each(table)("user-$userId")
+     *   .setup(async (ctx, row) => ({ token: await login(ctx, row) }))
+     *   .step("test", async (ctx, { token }) => { ... })
+     *   .teardown(async (ctx, state, row) => {
+     *     await ctx.http.post("/logout", { body: { token: state.token } });
+     *   });
+     * ```
+     */
+    teardown(fn) {
+        this._teardown = fn;
+        return this;
+    }
+    step(name, optionsOrFn, maybeFn) {
+        const fn = typeof optionsOrFn === "function" ? optionsOrFn : maybeFn;
+        const options = typeof optionsOrFn === "function" ? {} : optionsOrFn;
+        this._steps.push({
+            meta: { name, ...options },
+            fn,
+        });
+        return this;
+    }
+    /**
+     * Apply a builder transform function for step composition.
+     *
+     * Works the same as `TestBuilder.use()` — reusable step sequences
+     * are plain functions that take a builder and return a builder.
+     *
+     * @param fn Transform function that receives this builder and returns a (possibly re-typed) builder
+     *
+     * @example
+     * ```ts
+     * const withVerify = (b: EachBuilder<{ id: string }, { userId: number }>) => b
+     *   .step("verify", async (ctx, { id }, row) => {
+     *     ctx.expect(id).toBeTruthy();
+     *   });
+     *
+     * export const users = test.each(table)("user-$userId")
+     *   .setup(async (ctx, row) => ({ id: String(row.userId) }))
+     *   .use(withVerify);
+     * ```
+     */
+    use(fn) {
+        return fn(this);
+    }
+    /**
+     * Apply a builder transform and tag all newly added steps with a group ID.
+     *
+     * Works the same as `TestBuilder.group()` — steps added by `fn` are marked
+     * with `group` metadata for visual grouping in reports.
+     *
+     * @param id Group identifier (displayed in reports as a section header)
+     * @param fn Transform function that adds steps to the builder
+     *
+     * @example
+     * ```ts
+     * export const users = test.each(table)("user-$userId")
+     *   .group("setup", b => b
+     *     .step("init", async (ctx, state, row) => ({ id: String(row.userId) }))
+     *   )
+     *   .step("verify", async (ctx, { id }) => { ... });
+     * ```
+     */
+    group(id, fn) {
+        const before = this._steps.length;
+        const result = fn(this);
+        for (let i = before; i < this._steps.length; i++) {
+            this._steps[i].meta.group = id;
+        }
+        return result;
+    }
+    /** @internal */
+    _filteredTable() {
+        const filter = this._baseMeta.filter;
+        if (!filter)
+            return this._table;
+        return this._table.filter((row, index) => filter(row, index));
+    }
+    /** @internal */
+    _tagsForRow(row) {
+        const staticTags = toArray(this._baseMeta.tags);
+        const tagFieldNames = toArray(this._baseMeta.tagFields);
+        const dynamicTags = tagFieldNames
+            .map((field) => {
+            const value = row[field];
+            return value != null ? `${field}:${value}` : null;
+        })
+            .filter((t) => t !== null);
+        return [...staticTags, ...dynamicTags];
+    }
+    /**
+     * Finalize and register all tests in the global registry.
+     * Called automatically via microtask if not explicitly invoked via build().
+     * Idempotent — safe to call multiple times.
+     * @internal
+     */
+    _finalize() {
+        if (this._built)
+            return;
+        this._built = true;
+        const stepMetas = this._steps.map((s) => ({
+            name: s.meta.name,
+            ...(s.meta.group ? { group: s.meta.group } : {}),
+        }));
+        const table = this._filteredTable();
+        const isPick = table.length > 0 && "_pick" in table[0];
+        const hasGroup = isPick || this._parallel;
+        for (let i = 0; i < table.length; i++) {
+            const row = table[i];
+            const id = interpolateTemplate(this._baseMeta.id, row, i);
+            const name = this._baseMeta.name ? interpolateTemplate(this._baseMeta.name, row, i) : id;
+            registerTest({
+                id,
+                name,
+                type: "steps",
+                tags: this._tagsForRow(row),
+                description: this._baseMeta.description,
+                steps: stepMetas,
+                hasSetup: !!this._setup,
+                hasTeardown: !!this._teardown,
+                ...(hasGroup ? { groupId: this._baseMeta.id } : {}),
+                ...(this._parallel ? { parallel: true } : {}),
+            });
+        }
+    }
+    /**
+     * Build and register all tests. Returns a `Test[]` array.
+     *
+     * **Optional** — if omitted, the builder auto-finalizes via microtask
+     * and the runner will auto-detect the EachBuilder export.
+     */
+    build() {
+        this._finalize();
+        const table = this._filteredTable();
+        return table.map((row, index) => {
+            const id = interpolateTemplate(this._baseMeta.id, row, index);
+            const name = this._baseMeta.name ? interpolateTemplate(this._baseMeta.name, row, index) : id;
+            const meta = {
+                ...this._baseMeta,
+                id,
+                name,
+                tags: this._tagsForRow(row),
+            };
+            const setup = this._setup;
+            const teardown = this._teardown;
+            return {
+                meta,
+                type: "steps",
+                setup: setup ? ((ctx) => setup(ctx, row)) : undefined,
+                teardown: teardown
+                    ? ((ctx, state) => teardown(ctx, state, row))
+                    : undefined,
+                steps: this._steps.map((s) => ({
+                    meta: s.meta,
+                    fn: ((ctx, state) => s.fn(ctx, state, row)),
+                })),
+                ...(this._fixtures ? { fixtures: this._fixtures } : {}),
+            };
+        });
+    }
+}
+//# sourceMappingURL=each-builder.js.map

package/dist/test/each-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"each-builder.js","sourceRoot":"","sources":["../../src/test/each-builder.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAsEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,OAAO,WAAW;IAKd,SAAS,CAAW;IACpB,MAAM,CAAe;IACrB,MAAM,CAAgC;IACtC,SAAS,CAAmC;IAE5C,MAAM,GAA4D,EAAE,CAAC;IACrE,MAAM,GAAG,KAAK,CAAC;IACf,SAAS,CAAU;IAE3B,SAAS,CAAoC;IAE7C;;OAEG;IACM,cAAc,GAAG,cAAuB,CAAC;IAElD,YACE,QAAkB,EAClB,KAAmB,EACnB,QAA2C,EAC3C,QAAQ,GAAG,KAAK;QAEhB,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC1B,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC1B,0DAA0D;QAC1D,cAAc,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;IACzC,CAAC;IAED;;;;;;;;;OASG;IACH,IAAI,CAAC,IAA0B;QAC7B,IAAI,CAAC,SAAS,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,EAAE,GAAG,IAAI,EAAE,CAAC;QAChD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACH,IAAI;QACF,IAAI,CAAC,SAAS,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QACnD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACH,IAAI;QACF,IAAI,CAAC,SAAS,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QACnD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CACH,EAAuC;QAEtC,IAA6C,CAAC,MAAM,GAAG,EAAgD,CAAC;QACzG,OAAO,IAA4C,CAAC;IACtD,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,QAAQ,CACN,EAAiD;QAEjD,IAAI,CAAC,SAAS,GAAG,EAAgD,CAAC;QAClE,OAAO,IAAI,CAAC;IACd,CAAC;IAyCD,IAAI,CACF,IAAY,EACZ,WAEoD,EACpD,OAAwD;QAExD,MAAM,EAAE,GAAG,OAAO,WAAW,KAAK,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,OAAQ,CAAC;QACtE,MAAM,OAAO,GAAG,OAAO,WAAW,KAAK,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAE,WAAwB,CAAC;QAEnF,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE;YAC1B,EAAE;SACH,CAAC,CAAC;QAEH,OAAO,IAAgC,CAAC;IAC1C,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,GAAG,CACD,EAAkE;QAElE,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CACH,EAAU,EACV,EAAkE;QAElE,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;QAClC,MAAM,MAAM,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;QACxB,KAAK,IAAI,CAAC,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACjD,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;QACjC,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,gBAAgB;IACR,cAAc;QACpB,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;QACrC,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC,MAAM,CAAC;QAChC,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,GAA8B,EAAE,KAAK,CAAC,CAAC,CAAC;IAC3F,CAAC;IAED,gBAAgB;IACR,WAAW,CAAC,GAAM;QACxB,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAChD,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QACxD,MAAM,WAAW,GAAG,aAAa;aAC9B,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;YACb,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC;YACzB,OAAO,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QACpD,CAAC,CAAC;aACD,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;QAC1C,OAAO,CAAC,GAAG,UAAU,EAAE,GAAG,WAAW,CAAC,CAAC;IACzC,CAAC;IAED;;;;;OAKG;IACK,SAAS;QACf,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACxB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QAEnB,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACxC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI;YACjB,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACjD,CAAC,CAAC,CAAC;QACJ,MAAM,KAAK,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;QACpC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC;QACvD,MAAM,QAAQ,GAAG,MAAM,IAAI,IAAI,CAAC,SAAS,CAAC;QAC1C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YACrB,MAAM,EAAE,GAAG,mBAAmB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;YAC1D,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,mBAAmB,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAEzF,YAAY,CAAC;gBACX,EAAE;gBACF,IAAI;gBACJ,IAAI,EAAE,OAAO;gBACb,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC;gBAC3B,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,WAAW;gBACvC,KAAK,EAAE,SAAS;gBAChB,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM;gBACvB,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS;gBAC7B,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACnD,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC9C,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,KAAK;QACH,IAAI,CAAC,SAAS,EAAE,CAAC;QAEjB,MAAM,KAAK,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;QACpC,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;YAC9B,MAAM,EAAE,GAAG,mBAAmB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;YAC9D,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,mBAAmB,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAE7F,MAAM,IAAI,GAAa;gBACrB,GAAG,IAAI,CAAC,SAAS;gBACjB,EAAE;gBACF,IAAI;gBACJ,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC;aAC5B,CAAC;YAEF,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC;YAC1B,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;YAEhC,OAAO;gBACL,IAAI;gBACJ,IAAI,EAAE,OAAgB;gBACtB,KAAK,EAAE,KAAK,CAAC,CAAC,CAAE,CAAC,CAAC,GAAgB,EAAE,EAAE,CAAC,KAAK,CAAC,GAAU,EAAE,GAAG,CAAC,CAAsB,CAAC,CAAC,CAAC,SAAS;gBAC/F,QAAQ,EAAE,QAAQ;oBAChB,CAAC,CAAE,CAAC,CAAC,GAAgB,EAAE,KAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAU,EAAE,KAAK,EAAE,GAAG,CAAC,CAAyB;oBAC7F,CAAC,CAAC,SAAS;gBACb,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBAC7B,IAAI,EAAE,CAAC,CAAC,IAAI;oBACZ,EAAE,EAAE,CAAC,CAAC,GAAgB,EAAE,KAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,GAAU,EAAE,KAAK,EAAE,GAAG,CAAC,CAAoB;iBACtF,CAAC,CAAC;gBACH,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACxD,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/test/extend.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @module test-extend
+ *
+ * Fixture extension system for augmenting `TestContext` (`test.extend()`).
+ *
+ * `test.extend(fixtures)` returns an `ExtendedTest` function whose `ctx`
+ * includes the resolved fixture properties alongside the base `TestContext`.
+ * Supports chained `.extend()`, `.each()`, and `.pick()`.
+ * Also exports the `ExtendedTest` interface and `EachOptions`.
+ */
+import type { ExtensionFn, ResolveExtensions, Test, TestContext, TestMeta } from "../types.js";
+import { TestBuilder } from "./builder.js";
+import { EachBuilder } from "./each-builder.js";
+/** Keys that cannot be used as extension names (they shadow core TestContext). */
+export declare const EXTEND_RESERVED_KEYS: Set<string>;
+/**
+ * An extended `test` function created by `test.extend()`.
+ *
+ * Behaves identically to the base `test()` but augments the context type
+ * with fixture properties. Supports quick mode, builder mode, `.each()`,
+ * `.pick()`, and chained `.extend()`.
+ *
+ * @template Ctx The augmented context type (TestContext & extensions)
+ */
+export interface ExtendedTest<Ctx extends TestContext> {
+    /** Quick mode: single-function test with augmented context. */
+    (idOrMeta: string | TestMeta, fn: (ctx: Ctx) => Promise<void>): Test;
+    /** Builder mode: multi-step test with augmented context. */
+    <S = unknown>(idOrMeta: string | TestMeta): TestBuilder<S, Ctx>;
+    /**
+     * Chain another set of extensions on top of the current ones.
+     * The returned test function has `Ctx & NewExtensions` as its context type.
+     */
+    extend<E extends Record<string, ExtensionFn<unknown>>>(extensions: E): ExtendedTest<Ctx & ResolveExtensions<E>>;
+    /** Data-driven tests with augmented context. */
+    each<T extends Record<string, unknown>>(table: readonly T[], options?: EachOptions): {
+        (idOrMeta: string | TestMeta, fn: (ctx: Ctx, data: T) => Promise<void>): Test[];
+        (idOrMeta: string | TestMeta): EachBuilder<unknown, T, Ctx>;
+    };
+    /** Example-selection tests with augmented context. */
+    pick<T extends Record<string, unknown>>(examples: Record<string, T>, count?: number): {
+        (idOrMeta: string | TestMeta, fn: (ctx: Ctx, data: T & {
+            _pick: string;
+        }) => Promise<void>): Test[];
+        (idOrMeta: string | TestMeta): EachBuilder<unknown, T & {
+            _pick: string;
+        }, Ctx>;
+    };
+}
+/** @deprecated Use `parallel` in TestMeta instead. */
+export interface EachOptions {
+    parallel?: boolean;
+}
+/**
+ * Create an extended test function with fixture definitions.
+ * @internal
+ */
+export declare function createExtendedTest<Ctx extends TestContext>(allFixtures: Record<string, ExtensionFn<any>>): ExtendedTest<Ctx>;
+//# sourceMappingURL=extend.d.ts.map

package/dist/test/extend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extend.d.ts","sourceRoot":"","sources":["../../src/test/extend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EACV,WAAW,EACX,iBAAiB,EAEjB,IAAI,EACJ,WAAW,EACX,QAAQ,EACT,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,kFAAkF;AAClF,eAAO,MAAM,oBAAoB,aAAuC,CAAC;AAEzE;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY,CAAC,GAAG,SAAS,WAAW;IACnD,+DAA+D;IAC/D,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACrE,4DAA4D;IAC5D,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,WAAW,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAEhE;;;OAGG;IACH,MAAM,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC,EACnD,UAAU,EAAE,CAAC,GACZ,YAAY,CAAC,GAAG,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;IAE5C,gDAAgD;IAChD,IAAI,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,OAAO,CAAC,EAAE,WAAW,GACpB;QACD,CACE,QAAQ,EAAE,MAAM,GAAG,QAAQ,EAC3B,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GACvC,IAAI,EAAE,CAAC;QACV,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,WAAW,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;KAC7D,CAAC;IAEF,sDAAsD;IACtD,IAAI,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,EAC3B,KAAK,CAAC,EAAE,MAAM,GACb;QACD,CACE,QAAQ,EAAE,MAAM,GAAG,QAAQ,EAC3B,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,GAAG;YAAE,KAAK,EAAE,MAAM,CAAA;SAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAC3D,IAAI,EAAE,CAAC;QACV,CACE,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAC1B,WAAW,CAAC,OAAO,EAAE,CAAC,GAAG;YAAE,KAAK,EAAE,MAAM,CAAA;SAAE,EAAE,GAAG,CAAC,CAAC;KACrD,CAAC;CACH;AAED,sDAAsD;AACtD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,SAAS,WAAW,EACxD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,GAC5C,YAAY,CAAC,GAAG,CAAC,CA8HnB"}