ripplo

CLI for Ripplo. Typed end-to-end tests with real backend state.

Run via npx ripplo <command> so you always pick up the latest version. No global install needed.

Recommended setup: Claude Code plugin

If you use Claude Code, this is the shortest path. The plugin handles auth, scaffolding, and adapter wiring, and adds hooks that keep tests in sync with code changes.

/plugin marketplace add ripplo/claude-plugin
/plugin install ripplo
/ripplo:setup

That's it. Skip the rest of this README unless you want to know what /ripplo:setup is doing under the hood, or you're not on Claude Code.

Manual setup

Three steps: authenticate, scaffold, mount the adapter in your app server.

npx ripplo auth login   # device-code flow, opens a browser
npx ripplo init         # scaffolds .ripplo/ and writes RIPPLO_* env vars

ripplo init is interactive. It creates .ripplo/{index.ts, project.json, preconditions/, observers/, tests/}, appends RIPPLO_APP_URL, RIPPLO_ENGINE_URL, and RIPPLO_WEBHOOK_SECRET to your env file, and installs @ripplo/testing.

Then mount the adapter in your app server. Next.js App Router:

// app/ripplo/[action]/route.ts
import { createNextHandler } from "@ripplo/testing/nextjs";
import { engine } from "@/server/test/engine";

export const PUT = createNextHandler({
  enabled: process.env.ENABLE_RIPPLO_TESTING === "true",
  engine,
});

For Express, Fastify, Hono, Koa, NestJS, or Elysia, see @ripplo/testing.

engine is what you write in src/test/engine.ts to provide the implementations for the preconditions and observers you defined in .ripplo/. The DSL reference covers it.

Running tests

In one terminal, start the local executor:

npx ripplo watch

Leave it running alongside your dev server. It subscribes to run requests and drives Playwright against your local app.

In another, run tests:

npx ripplo run            # scope + dirty tests
npx ripplo run --all      # everything
npx ripplo run my-test    # by id

Commit .ripplo/ripplo.lock. The Ripplo server reads it on every push webhook; ripplo compile --check in a pre-commit hook keeps it fresh.

Worktrees

Ripplo is built for parallel feature work via git worktree. Each worktree gets its own dev session, scope, debug artifacts, and lockfile checkout — your auth token, projectId, and webhook secret are shared globally, so a fresh worktree needs no re-auth or re-init. Spin up as many as you want and run them concurrently.

Two things to know: env files are usually gitignored, so copy your .env.local into the new worktree (or point envFiles in .ripplo/project.json at a shared file outside the tree), and pick a distinct dev-server port — update both RIPPLO_APP_URL and RIPPLO_ENGINE_URL to match. ripplo doctor flags both.

Other commands

npx ripplo --help lists everything. The ones you'll use beyond setup: lint (compile + typecheck), doctor (auth/env/lockfile health), scope (manage what the current session is testing), flake-detect (run a test in parallel N times).