@ripplo/testing 0.0.1

package/README.md

@@ -0,0 +1,386 @@
+# @ripplo/testing
+
+Typed TypeScript DSL for defining end-to-end tests with [Ripplo](https://ripplo.ai).
+
+## Install
+
+```sh
+npm install @ripplo/testing
+```
+
+## Quick Start
+
+1. Run `npx ripplo` to authenticate and scaffold a `.ripplo/` directory in your project
+2. Define preconditions in `.ripplo/preconditions.ts` — these set up test data (users, projects, etc.)
+3. Write tests in `.ripplo/tests/` — each file defines one user flow to test
+4. Run `npx ripplo lint` to validate, `npx ripplo run` to execute
+
+Every test gets a clean slate via preconditions — no shared state, no ordering dependencies, fully parallelizable.
+
+## DSL API
+
+### Test Builder
+
+```typescript
+import ripplo from "../ripplo.js";
+import { dataProject } from "../preconditions.js";
+
+ripplo
+  .test("delete-project")
+  .name("Delete a project")
+  .requires({ project: dataProject })
+  .expectedOutcome("Project deleted and user redirected to connect page")
+  .startsAt(({ project }) => `/projects/${project.projectId}/settings`)
+  .steps(({ project }) => [
+    // steps here
+  ]);
+```
+
+**Chain:** `.test(id)` → `.name(display)` → `.requires(preconditions)` → `.expectedOutcome(text)` → `.startsAt(urlFn)` → `.steps(stepsFn)`
+
+Use `.notImplemented()` instead of `.startsAt()` + `.steps()` to stub a test during planning.
+
+### Locators
+
+Only two locator types are available. ARIA roles are strongly preferred.
+
+```typescript
+import { role, testId } from "@ripplo/testing/locators";
+
+role("button", "Save"); // ARIA role + accessible name (preferred)
+role("heading", "Settings"); // role without interaction
+role("textbox", "Email"); // input by role
+role("combobox", "Country"); // select/dropdown by role
+testId("workflow-checkbox"); // data-testid (fallback only)
+```
+
+**Available ARIA roles:** `alert`, `alertdialog`, `button`, `checkbox`, `combobox`, `dialog`, `form`, `grid`, `heading`, `img`, `link`, `list`, `listbox`, `listitem`, `menu`, `menuitem`, `navigation`, `option`, `progressbar`, `radio`, `region`, `row`, `searchbox`, `separator`, `slider`, `spinbutton`, `status`, `switch`, `tab`, `tabpanel`, `textbox`, `toolbar`, `tooltip`, `tree`, `treeitem`
+
+**Type-safe constraints:**
+
+- `InputLocator` accepts: `role("textbox")`, `role("searchbox")`, `role("combobox")`, `role("spinbutton")`, `testId()`
+- `SelectLocator` accepts: `role("combobox")`, `role("listbox")`, `testId()`
+- `CheckLocator` accepts: `role("checkbox")`, `role("switch")`, `testId()`
+
+### Actions
+
+```typescript
+import {
+  click,
+  fill,
+  select,
+  check,
+  uncheck,
+  hover,
+  press,
+  navigate,
+  dblclick,
+  focus,
+  clear,
+  typeText,
+  rightClick,
+  scrollIntoView,
+  drag,
+  upload,
+  handleDialog,
+  clipboard,
+  setPermission,
+  setViewport,
+} from "@ripplo/testing/actions";
+
+navigate("/settings"); // Go to URL
+click(role("button", "Save")); // Click element
+fill(role("textbox", "Email"), "test@x.com"); // Clear + type into input
+select(role("combobox", "Role"), "admin"); // Select option
+check(role("checkbox", "Terms")); // Check checkbox/switch
+uncheck(role("switch", "Notifications")); // Uncheck
+hover(role("button", "Info")); // Hover
+press("Enter"); // Press key
+focus(role("searchbox", "Search")); // Focus element
+dblclick(role("button", "Edit")); // Double click
+clear(role("textbox", "Search")); // Clear input
+upload(testId("file-input"), "./test.png"); // Upload file
+drag(role("row", "Item 1"), role("row", "Item 2")); // Drag and drop
+```
+
+### Assertions
+
+```typescript
+import { assert } from "@ripplo/testing/assert";
+
+assert.visible(role("heading", "Settings")); // Element visible
+assert.not.visible(role("dialog")); // Element not visible
+assert.text(role("status"), "3 / 5 runs"); // Exact text match
+assert.url("/projects/abc/settings"); // Exact URL match
+assert.enabled(role("button", "Submit")); // Element enabled
+assert.disabled(role("button", "Submit")); // Element disabled
+assert.checked(role("checkbox", "Terms")); // Checked
+assert.not.checked(role("switch", "Dark mode")); // Not checked
+assert.focused(role("textbox", "Search")); // Has focus
+assert.not.focused(role("textbox", "Search")); // No focus
+assert.count(testId("row"), 5); // Element count
+assert.attribute(role("link", "Docs"), "href", "/docs"); // Attribute value
+assert.value(role("textbox", "Email"), "test@x.com"); // Input value
+```
+
+All text/URL assertions use **exact matching only** (`equals` operator). No `contains`, `startsWith`, or regex.
+
+### Variables & Extraction
+
+```typescript
+import { extract, variable } from "@ripplo/testing/control";
+
+const token = variable("token");
+extract(testId("token-value"), token).as("capture token");
+// token can be referenced in subsequent steps
+```
+
+### Step Labels
+
+Every step **must** have a `.as("description")` label:
+
+```typescript
+click(role("button", "Save")).as("save the form");
+assert.visible(role("status", "Saved")).as("verify save confirmation");
+```
+
+## Precondition System
+
+Preconditions declare test data requirements with typed contracts:
+
+```typescript
+import ripplo from "./ripplo.js";
+
+export const authLoggedIn = ripplo
+  .precondition("auth:logged-in")
+  .description("Authenticated test user with a valid session")
+  .contract<{ userId: string }>();
+
+export const dataProject = ripplo
+  .precondition("data:project")
+  .description("A project exists and the user is an admin member")
+  .requires({ auth: authLoggedIn })
+  .contract<{ orgId: string; projectId: string }>();
+```
+
+**Chain:** `.precondition(name)` → `.description(text)` → `.requires(deps)` → `.contract<T>()`
+
+Use `.notImplemented()` instead of `.contract<T>()` for stubs.
+
+### Data Flow
+
+Precondition data flows into tests via destructuring:
+
+```typescript
+ripplo
+  .test("delete-project")
+  .requires({ project: dataProject })
+  .startsAt(({ project }) => `/projects/${project.projectId}/settings`)
+  .steps(({ project }) => [
+    navigate(`/projects/${project.projectId}/settings`).as("go to settings"),
+    // project.projectId, project.orgId available here
+  ]);
+```
+
+**Always destructure and use precondition data.** Never hardcode values that come from preconditions — if a precondition implementation changes, the test should not break.
+
+### Precondition Implementation
+
+```typescript
+ripplo.implement(authLoggedIn, {
+  setup: async (ctx, deps) => {
+    const email = ctx.uniqueEmail();
+    // Create user, set cookies via ctx.setCookie()
+    return { userId: ctx.fixed("user-123") };
+  },
+  teardown: async (ctx) => {
+    // Clean up using ctx.data
+  },
+});
+```
+
+**SetupContext provides:**
+
+- `ctx.runId` — unique UUID for this test run
+- `ctx.fixed(value)` — static test value
+- `ctx.uniqueId(prefix)` — generate unique ID (e.g., `ripplo-test-abc123`)
+- `ctx.uniqueEmail()` — generate unique email
+- `ctx.setCookie(name, value, options?)` — inject auth cookies
+
+## Determinism Rules
+
+1. **Use `role()` locators exclusively.** Only use `testId()` when no ARIA role is available.
+2. **All text assertions use exact matching.** No `contains`, `startsWith`, or regex.
+3. **Destructure precondition data in `steps()`.** Never hardcode names, IDs, or emails that come from preconditions.
+4. **Every step must have `.as("description")`.** No unlabeled steps.
+5. **No duplicate labels** within a test.
+6. **End with assertions** that verify the `expectedOutcome`.
+7. **After a test passes, run flake detection** to verify determinism across parallel runs.
+
+## CLI Commands
+
+```bash
+ripplo                              # Launch interactive dashboard
+ripplo lint [slugs..]               # Compile + lint tests (all or specific slugs)
+ripplo run [slugs..]                # Run tests in parallel
+ripplo list                         # List tests with status
+ripplo flake-detect <slug> --runs=10  # Run N times in parallel to detect flakiness
+```
+
+## Server Setup
+
+Your application server must expose the precondition endpoints under a single path prefix (the value you pass to `createRipplo({ preconditionsUrl })`). Pick the adapter that matches your framework — each handles webhook signature verification, cookie forwarding, and request parsing for you. Wrap the mount point behind an env guard (e.g. `ENABLE_RIPPLO_TESTING=true`) so it never ships to production.
+
+### Express
+
+```ts
+import express from "express";
+import { createExpressHandler } from "@ripplo/testing/express";
+import ripplo from "../.ripplo/ripplo.js";
+
+const app = express();
+app.use("/api/test/preconditions", createExpressHandler({ ripplo }));
+```
+
+Mounts both `PUT /execute-batch` and `PUT /teardown` under the prefix you choose.
+
+### Fastify
+
+```ts
+import Fastify from "fastify";
+import { registerFastifyHandler } from "@ripplo/testing/fastify";
+import ripplo from "../.ripplo/ripplo.js";
+
+const app = Fastify();
+await app.register(registerFastifyHandler({ ripplo }), {
+  prefix: "/api/test/preconditions",
+});
+```
+
+### Next.js (App Router)
+
+The Next.js adapter exports a single catch-all handler. Create one dynamic route file:
+
+```ts
+// app/api/test/preconditions/[action]/route.ts
+import { createNextHandler } from "@ripplo/testing/nextjs";
+import ripplo from "@/.ripplo/ripplo";
+
+export const PUT = createNextHandler({ ripplo });
+```
+
+The handler dispatches on the last URL segment (`execute-batch` or `teardown`) and returns 404 for anything else. It depends only on the Web `Request` / `Response` types, so it runs on both the Node and Edge runtimes — no `next` import required.
+
+### Custom integration (raw engine)
+
+If your framework isn't covered above (Hono, Koa, Bun, Deno, Cloudflare Workers, etc.), use the raw engine directly. The adapters are thin wrappers over the same API.
+
+```ts
+import {
+  buildSetCookieHeader,
+  createEngine,
+  serializeCookie,
+  verifyWebhookSignature,
+} from "@ripplo/testing";
+import ripplo from "../.ripplo/ripplo.js";
+
+const engine = createEngine(ripplo);
+const webhookSecret = ripplo.getConfig().webhookSecret;
+
+// PUT /api/test/preconditions/execute-batch
+async function executeBatch(req: Request): Promise<Response> {
+  const body = await req.text();
+  const verified = verifyWebhookSignature(
+    body,
+    {
+      "webhook-id": req.headers.get("webhook-id") ?? undefined,
+      "webhook-signature": req.headers.get("webhook-signature") ?? undefined,
+      "webhook-timestamp": req.headers.get("webhook-timestamp") ?? undefined,
+    },
+    webhookSecret,
+  );
+  if (!verified) {
+    return new Response(JSON.stringify({ error: "Invalid signature" }), { status: 401 });
+  }
+
+  const { preconditions } = JSON.parse(body);
+  const appUrl = `${req.headers.get("x-forwarded-proto") ?? "http"}://${req.headers.get("host")}`;
+  const result = await engine.executeBatch(preconditions, { appUrl });
+
+  const headers = new Headers({ "content-type": "application/json" });
+  result.cookies.forEach((c) => {
+    headers.append("Set-Cookie", buildSetCookieHeader(serializeCookie(c)));
+  });
+  return new Response(JSON.stringify(result), { headers });
+}
+
+// PUT /api/test/preconditions/teardown
+async function teardown(req: Request): Promise<Response> {
+  // ... same verify pattern, then:
+  // await engine.teardown(parsed.preconditions, parsed.data);
+}
+```
+
+**You're responsible for:**
+
+- **Webhook verification.** Always call `verifyWebhookSignature` before invoking the engine.
+- **Routing.** Dispatch the two endpoints (`execute-batch`, `teardown`) however your framework handles routes.
+- **Cookie forwarding.** `result.cookies` contains the cookies preconditions set during setup — they must reach the test browser as `Set-Cookie` headers, or login/session preconditions will silently fail.
+- **Body parsing.** Use the raw text body for signature verification, then `JSON.parse` for the engine call.
+
+### Config
+
+After mounting, point Ripplo at the prefix:
+
+```ts
+// .ripplo/ripplo.ts
+import { createRipplo } from "@ripplo/testing";
+
+export default createRipplo({
+  appUrl: process.env.APP_URL,
+  preconditionsUrl: `${process.env.APP_URL}/api/test/preconditions`,
+  projectId: "...",
+  webhookSecret: process.env.RIPPLO_WEBHOOK_SECRET,
+});
+```
+
+## Precondition API Contract
+
+The app server exposes two endpoints for test data management:
+
+### Execute (`PUT {preconditionApiPath}/execute`)
+
+```json
+// Request
+{ "precondition": "data:project" }
+
+// Response
+{ "success": true, "data": { "projectId": "cuid-abc", "orgId": "org-xyz" } }
+```
+
+Returns data that flows into test variables. Set-Cookie headers are captured automatically.
+
+### Teardown (`PUT {preconditionApiPath}/teardown`)
+
+```json
+// Request
+{ "preconditions": ["auth:logged-in", "data:project"] }
+
+// Response
+{ "success": true }
+```
+
+### Parallel Safety
+
+- Generate unique names/emails per run using `crypto.randomUUID()` suffixes
+- Return created entity IDs in the `data` response
+- Teardown only deletes that run's data (use session cookies to identify user)
+- Never hardcode entity names or use bulk deletion
+
+### Webhook Signing
+
+All requests are signed using Standard Webhooks (HMAC-SHA256). Headers: `webhook-id`, `webhook-timestamp`, `webhook-signature`. Verify before executing.
+
+### Environment Guard
+
+Wrap all precondition routes behind `ENABLE_RIPPLO_TESTING=true`. Never expose in production.

package/dist/actions.d.ts

@@ -0,0 +1,233 @@
+import { U as UnlabeledStep } from './step-DLfkKI3V.js';
+import { CheckLocator, InputLocator, AnyLocator, SelectLocator } from './locators.js';
+import '@ripplo/spec';
+
+declare function navigate(url: string): UnlabeledStep<{
+    type: "goto";
+    url: {
+        type: "static";
+        value: string;
+    };
+}>;
+declare function click(locator: AnyLocator): UnlabeledStep<{
+    locator: {
+        by: "testId";
+        value: string;
+    } | {
+        by: "role";
+        role: string;
+        name?: string | undefined;
+    };
+    type: "click";
+}>;
+declare function fill(locator: InputLocator, value: string): UnlabeledStep<{
+    locator: {
+        by: "testId";
+        value: string;
+    } | {
+        by: "role";
+        role: string;
+        name?: string | undefined;
+    };
+    type: "fill";
+    value: {
+        type: "static";
+        value: string;
+    };
+}>;
+declare function select(locator: SelectLocator, value: string): UnlabeledStep<{
+    locator: {
+        by: "testId";
+        value: string;
+    } | {
+        by: "role";
+        role: string;
+        name?: string | undefined;
+    };
+    type: "select";
+    value: {
+        type: "static";
+        value: string;
+    };
+}>;
+declare function check(locator: CheckLocator): UnlabeledStep<{
+    locator: {
+        by: "testId";
+        value: string;
+    } | {
+        by: "role";
+        role: string;
+        name?: string | undefined;
+    };
+    type: "check";
+}>;
+declare function uncheck(locator: CheckLocator): UnlabeledStep<{
+    locator: {
+        by: "testId";
+        value: string;
+    } | {
+        by: "role";
+        role: string;
+        name?: string | undefined;
+    };
+    type: "uncheck";
+}>;
+declare function hover(locator: AnyLocator): UnlabeledStep<{
+    locator: {
+        by: "testId";
+        value: string;
+    } | {
+        by: "role";
+        role: string;
+        name?: string | undefined;
+    };
+    type: "hover";
+}>;
+declare function press(key: string): UnlabeledStep<{
+    key: string;
+    type: "press";
+}>;
+declare function upload(locator: AnyLocator, path: string): UnlabeledStep<{
+    files: string[];
+    locator: {
+        by: "testId";
+        value: string;
+    } | {
+        by: "role";
+        role: string;
+        name?: string | undefined;
+    };
+    type: "upload";
+}>;
+declare function dblclick(locator: AnyLocator): UnlabeledStep<{
+    locator: {
+        by: "testId";
+        value: string;
+    } | {
+        by: "role";
+        role: string;
+        name?: string | undefined;
+    };
+    type: "dblclick";
+}>;
+declare function focus(locator: AnyLocator): UnlabeledStep<{
+    locator: {
+        by: "testId";
+        value: string;
+    } | {
+        by: "role";
+        role: string;
+        name?: string | undefined;
+    };
+    type: "focus";
+}>;
+declare function clear(locator: InputLocator): UnlabeledStep<{
+    locator: {
+        by: "testId";
+        value: string;
+    } | {
+        by: "role";
+        role: string;
+        name?: string | undefined;
+    };
+    type: "clear";
+}>;
+declare function typeText(locator: InputLocator, value: string): UnlabeledStep<{
+    locator: {
+        by: "testId";
+        value: string;
+    } | {
+        by: "role";
+        role: string;
+        name?: string | undefined;
+    };
+    type: "type";
+    value: {
+        type: "static";
+        value: string;
+    };
+}>;
+declare function rightClick(locator: AnyLocator): UnlabeledStep<{
+    locator: {
+        by: "testId";
+        value: string;
+    } | {
+        by: "role";
+        role: string;
+        name?: string | undefined;
+    };
+    type: "rightClick";
+}>;
+declare function scrollIntoView(locator: AnyLocator): UnlabeledStep<{
+    locator: {
+        by: "testId";
+        value: string;
+    } | {
+        by: "role";
+        role: string;
+        name?: string | undefined;
+    };
+    type: "scrollIntoView";
+}>;
+declare function drag(source: AnyLocator, target: AnyLocator): UnlabeledStep<{
+    source: {
+        by: "testId";
+        value: string;
+    } | {
+        by: "role";
+        role: string;
+        name?: string | undefined;
+    };
+    target: {
+        by: "testId";
+        value: string;
+    } | {
+        by: "role";
+        role: string;
+        name?: string | undefined;
+    };
+    type: "drag";
+}>;
+interface HandleDialogOptions {
+    readonly action: "accept" | "dismiss";
+    readonly promptText: string | undefined;
+}
+declare function handleDialog({ action, promptText }: HandleDialogOptions): UnlabeledStep<{
+    action: "accept" | "dismiss";
+    promptText: string | undefined;
+    type: "handleDialog";
+}>;
+interface ClipboardOptions {
+    readonly action: "read" | "write";
+    readonly value: string | undefined;
+    readonly variable: string | undefined;
+}
+declare function clipboard({ action, value, variable }: ClipboardOptions): UnlabeledStep<{
+    action: "read" | "write";
+    type: "clipboard";
+    value: {
+        type: "static";
+        value: string;
+    } | undefined;
+    variable: string | undefined;
+}>;
+interface SetPermissionOptions {
+    readonly permission: string;
+    readonly state: "granted" | "prompt";
+}
+declare function setPermission({ permission, state }: SetPermissionOptions): UnlabeledStep<{
+    permission: string;
+    state: "granted" | "prompt";
+    type: "setPermission";
+}>;
+interface SetViewportOptions {
+    readonly height: number;
+    readonly width: number;
+}
+declare function setViewport({ height, width }: SetViewportOptions): UnlabeledStep<{
+    height: number;
+    type: "setViewport";
+    width: number;
+}>;
+
+export { check, clear, click, clipboard, dblclick, drag, fill, focus, handleDialog, hover, navigate, press, rightClick, scrollIntoView, select, setPermission, setViewport, typeText, uncheck, upload };