@ripplo/testing 0.6.1 → 0.7.1

package/DSL.md

@@ -0,0 +1,357 @@
+# Ripplo DSL reference
+
+The complete primitive catalog for `@ripplo/testing`. The `/ripplo:create` skill covers the workflow and the model; this is the exhaustive "what exists" — every action, locator, predicate, field axis, and assertion with a signature and a one-line example.
+
+A project has four layers:
+
+- **Entities** (`.ripplo/entities/`) — the state model. Each entity gets a `seed`/`read` impl in the app's engine funnel.
+- **Singletons** (`.ripplo/singletons/`) — client/global state (e.g. localStorage flags).
+- **Worlds** (`.ripplo/worlds/`) — pure builder functions returning a flat record of entity handles (the starting state).
+- **Tests** (`.ripplo/tests/`) — `test("Intent", () => ({ given, steps }))`.
+
+Everything is imported from `@ripplo/testing`.
+
+---
+
+## Entities
+
+```ts
+import { entity, field, id, key, v } from "@ripplo/testing";
+
+export const Task = entity("task", {
+  description: "A task under a project",
+  fields: {
+    title: field({ value: v.word() }),
+    projectId: field({ value: v.id() }), // a foreign key is just an id-valued field
+    done: field({ value: v.boolean() }),
+    note: field({ optional: true, value: v.word() }), // nullable
+  },
+  identity: { id: id() },
+  source: "backend", // "backend" (DB) or "client" (browser state)
+});
+```
+
+- `entity(name, { description, fields, identity, source })` → an `EntityDef`. `name` is the dispatch key for the engine impl.
+
+### `source` — where the state lives
+
+Pick by where the state is persisted, not where it's displayed:
+
+- `source: "backend"` — the default for anything long-lived: database rows, server-side session state, anything that survives a page reload because the server has it. Seeded/read by the **server engine** (`createEngine` in your app's `test/engine.ts`).
+- `source: "client"` — state that lives only in the browser: localStorage, IndexedDB, in-memory stores that the app treats as state but never persists server-side. Seeded/read by the **client engine** (`mountClientEngine`, below). Reach for it when a flow's behavior depends on browser-local state you need to arrange or assert.
+
+If you're unsure, it's backend. A value that's cached in the browser but owned by the server is backend — model the server's row, not the cache.
+
+- A **field** is a free, seedable state dimension. Functionally-derived values (`slug = slugify(name)`) and server-defaulted values (`createdAt`) are **not** fields — drop them.
+
+### `field(options)`
+
+```ts
+field({ value: v.email() }); // required, stable, oracle holds observed == model
+field({ value: v.word(), optional: true }); // nullable; `null` is a valid set/assert value
+field({ value: v.number({ min: 0, max: 100 }), stable: false }); // adopt-only, drift not checked
+```
+
+| option     | meaning                                                                                                     |
+| ---------- | ----------------------------------------------------------------------------------------------------------- |
+| `value`    | the value-space (`v.*`) — required                                                                          |
+| `optional` | `true` ⇒ the field is nullable (`null` allowed in `of`/`updated`/assertions); oracle treats `null ≡ absent` |
+| `stable`   | default `true` (oracle holds `observed == model value`). `false` = adopt-only, drift unchecked              |
+
+### Identity: `id()` and `key(options)`
+
+```ts
+identity: {
+  id: id();
+} // surrogate key — server-assigned (cuid/autoincrement), adopted
+identity: {
+  email: key({ value: v.email() });
+} // natural key — you supply the value
+```
+
+### Value-spaces (`v.*`)
+
+| builder                                    | yields  | notes                                                       |
+| ------------------------------------------ | ------- | ----------------------------------------------------------- |
+| `v.email()`                                | string  | realistic email                                             |
+| `v.fullName()`                             | string  | person name                                                 |
+| `v.companyName()`                          | string  | org name                                                    |
+| `v.slug()`                                 | string  | url-safe slug                                               |
+| `v.word()`                                 | string  | single token                                                |
+| `v.url()`                                  | string  | URL                                                         |
+| `v.id()`                                   | string  | id-shaped string (use for FKs)                              |
+| `v.number({ min, max })`                   | number  | bounded integer                                             |
+| `v.boolean()`                              | boolean |                                                             |
+| `v.oneOf([...])`                           | any     | enum — one of the listed values                             |
+| `v.datetime({ offsetDays: { min, max } })` | string  | ISO-8601 timestamp, offset days relative to the run's start |
+
+String spaces take optional constraints: `v.word({ minLength, maxLength, pattern })`. `v.number` requires `{ min, max }`. `v.oneOf` types narrowly with `as const`-style tuples: `v.oneOf(["PENDING", "ACCEPTED"])`. `v.datetime` values are generated relative to the run's start timestamp (e.g. `{ min: -30, max: 1 }` = up to 30 days past, 1 day future); the oracle compares datetimes by UTC instant, so driver formatting/timezone rendering differences never diverge.
+
+---
+
+## Worlds
+
+Pure functions in `.ripplo/worlds/index.ts` returning a flat record of handles. Compose from other worlds.
+
+```ts
+import { arbitrary } from "@ripplo/testing";
+import { Project, Task, User } from "../entities/index.js";
+
+export const ownedProject = () => {
+  const me = User.of({ email: arbitrary(User.field.email) });
+  const project = Project.of({ name: arbitrary(Project.field.name), ownerId: me.id });
+  return { me, project };
+};
+
+export const projectWithTask = () => {
+  const base = ownedProject();
+  const task = Task.of({ title: arbitrary(Task.field.title), projectId: base.project.id });
+  return { ...base, task };
+};
+```
+
+### Entity handles in a world
+
+| method                | meaning                                                                                 |
+| --------------------- | --------------------------------------------------------------------------------------- |
+| `Entity.of(props)`    | a row that is **guaranteed** present                                                    |
+| `Entity.only(props)`  | exactly one such row (singleton in the world)                                           |
+| `Entity.maybe(props)` | optionally present (fuzz covers both branches)                                          |
+| `Entity.none(where)`  | asserts **absence** — no row matches (returns an absence handle; include it in `given`) |
+
+- `arbitrary(Entity.field.x)` — draws a fresh value for field `x`. A fresh param each call.
+- Wire a foreign key by passing a parent handle's id: `projectId: base.project.id`.
+- `Entity.field.x` is a `FieldHandle` — a reference to the field, used in `arbitrary(...)`.
+- A world MUST return every handle it creates (a dropped const → `no-unused-vars`, or a dangling-ref throw at compile).
+
+---
+
+## Tests
+
+```ts
+import { button, click, fill, goto, test, textbox, visible } from "@ripplo/testing";
+import { Task } from "../entities/index.js";
+import { ownedProject } from "../worlds/index.js";
+
+export const createTask = test("Create a task", () => {
+  const { me, project } = ownedProject();
+  return {
+    given: [me, project], // arrange: all the handles this test needs
+    steps: [
+      // act + assert
+      goto`/projects/${project.id}/tasks`.expect(visible(button("New"))),
+      click(button("New")).expect(visible(textbox("Title"))),
+      fill(textbox("Title"), "Buy milk"),
+      click(button("Create")).expect(Task.created({ title: "Buy milk", projectId: project.id })),
+    ],
+  };
+});
+
+export const renameTask = test("Rename a task"); // STUB — no body; gated until implemented
+```
+
+- `test(intent)` (no body) → a **stub**; `test(intent, () => body)` → an implemented test.
+- The test body returns `{ given, steps }`. The arrange/act boundary is `given:` vs `steps:`.
+- Everything a step references must trace to a handle in `given`.
+
+---
+
+## Actions
+
+Each returns a step; chain `.expect(...predicates)` to assert after it runs.
+
+| action     | signature                      | example                                  |
+| ---------- | ------------------------------ | ---------------------------------------- |
+| `goto`     | `` goto`/path/${handle.id}` `` | `` goto`/projects/${p.id}` ``            |
+| `click`    | `click(locator)`               | `click(button("Save"))`                  |
+| `dblclick` | `dblclick(locator)`            | `dblclick(testId\`row-${r.id}\`)`        |
+| `fill`     | `fill(locator, value)`         | `fill(textbox("Name"), "Acme")`          |
+| `clear`    | `clear(locator)`               | `clear(textbox("Name"))`                 |
+| `select`   | `select(locator, value)`       | `select(combobox("Plan"), "pro")`        |
+| `check`    | `check(locator)`               | `check(checkbox("Agree"))`               |
+| `uncheck`  | `uncheck(locator)`             | `uncheck(checkbox("Agree"))`             |
+| `hover`    | `hover(locator)`               | `hover(button("More"))`                  |
+| `upload`   | `upload(locator, files)`       | `upload(testId\`avatar\`, ["face.png"])` |
+| `press`    | `press(key, locator?)`         | `press("Enter", textbox("Search"))`      |
+
+`fill`/`select`/`value`/`text` accept a literal string or a `Binding<string>` (e.g. `arbitrary(...)` or a handle field). `goto`/`testId` are template literals — interpolate handle ids directly.
+
+```ts
+const title = arbitrary(Task.field.title);
+goto`/projects/${project.id}/tasks`.expect(...)
+fill(textbox("Title"), title)
+```
+
+---
+
+## Locators
+
+| locator  | signature                               | resolves to                                     |
+| -------- | --------------------------------------- | ----------------------------------------------- |
+| `role`   | `role(roleName, name?)`                 | any ARIA role, optional accessible name         |
+| `inside` | `inside(scope, target)`                 | target located within scope; nests arbitrarily  |
+| `testId` | `` testId\`...\` `` or `testId(string)` | a `data-testid` — only when no ARIA role exists |
+
+Named locators — `(name, ...bindings)`, accessible name **required**:
+
+`alertdialog` `button` `cell` `checkbox` `columnheader` `combobox` `dialog` `heading` `img` `link` `listitem` `menuitem` `option` `radio` `row` `searchbox` `slider` `spinbutton` `switchControl` (role `switch` — `switch` is a JS keyword) `tab` `textbox` `treeitem`
+
+Container/landmark locators — `(name?, ...bindings)`, name optional (often unique per page):
+
+`alert` `banner` `complementary` `contentinfo` `form` `grid` `group` `list` `main` `menu` `navigation` `progressbar` `radiogroup` `region` `status` `table` `tablist` `tabpanel` `toolbar`
+
+Anything else: `role("menubar", name)` — every ARIA role works through `role()`. Prefer the named sugar above when one exists.
+
+Radix/shadcn gotchas: toggles render role `switch` (use `switchControl`, not `checkbox`); confirm dialogs render role `alertdialog` (use `alertdialog`, not `dialog`).
+
+Names are matched **exactly** — no `contains`/regex. If the app lacks an accessible name, add one to the app rather than falling back to `testId`. Container rows/dialogs usually need an explicit `aria-label` to be scopable — add it to the app.
+
+Every role-locator name accepts a binding or a template literal, same as `testId`:
+
+```ts
+click(button(user.name)); // binding as the accessible name
+click(inside(row(schedule.name), button("Delete"))); // scoped: the Delete in this row
+click(inside(dialog`Edit ${schedule.name}`, button("Save"))); // template-literal name
+click(inside(main(), button("New"))); // disambiguate from a header CTA
+```
+
+---
+
+## Predicates (UI assertions)
+
+Used inside a step's `.expect(...)`.
+
+| predicate  | signature                         | asserts                                   |
+| ---------- | --------------------------------- | ----------------------------------------- |
+| `visible`  | `visible(locator)`                | element is visible                        |
+| `disabled` | `disabled(locator)`               | element is disabled                       |
+| `enabled`  | `enabled(locator)`                | element is enabled                        |
+| `focused`  | `focused(locator)`                | element has focus                         |
+| `value`    | `value(locator, string\|binding)` | input's value equals                      |
+| `text`     | `text(locator, string\|binding)`  | element's text equals                     |
+| `not`      | `not(predicate)`                  | negation — `not(visible(role("dialog")))` |
+| `and`      | `and(...conditions)`              | conjunction                               |
+| `when`     | `when(...clauses)`                | conditional assertion                     |
+| `count`    | `count(Entity).is(n)`             | n rows of the entity exist                |
+
+### Browser singletons
+
+```ts
+import { title, url, viewport } from "@ripplo/testing";
+goto`/projects/${p.id}`.expect(url.is`/projects/${p.id}`); // url/title/viewport carry `.is`
+```
+
+---
+
+## Backend assertions (the oracle)
+
+Put these in a step's `.expect(...)` alongside UI predicates. The oracle does a 3-way compare (model-before / predicted-after / observed) and flags divergence — you never poll.
+
+```ts
+import { changed, within } from "@ripplo/testing";
+
+Task.created({ title: "Buy milk", projectId: p.id }); // a row with these fields now exists
+Task.updated({ id: task.id }, { title: "Buy bread" }); // the keyed row changed to this
+Task.updated({ id: org.id }, { secret: changed() }); // changed to a server-chosen value (rotation)
+Task.deleted({ id: task.id }); // the keyed row is gone
+```
+
+- `Entity.created(props)` — assert a creation.
+- `Entity.updated(key, changes)` — assert an update on the row matching `key`. Use `changed()` as a value when the new value is server-chosen (assert it _differs_ without pinning it).
+- `Entity.deleted(key)` — assert deletion.
+- Consistency timing is automatic: a field declared `consistency: "eventual"` (or a `changed()` baseline) tolerates propagation lag; default `strict` fails fast on a wrong intermediate value.
+
+### Relational selection (`where` / `within`)
+
+For assertions scoped by a subquery — "delete every task in projects this user owns":
+
+```ts
+Task.deleted({ projectId: within(Project.where({ ownerId: me.id }), "id") }); // tasks whose projectId ∈ owned project ids
+```
+
+- `Entity.where(criteria)` — a subquery.
+- `within(selection, "sourceField")` — used as a key value: matches when that column's value is in the `sourceField` values of the subquery's matching rows.
+- Selections nest arbitrarily (a subquery's `where` accepts `within` too).
+
+---
+
+## Singletons (client/global state)
+
+```ts
+import { singleton, v } from "@ripplo/testing";
+
+export const onboardingDismissed = singleton("onboardingDismissed", {
+  default: false,
+  description: "user dismissed the onboarding flow (localStorage)",
+  source: "client",
+  value: v.boolean(),
+});
+
+export const singletons = [onboardingDismissed];
+```
+
+Set in a test's body (`singletons:`) and assert via predicates; the client engine seeds/reads them in the browser.
+
+### The client engine
+
+`client`-sourced entities and singletons need a browser-side counterpart to the server engine: a `seed`/`read` impl per declaration, mounted once in your app's client entry. TS exhaustiveness-checks it the same way — every `source: "client"` declaration must have an impl.
+
+```ts
+// app client entry (dev/test builds)
+import { mountClientEngine } from "@ripplo/testing";
+import ripplo from "../../.ripplo/index.js";
+
+mountClientEngine(
+  ripplo,
+  {
+    entities: {},
+    singletons: {
+      onboardingDismissed: {
+        read: () => JSON.parse(localStorage.getItem("onboarding-dismissed") ?? "null"),
+        seed: (value) => localStorage.setItem("onboarding-dismissed", JSON.stringify(value)),
+      },
+    },
+  },
+  // gate with a TARGETED build-time flag (mirrors the server's ENABLE_RIPPLO_TESTING) so the
+  // mount stays out of untested production bundles while still allowing runs against prod builds
+  // (Vite: VITE_ENABLE_RIPPLO_TESTING; Next.js: NEXT_PUBLIC_ENABLE_RIPPLO_TESTING)
+  { enabled: import.meta.env.VITE_ENABLE_RIPPLO_TESTING === "true" },
+);
+```
+
+The runtime injects seeds before the page loads and reads state through the mount during assertions. Backend entities never appear here — they belong to the server engine.
+
+---
+
+---
+
+## Engine impls
+
+Each entity needs a `seed`/`read` implementation in the app's engine funnel, exhaustiveness-checked by TS.
+
+```ts
+import { createEngine, type EngineImpls } from "@ripplo/testing";
+import ripplo from "../../.ripplo/index.js";
+
+type Impls = EngineImpls<typeof ripplo, "backend">["entities"];
+
+const impls: Impls = {
+  task: {
+    seed: async ({ fields, runId }) => {
+      const id = testId(runId, "task"); // run-scoped id for parallel isolation
+      await db.task.create({ data: { id, title: fields.title, projectId: fields.projectId } });
+      return { row: { id, title: fields.title, projectId: fields.projectId }, session: undefined };
+    },
+    read: async ({ runId }) =>
+      (await db.task.findMany({ where: { projectId: { startsWith: runPrefix(runId) } } })).map(
+        (t) => ({ id: t.id, title: t.title, projectId: t.projectId }),
+      ),
+  },
+};
+
+export const engine = createEngine(ripplo, { entities: impls, singletons: {} }, teardown);
+```
+
+- **`seed`** creates one row from `fields`, returns `{ row, session }` (`session` = an auth session for identity entities like `user`/`session`, else `undefined`).
+- **`read`** returns this run's rows of the entity. Scope every query by the run so the oracle only sees this run's data.
+- Isolation lives here, not in the test: run-scoped ids in `seed`, run-scoped queries in `read`. Never `update`/`delete` rows your run didn't create.

package/LICENSE.md

@@ -0,0 +1 @@
+© Ripplo LLC. All rights reserved. Use is subject to Ripplo's [Terms of Service](https://ripplo.ai/terms).