ripplo 0.5.11 → 0.6.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +46 -53
- package/dist/index.js +170 -169
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,82 +1,75 @@
|
|
|
1
1
|
# ripplo
|
|
2
2
|
|
|
3
|
-
CLI for [Ripplo](https://ripplo.ai)
|
|
3
|
+
CLI for [Ripplo](https://ripplo.ai). Typed end-to-end tests with real backend state.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Run via `npx ripplo <command>` so you always pick up the latest version. No global install needed.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
npm install -g ripplo
|
|
9
|
-
# or: npx ripplo <subcommand>
|
|
10
|
-
```
|
|
7
|
+
## Recommended setup: Claude Code plugin
|
|
11
8
|
|
|
12
|
-
|
|
9
|
+
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.
|
|
13
10
|
|
|
14
|
-
```
|
|
15
|
-
|
|
16
|
-
|
|
11
|
+
```
|
|
12
|
+
/plugin marketplace add ripplo/claude-plugin
|
|
13
|
+
/plugin install ripplo
|
|
14
|
+
/ripplo:setup
|
|
17
15
|
```
|
|
18
16
|
|
|
19
|
-
|
|
17
|
+
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.
|
|
20
18
|
|
|
21
|
-
|
|
19
|
+
## Manual setup
|
|
20
|
+
|
|
21
|
+
Three steps: authenticate, scaffold, mount the adapter in your app server.
|
|
22
22
|
|
|
23
23
|
```sh
|
|
24
|
-
npx ripplo
|
|
24
|
+
npx ripplo auth login # device-code flow, opens a browser
|
|
25
|
+
npx ripplo init # scaffolds .ripplo/ and writes RIPPLO_* env vars
|
|
25
26
|
```
|
|
26
27
|
|
|
27
|
-
|
|
28
|
+
`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`.
|
|
28
29
|
|
|
29
|
-
|
|
30
|
+
Then mount the adapter in your app server. Next.js App Router:
|
|
30
31
|
|
|
31
|
-
|
|
32
|
+
```ts
|
|
33
|
+
// app/ripplo/[action]/route.ts
|
|
34
|
+
import { createNextHandler } from "@ripplo/testing/nextjs";
|
|
35
|
+
import { engine } from "@/server/test/engine";
|
|
36
|
+
|
|
37
|
+
export const PUT = createNextHandler({
|
|
38
|
+
enabled: process.env.ENABLE_RIPPLO_TESTING === "true",
|
|
39
|
+
engine,
|
|
40
|
+
});
|
|
41
|
+
```
|
|
32
42
|
|
|
33
|
-
|
|
43
|
+
For Express, Fastify, Hono, Koa, NestJS, or Elysia, see [`@ripplo/testing`](https://www.npmjs.com/package/@ripplo/testing).
|
|
34
44
|
|
|
35
|
-
|
|
45
|
+
`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.
|
|
36
46
|
|
|
37
|
-
|
|
38
|
-
- **Dev server port + URL vars.** Two sibling worktrees can't both run `pnpm dev` on the same port. Pick a distinct port for this worktree, **and update both `RIPPLO_APP_URL` and `RIPPLO_ENGINE_URL`** in this worktree's env file to match — e.g. main on `:3000` → this worktree on `:3001` → set `RIPPLO_APP_URL=http://localhost:3001` and `RIPPLO_ENGINE_URL=http://localhost:3001/ripplo`. If the URL vars stay pointing at main's port, `ripplo watch` talks to the wrong dev server.
|
|
47
|
+
## Running tests
|
|
39
48
|
|
|
40
|
-
|
|
49
|
+
In one terminal, start the local executor:
|
|
41
50
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
| `ripplo auth status` | Show current authentication |
|
|
46
|
-
| `ripplo auth logout` | Remove the saved token |
|
|
47
|
-
| `ripplo init` | Scaffold `.ripplo/` and write `RIPPLO_*` env vars |
|
|
48
|
-
| `ripplo watch` | Subscribe to run requests; execute tests against your dev server |
|
|
49
|
-
| `ripplo run [ids..]` | Run tests in parallel (defaults to scope + dirty tests; `--all` for full suite) |
|
|
50
|
-
| `ripplo lint [ids..]` | Compile and lint; writes `.ripplo/ripplo.lock` |
|
|
51
|
-
| `ripplo compile [--check]` | Rebuild the lockfile (`--check` = exit non-zero if stale; for CI/hooks) |
|
|
52
|
-
| `ripplo sync` | Push the compiled `.ripplo/` resources to the server (no run; useful for debugging sync state) |
|
|
53
|
-
| `ripplo doctor` | Check lockfile freshness, auth, env |
|
|
54
|
-
| `ripplo status` | Report unimplemented tests and preconditions |
|
|
55
|
-
| `ripplo cover` | Audit coverage statements across the whole tree |
|
|
56
|
-
| `ripplo scope <sub>` | Manage testing scope (`add`, `link`, `remove`, `status`) |
|
|
57
|
-
| `ripplo flake-detect <id>` | Run a test N times in parallel to detect flakiness |
|
|
51
|
+
```sh
|
|
52
|
+
npx ripplo watch
|
|
53
|
+
```
|
|
58
54
|
|
|
59
|
-
|
|
55
|
+
Leave it running alongside your dev server. It subscribes to run requests and drives Playwright against your local app.
|
|
60
56
|
|
|
61
|
-
|
|
57
|
+
In another, run tests:
|
|
62
58
|
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
├── ripplo.lock # generated + committed; read by the Ripplo server on push
|
|
68
|
-
├── preconditions/index.ts # handles + `preconditions` registry
|
|
69
|
-
├── observers/index.ts # handles + `observers` registry
|
|
70
|
-
└── tests/
|
|
71
|
-
└── <test-id>.ts # one TestDefinition per file
|
|
59
|
+
```sh
|
|
60
|
+
npx ripplo run # scope + dirty tests
|
|
61
|
+
npx ripplo run --all # everything
|
|
62
|
+
npx ripplo run my-test # by id
|
|
72
63
|
```
|
|
73
64
|
|
|
74
|
-
|
|
65
|
+
Commit `.ripplo/ripplo.lock`. The Ripplo server reads it on every push webhook; `ripplo compile --check` in a pre-commit hook keeps it fresh.
|
|
66
|
+
|
|
67
|
+
## Worktrees
|
|
75
68
|
|
|
76
|
-
|
|
69
|
+
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.
|
|
77
70
|
|
|
78
|
-
|
|
71
|
+
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.
|
|
79
72
|
|
|
80
|
-
|
|
73
|
+
## Other commands
|
|
81
74
|
|
|
82
|
-
|
|
75
|
+
`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).
|