@glubean/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,718 @@
+import type { EachTestFunction, ExtensionFn, ResolveExtensions, SimpleTestFunction, StepMeta, Test, TestContext, TestMeta } from "./types.js";
+/**
+ * Glubean SDK spec version.
+ *
+ * This defines the API contract between the SDK, Scanner, and Runner.
+ * - Major version: Breaking changes
+ * - Minor version: New features (backward compatible)
+ *
+ * @example
+ * ```ts
+ * import { SPEC_VERSION } from "@glubean/sdk";
+ * console.log("SDK spec version:", SPEC_VERSION);
+ * ```
+ */
+export declare const SPEC_VERSION = "2.0";
+/**
+ * Builder class for creating tests with a fluent API.
+ *
+ * @template S The state type for multi-step tests
+ * @template Ctx The context type (defaults to TestContext; augmented by test.extend())
+ *
+ * @example Simple test (quick mode)
+ * ```ts
+ * export const login = test("login", async (ctx) => {
+ *   ctx.assert(true, "works");
+ * });
+ * ```
+ *
+ * @example Multi-step test (builder mode)
+ * ```ts
+ * export const checkout = test("checkout")
+ *   .meta({ tags: ["e2e"] })
+ *   .setup(async (ctx) => ({ cart: await createCart() }))
+ *   .step("Add to cart", async (ctx, state) => {
+ *     await addItem(state.cart, "item-1");
+ *     return state;
+ *   })
+ *   .step("Checkout", async (ctx, state) => {
+ *     await checkout(state.cart);
+ *     return state;
+ *   })
+ *   .teardown(async (ctx, state) => {
+ *     await cleanup(state.cart);
+ *   })
+ *   .build();
+ * ```
+ */
+export declare class TestBuilder<S = unknown, Ctx extends TestContext = TestContext> {
+    private _meta;
+    private _setup?;
+    private _teardown?;
+    private _steps;
+    private _built;
+    _fixtures?: Record<string, ExtensionFn<any>>;
+    /**
+     * Marker property so the runner can detect un-built TestBuilder exports
+     * without importing the SDK. The runner checks this string to auto-build.
+     */
+    readonly __glubean_type: "builder";
+    constructor(id: string, fixtures?: Record<string, ExtensionFn<any>>);
+    /**
+     * Set additional metadata for the test.
+     *
+     * @example
+     * ```ts
+     * test("my-test")
+     *   .meta({ tags: ["smoke"], description: "A smoke test" })
+     *   .step(...)
+     * ```
+     */
+    meta(meta: Omit<TestMeta, "id">): TestBuilder<S, Ctx>;
+    /**
+     * Mark this test as focused.
+     *
+     * Focused tests are intended for local debugging sessions. When any tests in
+     * a run are marked as `only`, non-focused tests may be excluded by discovery
+     * tooling/orchestrators. If `skip` is also set on the same test, `skip`
+     * still wins during run selection.
+     */
+    only(): TestBuilder<S, Ctx>;
+    /**
+     * Mark this test as skipped.
+     *
+     * Skip takes precedence over `only` when both are present.
+     */
+    skip(): TestBuilder<S, Ctx>;
+    /**
+     * Set the setup function that runs before all steps.
+     * The returned state is passed to all steps and teardown.
+     *
+     * @example
+     * ```ts
+     * test("auth")
+     *   .setup(async (ctx) => {
+     *     const baseUrl = ctx.vars.require("BASE_URL");
+     *     const apiKey = ctx.secrets.require("API_KEY");
+     *     const { token } = await ctx.http.post(`${baseUrl}/auth/token`, {
+     *       headers: { "X-API-Key": apiKey },
+     *     }).json();
+     *     return { token };
+     *   })
+     *   .step("verify", async (ctx, { token }) => { ... })
+     * ```
+     */
+    setup<NewS>(fn: (ctx: Ctx) => Promise<NewS>): TestBuilder<NewS, Ctx>;
+    /**
+     * Set the teardown function that runs after all steps (even on failure).
+     *
+     * @example
+     * ```ts
+     * test("db-test")
+     *   .setup(async (ctx) => ({ conn: await connect() }))
+     *   .step(...)
+     *   .teardown(async (ctx, { conn }) => {
+     *     await conn.close();
+     *   })
+     * ```
+     */
+    teardown(fn: (ctx: Ctx, state: S) => Promise<void>): TestBuilder<S, Ctx>;
+    /**
+     * Add a step that does not return state (void).
+     * The state type is preserved for subsequent steps.
+     *
+     * @param name Step name (displayed in reports)
+     * @param fn Step function that performs assertions/side-effects without returning state
+     */
+    step(name: string, fn: (ctx: Ctx, state: S) => Promise<void>): TestBuilder<S, Ctx>;
+    /**
+     * Add a step that returns new state, replacing the current state type.
+     *
+     * The returned value becomes the `state` argument for subsequent steps.
+     * This enables fully type-safe chained steps without needing `.setup()`.
+     *
+     * @param name Step name (displayed in reports)
+     * @param fn Step function receiving context and current state, returning new state
+     *
+     * @example
+     * ```ts
+     * test("auth-flow")
+     *   .step("login", async (ctx) => {
+     *     const data = await ctx.http.post("/auth/login", { json: creds }).json<{ token: string }>();
+     *     return { token: data.token };
+     *   })
+     *   .step("get profile", async (ctx, { token }) => {
+     *     // token is inferred as string ✓
+     *     const profile = await ctx.http.get("/auth/me", {
+     *       headers: { Authorization: `Bearer ${token}` },
+     *     }).json<{ name: string }>();
+     *     return { token, name: profile.name };
+     *   })
+     * ```
+     */
+    step<NewS>(name: string, fn: (ctx: Ctx, state: S) => Promise<NewS>): TestBuilder<NewS, Ctx>;
+    /**
+     * Add a step with options (void return).
+     */
+    step(name: string, options: Omit<StepMeta, "name">, fn: (ctx: Ctx, state: S) => Promise<void>): TestBuilder<S, Ctx>;
+    /**
+     * Add a step with additional options, returning new state.
+     */
+    step<NewS>(name: string, options: Omit<StepMeta, "name">, fn: (ctx: Ctx, state: S) => Promise<NewS>): TestBuilder<NewS, Ctx>;
+    /**
+     * Apply a builder transform function for step composition.
+     *
+     * Reusable step sequences are just plain functions that take a builder
+     * and return a builder. `.use()` applies such a function to the current
+     * chain, preserving state flow.
+     *
+     * @param fn Transform function that receives this builder and returns a (possibly re-typed) builder
+     *
+     * @example Reusable step sequence
+     * ```ts
+     * // Define once — just a function
+     * const withAuth = (b: TestBuilder<unknown>) => b
+     *   .step("login", async (ctx) => {
+     *     const data = await ctx.http.post("/login", { json: creds }).json<{ token: string }>();
+     *     return { token: data.token };
+     *   });
+     *
+     * // Reuse across tests
+     * export const testA = test("test-a").use(withAuth).step("act", async (ctx, { token }) => { ... });
+     * export const testB = test("test-b").use(withAuth).step("verify", async (ctx, { token }) => { ... });
+     * ```
+     */
+    use<NewS>(fn: (builder: TestBuilder<S, Ctx>) => TestBuilder<NewS, Ctx>): TestBuilder<NewS, Ctx>;
+    /**
+     * Apply a builder transform and tag all newly added steps with a group ID.
+     *
+     * Works exactly like `.use()`, but every step added by `fn` is marked with
+     * `group` metadata for visual grouping in reports and dashboards.
+     *
+     * @param id Group identifier (displayed in reports as a section header)
+     * @param fn Transform function that adds steps to the builder
+     *
+     * @example Reusable steps with grouping
+     * ```ts
+     * const withAuth = (b: TestBuilder<unknown>) => b
+     *   .step("login", async (ctx) => ({ token: "..." }))
+     *   .step("verify", async (ctx, { token }) => ({ token, verified: true }));
+     *
+     * export const checkout = test("checkout")
+     *   .group("auth", withAuth)
+     *   .step("pay", async (ctx, { token }) => { ... });
+     *
+     * // Report output:
+     * // checkout
+     * //   ├─ [auth]
+     * //   │   ├─ login ✓
+     * //   │   └─ verify ✓
+     * //   └─ pay ✓
+     * ```
+     *
+     * @example Inline grouping (no reuse, just organization)
+     * ```ts
+     * export const e2e = test("e2e")
+     *   .group("setup", b => b
+     *     .step("seed db", async (ctx) => ({ dbId: "..." }))
+     *     .step("create user", async (ctx, { dbId }) => ({ dbId, userId: "..." }))
+     *   )
+     *   .step("verify", async (ctx, { dbId, userId }) => { ... });
+     * ```
+     */
+    group<NewS>(id: string, fn: (builder: TestBuilder<S, Ctx>) => TestBuilder<NewS, Ctx>): TestBuilder<NewS, Ctx>;
+    /**
+     * Finalize and register the test 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 the test. Returns a plain `Test<S>` object.
+     *
+     * **Optional** — if omitted, the builder auto-finalizes via microtask
+     * after all synchronous chaining completes, and the runner will
+     * auto-detect the builder export. Calling `.build()` explicitly is
+     * still supported for backward compatibility.
+     *
+     * @example
+     * ```ts
+     * // With .build() (explicit — backward compatible)
+     * export const myTest = test("my-test")
+     *   .step("step-1", async (ctx) => { ... })
+     *   .build();
+     *
+     * // Without .build() (auto-finalized — recommended)
+     * export const myTest = test("my-test")
+     *   .step("step-1", async (ctx) => { ... });
+     * ```
+     */
+    build(): Test<S>;
+}
+/**
+ * Create a new test.
+ *
+ * This is the unified entry point for all test definitions.
+ * Supports both quick mode (single function) and builder mode (multi-step).
+ *
+ * @example Quick mode (simple test)
+ * ```ts
+ * import { test } from "@glubean/sdk";
+ *
+ * export const login = test("login", async (ctx) => {
+ *   const res = await ctx.http.get(`${ctx.vars.require("BASE_URL")}/login`);
+ *   ctx.assert(res.ok, "Login should succeed");
+ * });
+ * ```
+ *
+ * @example Quick mode with metadata
+ * ```ts
+ * export const login = test(
+ *   { id: "login", tags: ["auth", "smoke"] },
+ *   async (ctx) => {
+ *     ctx.assert(true, "works");
+ *   }
+ * );
+ * ```
+ *
+ * @example Builder mode (multi-step) — .build() is optional
+ * ```ts
+ * export const checkout = test("checkout")
+ *   .meta({ tags: ["e2e"] })
+ *   .setup(async (ctx) => ({ cart: await createCart() }))
+ *   .step("Add item", async (ctx, state) => { ... })
+ *   .step("Pay", async (ctx, state) => { ... })
+ *   .teardown(async (ctx, state) => { ... });
+ * ```
+ *
+ * @param idOrMeta Test ID (string) or full metadata object
+ * @param fn Optional test function (quick mode)
+ * @returns Test object (quick mode) or TestBuilder (builder mode)
+ */
+export declare function test<S = unknown>(idOrMeta: string | TestMeta): TestBuilder<S>;
+export declare function test(idOrMeta: string | TestMeta, fn: SimpleTestFunction): Test;
+/**
+ * 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;
+    _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>>);
+    /**
+     * 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>;
+    /**
+     * Get the filtered table (apply filter callback if present).
+     * @internal
+     */
+    private _filteredTable;
+    /**
+     * Compute tags for a specific row (static tags + tagFields).
+     * @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>[];
+}
+/**
+ * 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[]): {
+        (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>;
+    };
+}
+export declare namespace test {
+    /**
+     * Mark a test definition as focused (`only: true`).
+     *
+     * Works in both quick mode and builder mode.
+     * If `skip` is also set on the same test, `skip` takes precedence.
+     *
+     * @example Quick mode
+     * ```ts
+     * export const focused = test.only("focused-login", async (ctx) => {
+     *   ctx.expect(true).toBeTruthy();
+     * });
+     * ```
+     *
+     * @example Builder mode
+     * ```ts
+     * export const focusedFlow = test.only("focused-flow")
+     *   .step("run", async (ctx) => {
+     *     ctx.expect(true).toBeTruthy();
+     *   });
+     * ```
+     */
+    function only<S = unknown>(idOrMeta: string | TestMeta): TestBuilder<S>;
+    function only(idOrMeta: string | TestMeta, fn: SimpleTestFunction): Test;
+    /**
+     * Mark a test definition as skipped (`skip: true`).
+     *
+     * Works in both quick mode and builder mode.
+     * Skip takes precedence over `only` when both are present.
+     */
+    function skip<S = unknown>(idOrMeta: string | TestMeta): TestBuilder<S>;
+    function skip(idOrMeta: string | TestMeta, fn: SimpleTestFunction): Test;
+    function each<T extends Record<string, unknown>>(table: readonly T[]): {
+        (idOrMeta: string, fn: EachTestFunction<T>): Test[];
+        (idOrMeta: TestMeta, fn: EachTestFunction<T>): Test[];
+        (idOrMeta: string): EachBuilder<unknown, T>;
+        (idOrMeta: TestMeta): EachBuilder<unknown, T>;
+    };
+    /**
+     * Example-selection API — randomly picks N examples from a named map.
+     *
+     * `test.pick` is a thin wrapper over `test.each`. It selects a subset of
+     * examples from a `Record<string, T>`, injects a `_pick` field containing
+     * the example key name, and delegates to `test.each`.
+     *
+     * Because the return value is identical to `test.each`, all `test.each`
+     * options (`filter`, `tagFields`, `tags`) work transparently with `test.pick`.
+     *
+     * **Default behavior (no CLI override):** randomly selects `count` examples
+     * (default 1). This provides lightweight fuzz / smoke-test coverage.
+     *
+     * **CLI override:** `--pick key1,key2` (or env var `GLUBEAN_PICK`) selects
+     * specific examples by name, overriding random selection.
+     *
+     * **Run all:** `--pick all` or `--pick '*'` runs every example.
+     * Recommended for CI where you want full coverage.
+     *
+     * **Glob patterns:** `--pick 'us-*'` selects all keys matching the pattern.
+     * Useful when examples are grouped by prefix (e.g. regions, tenants).
+     *
+     * **VSCode integration:** CodeLens buttons let users click a specific
+     * example to run, which passes `--pick <key>` under the hood.
+     *
+     * Use `$_pick` in the ID template to include the example key in the test ID.
+     *
+     * @param examples A named map of example data rows
+     * @param count Number of examples to randomly select (default 1)
+     * @returns Same as `test.each` — a function accepting ID template and callback
+     *
+     * @example Inline examples
+     * ```ts
+     * export const createUser = test.pick({
+     *   "normal":    { name: "Alice", age: 25 },
+     *   "edge-case": { name: "", age: -1 },
+     *   "admin":     { name: "Admin", role: "admin" },
+     * })("create-user-$_pick", async (ctx, example) => {
+     *   await ctx.http.post("/api/users", { json: example });
+     * });
+     * ```
+     *
+     * @example With filter and tagFields (inherited from test.each)
+     * ```ts
+     * export const regionTests = test.pick(allRegions)({
+     *   id: "region-$_pick",
+     *   tagFields: ["currency", "_pick"],
+     *   filter: (row) => row.currency === "USD",
+     * }, async (ctx, data) => {
+     *   const res = await ctx.http.get(data.endpoint);
+     *   ctx.expect(res).toHaveStatus(200);
+     * });
+     * ```
+     *
+     * @example CLI usage
+     * ```bash
+     * glubean run file.ts                    # random example (default)
+     * glubean run file.ts --pick normal      # specific example
+     * glubean run file.ts --pick normal,admin  # multiple examples
+     * glubean run file.ts --pick all         # every example (CI)
+     * glubean run file.ts --pick 'us-*'      # glob pattern
+     * ```
+     */
+    function pick<T extends Record<string, unknown>>(examples: Record<string, T>, count?: number): ReturnType<typeof each<T & {
+        _pick: string;
+    }>>;
+    /**
+     * Create an extended `test` function with augmented context.
+     *
+     * Inspired by Playwright's `test.extend()`. Returns a new test function
+     * where `ctx` includes the resolved fixture properties alongside the
+     * base `TestContext` methods.
+     *
+     * @example Define shared fixtures
+     * ```ts
+     * // tests/fixtures.ts
+     * import { test as base } from "@glubean/sdk";
+     *
+     * export const test = base.extend({
+     *   auth: (ctx) => createAuth(ctx.vars.require("AUTH_URL")),
+     *   db: async (ctx, use) => {
+     *     const db = await connect(ctx.vars.require("DB_URL"));
+     *     await use(db);
+     *     await db.disconnect();
+     *   },
+     * });
+     * ```
+     *
+     * @example Use in tests
+     * ```ts
+     * // tests/users.test.ts
+     * import { test } from "./fixtures.js";
+     *
+     * export const myTest = test("my-test", async (ctx) => {
+     *   ctx.auth; // full autocomplete
+     *   ctx.db;   // full autocomplete
+     * });
+     * ```
+     *
+     * @example Chained extend
+     * ```ts
+     * import { test as withAuth } from "./auth-fixtures.js";
+     * export const test = withAuth.extend({ db: ... });
+     * ```
+     */
+    function extend<E extends Record<string, ExtensionFn<unknown>>>(extensions: E): ExtendedTest<TestContext & ResolveExtensions<E>>;
+}
+export * from "./types.js";
+export { fromCsv, fromDir, fromJsonl, fromYaml, toArray } from "./data.js";
+export type { FromCsvOptions, FromDirConcatOptions, FromDirOptions, FromYamlOptions } from "./data.js";
+export { configure, resolveTemplate } from "./configure.js";
+export { definePlugin } from "./plugin.js";
+export { Expectation, ExpectFailError } from "./expect.js";
+export type { AssertEmitter, AssertionEmission, CustomMatchers, MatcherFn, MatcherResult } from "./expect.js";
+//# sourceMappingURL=index.d.ts.map