@ripplo/testing 0.3.8 → 0.3.10

package/dist/actions.d.ts

@@ -191,6 +191,11 @@ interface HandleDialogOptions {
     readonly promptText: string | undefined;
     readonly uiOnly?: boolean;
 }
+/**
+ * Respond to a native browser dialog (`alert`, `confirm`, `prompt`). Set
+ * `uiOnly: true` only when the dialog has no backend side effect — if it
+ * triggers a mutation, wire an observer and keep `uiOnly` off.
+ */
 declare function handleDialog({ action, promptText, uiOnly }: HandleDialogOptions): UnlabeledStep<{
     action: "accept" | "dismiss";
     promptText: string | undefined;
@@ -202,6 +207,12 @@ interface ClipboardOptions {
     readonly target: Variable<string> | undefined;
     readonly value: StringOrVariable | undefined;
 }
+/**
+ * Read from or write to the browser clipboard. Use when a flow depends on
+ * copy/paste (share links, invite tokens) — pair `write` to seed the
+ * clipboard before a paste action, or `read` into a `variable()` to assert
+ * what the app copied.
+ */
 declare function clipboard({ action, target, value }: ClipboardOptions): UnlabeledStep<{
     action: "read" | "write";
     type: "clipboard";
@@ -212,6 +223,10 @@ interface SetPermissionOptions {
     readonly permission: string;
     readonly state: "granted" | "prompt";
 }
+/**
+ * Pre-answer a browser permission prompt (geolocation, camera, notifications,
+ * clipboard-read, etc.) so the test doesn't stall on the native dialog.
+ */
 declare function setPermission({ permission, state }: SetPermissionOptions): UnlabeledStep<{
     permission: string;
     state: "granted" | "prompt";
@@ -221,6 +236,11 @@ interface SetViewportOptions {
     readonly height: number;
     readonly width: number;
 }
+/**
+ * Resize the browser viewport mid-test. Use to cover responsive breakpoints
+ * (mobile nav, collapsed sidebars) within the same flow rather than
+ * duplicating the test per size.
+ */
 declare function setViewport({ height, width }: SetViewportOptions): UnlabeledStep<{
     height: number;
     type: "setViewport";

package/dist/assert.d.ts

@@ -67,6 +67,12 @@ declare const assert: {
         operator: "equals";
         type: "assertAttribute";
     }>;
+    /**
+     * Verify a backend side effect by polling an observer. The server-side
+     * observer impl returns `ctx.retry(reason)` for transient states (keep
+     * polling) and `ctx.fail(reason)` only for invariant violations (stop
+     * early). The observer's `.budget()` governs poll interval and timeout.
+     */
     backend<THandle extends ObserverHandle>(observer: THandle, params: ObserverInput<THandle> & Record<string, string>): UnlabeledStep<{
         budget: ObserverBudgetTier;
         observer: string;

package/dist/assert.js

@@ -37,6 +37,13 @@ var assert = {
       type: "assertAttribute"
     });
   },
+  // eslint-disable-next-line no-comments/disallowComments
+  /**
+   * Verify a backend side effect by polling an observer. The server-side
+   * observer impl returns `ctx.retry(reason)` for transient states (keep
+   * polling) and `ctx.fail(reason)` only for invariant violations (stop
+   * early). The observer's `.budget()` governs poll interval and timeout.
+   */
   backend(observer, params) {
     return createStep({
       budget: readObserverBudget(observer),

package/dist/{builder-D-i_ueN3.d.ts → builder-CkyzxH7O.d.ts}

@@ -6,6 +6,12 @@ interface ObserverNeedsDescription {
     readonly description: (text: string) => ObserverNeedsBudget;
 }
 interface ObserverNeedsBudget {
+    /**
+     * Polling envelope: interval + total timeout the runner uses when calling
+     * `assert.backend()`. Pick by where the side effect lands — fast for
+     * same-request DB reads, slow for job-queue settle, async for
+     * webhook/email delivery. Too tight = flaky; too loose = slow suite.
+     */
     readonly budget: (tier: ObserverBudget) => ObserverNeedsInput;
 }
 interface ObserverNeedsInput {
@@ -15,6 +21,11 @@ interface ObserverReady<TInput extends Record<string, string>> {
     readonly contract: () => ObserverHandle<TInput>;
 }
 
+interface CoverageRegistry {
+}
+type RegistryKeys = keyof CoverageRegistry;
+type CoverageStatementId = [RegistryKeys] extends [never] ? string : Extract<RegistryKeys, string>;
+
 type PreconditionRecord = Record<string, Precondition>;
 type ResolveDeps<TDeps extends PreconditionRecord> = {
     readonly [K in keyof TDeps]: PreconditionData<TDeps[K]>;
@@ -32,6 +43,13 @@ interface TestNeedsName {
 }
 interface TestNeedsRequires {
     readonly description: (text: string) => TestNeedsRequires;
+    /**
+     * Declare the preconditions this test needs. The object keys become the
+     * destructured parameter in `.startsAt` / `.steps`, and each precondition's
+     * return data flows through as a typed proxy — interpolate proxy fields
+     * directly (e.g. `` `/workspaces/${workspace.id}` ``); never hand-write
+     * `{{namespace.key}}` template strings (lint blocks this).
+     */
     readonly requires: <TReqs extends PreconditionRecord>(reqs: TReqs) => TestNeedsOutcome<ResolveDeps<TReqs>>;
 }
 interface TestNeedsOutcome<TVars extends Record<string, Record<string, string>>> {
@@ -39,14 +57,34 @@ interface TestNeedsOutcome<TVars extends Record<string, Record<string, string>>>
 }
 
 interface TestNeedsStartsAt<TVars extends Record<string, Record<string, string>>> {
+    /**
+     * Skip implementation — compiles as a planning stub and is reported in
+     * `getUnimplemented()`. The test appears in the lockfile but is not run.
+     */
     readonly notImplemented: () => TestDefinition;
+    /**
+     * Starting URL for the test, derived from precondition data. The function
+     * receives the `.requires()` object destructured as typed proxies; it runs
+     * at compile time, not at test-author time.
+     */
     readonly startsAt: (fn: (vars: TVars) => string) => TestNeedsSteps<TVars>;
 }
 interface TestNeedsSteps<TVars extends Record<string, Record<string, string>>> {
+    /**
+     * Declare the ordered step list. Receives destructured precondition data as
+     * typed proxies (same as `.startsAt`). Every step must be labeled with
+     * `.as("…")` — lint enforces it.
+     */
     readonly steps: (fn: (vars: TVars) => ReadonlyArray<Step>) => TestNeedsCoverage;
 }
 interface TestNeedsCoverage {
-    readonly coverage: (...ids: ReadonlyArray<string>) => TestDefinition;
+    /**
+     * Finalize the test and declare which mutation/AST branches it covers.
+     * Coverage IDs feed LLM-driven test scoping on diffs so only relevant tests
+     * run for a change. `.coverage()` (or `.notImplemented()`) is the only way
+     * to terminate the chain into a runnable `TestDefinition`.
+     */
+    readonly coverage: (...ids: ReadonlyArray<CoverageStatementId>) => TestDefinition;
 }
 
 type PreconditionSetupResult<TData extends Record<string, string>> = {
@@ -79,9 +117,35 @@ interface RipploInstance<P extends PreconditionRegistry = PreconditionRegistry,
     readonly getUnimplemented: () => UnimplementedItems;
 }
 type RipploBuilder = RipploInstance;
+/**
+ * Declare a precondition — a named, reusable piece of test data setup. Returns
+ * a pure handle (no side effects at definition time); the setup/teardown impl
+ * is wired once in `createEngine`. Depend on other preconditions via
+ * `.requires()` so the DAG can resolve independents in parallel, giving every
+ * test a clean, isolated slate.
+ */
 declare function precondition(name: string): PreconditionNeedsSetup;
+/**
+ * Declare a backend assertion — checked from tests via `assert.backend()`.
+ * The impl runs on your server (where DB/queue access lives) and is polled
+ * until pass/fail; `.budget()` picks the polling envelope. Use this instead
+ * of sleeps when verifying async side effects (jobs, webhooks, emails, DB rows).
+ */
 declare function observer(name: string): ObserverNeedsDescription;
+/**
+ * Start a test definition. `id` is a stable kebab-case key persisted in the
+ * lockfile and used for run history — changing it renames the test and loses
+ * history. Set `options.uiOnly` only for genuinely read-only flows (no
+ * mutations); do not use it to silence observer lint on flows that mutate
+ * state — wire the observer instead.
+ */
 declare function test(id: string, options?: TestOptions): TestNeedsName;
+/**
+ * The single registration point for the DSL graph. Collects the three
+ * registries into an instance consumed both by `ripplo compile` (to write
+ * `.ripplo/ripplo.lock`) and by `createEngine` on the server, where
+ * TypeScript exhaustiveness-checks that every handle has exactly one impl.
+ */
 declare function createRipplo<P extends PreconditionRegistry, O extends ObserverRegistry>(rawConfig: UserDslConfig, registries: RipploRegistries<P, O>): RipploInstance<P, O>;
 
-export { type ObserverImplFn as O, type PreconditionImpl as P, type ResolveDeps as R, type ObserverRegistry as a, type PreconditionRecord as b, type PreconditionRegistry as c, type RipploBuilder as d, type RipploInstance as e, type RipploRegistries as f, createRipplo as g, observer as o, precondition as p, test as t };
+export { type CoverageRegistry as C, type ObserverImplFn as O, type PreconditionImpl as P, type ResolveDeps as R, type ObserverRegistry as a, type PreconditionRecord as b, type PreconditionRegistry as c, type RipploBuilder as d, type RipploInstance as e, type RipploRegistries as f, createRipplo as g, observer as o, precondition as p, test as t };

package/dist/compiler.d.ts

@@ -1,5 +1,5 @@
 import { Observer, Precondition, WorkflowSpec } from '@ripplo/spec';
-import { d as RipploBuilder } from './builder-D-i_ueN3.js';
+import { d as RipploBuilder } from './builder-CkyzxH7O.js';
 import { e as DslConfig } from './types-Do4o4Y_c.js';
 import './step-De52hTLd.js';
 import 'zod';

package/dist/control.d.ts

@@ -6,6 +6,12 @@ declare const VARIABLE_INTERNAL: unique symbol;
 interface Variable<_TName extends string> {
     readonly [VARIABLE_INTERNAL]: _TName;
 }
+/**
+ * Declare a runtime placeholder, bound later by `extract()` and consumed by
+ * actions/assertions. Use for values produced mid-test (e.g. an ID rendered
+ * into the DOM). Precondition data is already typed and injected — reach for
+ * `variable` only when the value isn't known until the test runs.
+ */
 declare function variable<TName extends string>(name: TName): Variable<TName>;
 declare function readVariable(v: Variable<string>): string;
 declare function isVariable(v: unknown): v is Variable<string>;
@@ -18,6 +24,11 @@ interface VariableRef {
     readonly type: "variable";
 }
 declare function toStringValueRef(value: string | Variable<string>): StaticStringRef | VariableRef;
+/**
+ * Capture the text of the matched element into `target` (a `variable()`).
+ * Pairs by name — downstream steps referencing the same `variable` see the
+ * extracted value.
+ */
 declare function extract(locator: AnyLocator, target: Variable<string>): UnlabeledStep<{
     locator: {
         by: "testId";

package/dist/elysia.d.ts

@@ -1,6 +1,6 @@
 import { Elysia } from 'elysia';
-import { R as RipploEngine } from './engine-BMfNkIKC.js';
-import './builder-D-i_ueN3.js';
+import { R as RipploEngine } from './engine-CRq3Az6b.js';
+import './builder-CkyzxH7O.js';
 import './types-Do4o4Y_c.js';
 import 'zod';
 import './step-De52hTLd.js';

package/dist/{engine-BMfNkIKC.d.ts → engine-CRq3Az6b.d.ts}

@@ -1,4 +1,4 @@
-import { c as PreconditionRegistry, a as ObserverRegistry, O as ObserverImplFn, P as PreconditionImpl, e as RipploInstance } from './builder-D-i_ueN3.js';
+import { c as PreconditionRegistry, a as ObserverRegistry, O as ObserverImplFn, P as PreconditionImpl, e as RipploInstance } from './builder-CkyzxH7O.js';
 import { h as ObserverOutcome, C as CookieEntry, e as DslConfig, g as ObserverDefinition, k as PreconditionDefinition, U as UnimplementedItems, O as ObserverHandle, P as Precondition } from './types-Do4o4Y_c.js';
 
 interface EngineResult {

package/dist/express.d.ts

@@ -1,6 +1,6 @@
 import { Router } from 'express';
-import { R as RipploEngine } from './engine-BMfNkIKC.js';
-import './builder-D-i_ueN3.js';
+import { R as RipploEngine } from './engine-CRq3Az6b.js';
+import './builder-CkyzxH7O.js';
 import './types-Do4o4Y_c.js';
 import 'zod';
 import './step-De52hTLd.js';

package/dist/fastify.d.ts

@@ -1,6 +1,6 @@
 import { FastifyInstance } from 'fastify';
-import { R as RipploEngine } from './engine-BMfNkIKC.js';
-import './builder-D-i_ueN3.js';
+import { R as RipploEngine } from './engine-CRq3Az6b.js';
+import './builder-CkyzxH7O.js';
 import './types-Do4o4Y_c.js';
 import 'zod';
 import './step-De52hTLd.js';

package/dist/hono.d.ts

@@ -1,6 +1,6 @@
 import { Hono } from 'hono';
-import { R as RipploEngine } from './engine-BMfNkIKC.js';
-import './builder-D-i_ueN3.js';
+import { R as RipploEngine } from './engine-CRq3Az6b.js';
+import './builder-CkyzxH7O.js';
 import './types-Do4o4Y_c.js';
 import 'zod';
 import './step-De52hTLd.js';

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-export { O as ObserverImplFn, a as ObserverRegistry, P as PreconditionImpl, b as PreconditionRecord, c as PreconditionRegistry, R as ResolveDeps, d as RipploBuilder, e as RipploInstance, f as RipploRegistries, g as createRipplo, o as observer, p as precondition, t as test } from './builder-D-i_ueN3.js';
+export { C as CoverageRegistry, O as ObserverImplFn, a as ObserverRegistry, P as PreconditionImpl, b as PreconditionRecord, c as PreconditionRegistry, R as ResolveDeps, d as RipploBuilder, e as RipploInstance, f as RipploRegistries, g as createRipplo, o as observer, p as precondition, t as test } from './builder-CkyzxH7O.js';
 import { CompileResult } from './compiler.js';
 export { CompiledTest, compile } from './compiler.js';
-export { E as EngineImpls, a as EngineResult, b as ExecuteBatchOptions, N as NotImplemented, O as ObserverImplFnFor, P as PreconditionImplFor, R as RipploEngine, c as createEngine, n as notImplemented } from './engine-BMfNkIKC.js';
+export { E as EngineImpls, a as EngineResult, b as ExecuteBatchOptions, N as NotImplemented, O as ObserverImplFnFor, P as PreconditionImplFor, R as RipploEngine, c as createEngine, n as notImplemented } from './engine-CRq3Az6b.js';
 import { C as CookieEntry } from './types-Do4o4Y_c.js';
 export { c as CookieOptions, D as DEFAULT_IGNORE_PATHS, d as DEFAULT_WATCH_PATHS, e as DslConfig, f as ObserverContext, g as ObserverDefinition, O as ObserverHandle, a as ObserverInput, h as ObserverOutcome, P as Precondition, i as PreconditionDeps, S as SetupContext, T as TeardownContext, j as TestDefinition } from './types-Do4o4Y_c.js';
 export { D as DslNodeInput } from './step-De52hTLd.js';

package/dist/koa.d.ts

@@ -1,6 +1,6 @@
 import { Middleware } from 'koa';
-import { R as RipploEngine } from './engine-BMfNkIKC.js';
-import './builder-D-i_ueN3.js';
+import { R as RipploEngine } from './engine-CRq3Az6b.js';
+import './builder-CkyzxH7O.js';
 import './types-Do4o4Y_c.js';
 import 'zod';
 import './step-De52hTLd.js';

package/dist/locators.d.ts

@@ -24,7 +24,17 @@ type AnyLocator = Locator<"role" | "testId">;
 type InputLocator = Locator<"testId"> | RoleLocator<"combobox" | "searchbox" | "spinbutton" | "textbox">;
 type SelectLocator = Locator<"testId"> | RoleLocator<"combobox" | "listbox">;
 type CheckLocator = Locator<"testId"> | RoleLocator<"checkbox" | "switch">;
+/**
+ * Preferred locator: targets an element by its ARIA role and accessible name.
+ * Survives DOM churn and doubles as an accessibility check — if a role query
+ * can't find your element, real users likely can't either.
+ */
 declare function role<TRole extends AriaRole>(ariaRole: TRole, name?: string): RoleLocator<TRole>;
+/**
+ * Escape hatch for elements without a semantic role (decorative wrappers,
+ * non-interactive panels). Prefer `role()` when the element has one; a
+ * test-id locator has no accessibility signal.
+ */
 declare function testId(id: string): Locator<"testId">;
 
 export { type AnyLocator, type AriaRole, type CheckLocator, type InputLocator, type Locator, type LocatorSpec, type RoleLocator, type SelectLocator, readLocator, role, testId };

package/dist/lockfile.d.ts

@@ -1,7 +1,7 @@
 import { Codec } from '@ripplo/spec';
 import { z } from 'zod';
 import { CompileResult } from './compiler.js';
-import './builder-D-i_ueN3.js';
+import './builder-CkyzxH7O.js';
 import './types-Do4o4Y_c.js';
 import './step-De52hTLd.js';
 

package/dist/nestjs.d.ts

@@ -1,6 +1,6 @@
 import { DynamicModule } from '@nestjs/common';
-import { R as RipploEngine } from './engine-BMfNkIKC.js';
-import './builder-D-i_ueN3.js';
+import { R as RipploEngine } from './engine-CRq3Az6b.js';
+import './builder-CkyzxH7O.js';
 import './types-Do4o4Y_c.js';
 import 'zod';
 import './step-De52hTLd.js';

package/dist/nextjs.d.ts

@@ -1,5 +1,5 @@
-import { R as RipploEngine } from './engine-BMfNkIKC.js';
-import './builder-D-i_ueN3.js';
+import { R as RipploEngine } from './engine-CRq3Az6b.js';
+import './builder-CkyzxH7O.js';
 import './types-Do4o4Y_c.js';
 import 'zod';
 import './step-De52hTLd.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ripplo/testing",
   "description": "TypeScript DSL for defining and running Ripplo e2e workflow tests",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "type": "module",
   "files": [
     "dist"