logan
5ca6cad45a
A coding agent could develop this repo's Go packages and could not develop the application: every path to running YellowJacket ended in a blocking GTK window, so 265 bound methods, 46 events, 33 component directories and 13 stores had exactly one form of verification available — `tsc --noEmit`. The unlock is that `wails dev`'s dev server on :34115 serves the real frontend with the real generated bindings against the same Go backend a desktop window attaches to, so a plain Chromium under Xvfb gets a fully functional app. Four test tiers now exist, cheapest first: - `make ui-test` — 313 Vitest tests in a real browser in ~2 s, no app, no backend, no display. Works because `frontend/wailsjs/` is a pure passthrough to `window.go`/`window.runtime`, so faking just those two globals runs the real bindings and the real store code. - `make test` — services in-process, asserting on the payload the frontend would receive, via a new `events.Emit` wrapper. - `make dev-headless` + `playwright-cli` — the real app, driven interactively, with an event bridge on `window.__yjEvents` and a dev-only control surface at `/__test/`. - `make e2e` — 19 of those flows frozen as Playwright specs. `events.Emit(ctx, …)` replaces all 35 direct `runtime.EventsEmit` call sites: wails' `getEvents` `log.Fatalf`s on any context without its runtime, so those paths could not run under test and a background worker could take the app down. Four packages had each hand-rolled the same guard; nine more guarded on `ctx != nil`, which does not help. `TestNoDirectRuntimeEmits` fails the build on a new one. Fixtures are generated, not committed (`make testdata`), and seeds are built by *running the app* — never by hand-writing config and DB rows, which would be a second description of a valid YJ_HOME. `.gitea/workflows/ci.yml` is the first workflow here that tests anything; the other three only package, so `gitea_ci` reported only packaging jobs and misled anyone asking whether a push was healthy. Both jobs were prototyped to green in a bare ubuntu:24.04 container before the YAML was written, which immediately caught `make lint` linting three configurations that nothing builds: all three passes omitted `webkit2_41`, so wails resolved webkit2gtk-4.0 — which Arch still ships and Ubuntu 24.04 dropped. Operational instructions live in `.pi/skills/yellowjacket-dev/`, measured discoveries in `.planning/NOTES.md`, and architecture in `CLAUDE.md` — split by tense, not by topic, because a topical split gives every new fact two plausible homes. `make skill-check` fails a commit if the skill cites a make target that does not exist.
86 lines
4.0 KiB
Markdown
86 lines
4.0 KiB
Markdown
# The harness: event bridge and control surface
|
|
|
|
Two things ride on top of the headless app. Both exist only in dev
|
|
builds; neither is reachable from a shipped binary.
|
|
|
|
## The event bridge (`.playwright/init-events.js`)
|
|
|
|
Loaded as an `initScript` by `.playwright/cli.config.json` and by
|
|
`e2e/support/fixtures.ts`, so an exploratory session and a committed
|
|
spec see an identical page. It records every backend event by wrapping
|
|
`window.wails.EventsNotify` — the single choke point all 46 events pass
|
|
through, whether or not the app subscribes to them.
|
|
|
|
```js
|
|
window.__yjEvents.wait('LibraryScanComplete', { timeoutMs: 60000 })
|
|
window.__yjEvents.names() // name -> count; use this to find out
|
|
// what actually fired before asserting
|
|
window.__yjEvents.last('QueueChanged')
|
|
window.__yjEvents.since(seq)
|
|
window.__yjEvents.reset() // drop the buffer
|
|
window.__yjEvents.ready(20000) // resolves when a binding round-trips,
|
|
// which is later than DOM-ready and true
|
|
window.__yjEvents.call('queue.Queue.GetState', [], 5000)
|
|
```
|
|
|
|
- **`wait` resolves against already-buffered events as well as future
|
|
ones**, so there is no race between doing the thing and listening.
|
|
- **Install exactly one recorder.** Listeners survive across `eval`
|
|
calls; a second recorder double-counts. Call `reset()`, never
|
|
re-register.
|
|
- **`call` times out on purpose.** A binding with wrong argument types
|
|
never fires its callback. A 5 s rejection naming `.dev/app.log` beats
|
|
an infinite hang.
|
|
|
|
In specs, use the wrappers rather than `page.evaluate`:
|
|
`waitForEvent`, `resetEvents`, `eventNames`, `callBinding`, and the
|
|
`app` fixture (a page with the bridge installed and the backend
|
|
actually answering) from `e2e/support/fixtures.ts`.
|
|
|
|
## The control surface (`backend/testctl`, mounted at `/__test/`)
|
|
|
|
Gated twice: behind the `dev` build tag (with a no-op `!dev` twin) and
|
|
behind `YJ_TESTCTL=1`, which `scripts/dev-headless.sh` sets and
|
|
`make dev` does not.
|
|
|
|
| Endpoint | Use |
|
|
|---|---|
|
|
| `GET /__test/health` | is this a seeded dev build, and which library |
|
|
| `POST /__test/db/snapshot?name=X` | save the SQLite state |
|
|
| `POST /__test/db/restore?name=X` | put it back (see below) |
|
|
| `POST /__test/emit` `{name, data}` | force any backend event |
|
|
| `POST /__test/sql` `{sql, args}` | read rows, or a write count |
|
|
|
|
`TestCtl` in `e2e/support/fixtures.ts` is the typed client.
|
|
|
|
- **`emit` is the fast way to render a push-driven view** without
|
|
staging the work that would produce it — job progress, download
|
|
progress, scan progress. It calls `events.Deliver`, which *errors*
|
|
when the event reaches nobody, so a `200` means it really arrived.
|
|
- **`restore` is slow** (~40 s in the suite) because it copies every
|
|
table. Prefer snapshotting once and restoring only when a spec
|
|
genuinely mutates state.
|
|
|
|
## Traps in the config
|
|
|
|
- **The two path keys in `.playwright/cli.config.json` resolve
|
|
differently.** `initScript` is relative to the *config file's*
|
|
directory (`"init-events.js"`, not `".playwright/init-events.js"`);
|
|
`outputDir` is relative to the *shell's cwd*. Set `outputDir` to
|
|
`".playwright-cli"` and run `playwright-cli` from the repo root, or
|
|
snapshots land somewhere neither `.gitignore` nor your next `ls`
|
|
will find, and you will read a stale one from a previous session
|
|
and think a component regressed.
|
|
- **`snapshot` writes a file, it does not print the tree.** The
|
|
command prints a path under `outputDir`; read that. Only the tail
|
|
is echoed.
|
|
- **Three separate browser caches.** `playwright-cli`, `@playwright/test`
|
|
(`make e2e-setup`) and the Vitest provider (`make ui-setup`) each
|
|
download their own Chromium. One working is no guarantee for the next.
|
|
- **`getByRole('button', { name })` matches substrings.** "Play" also
|
|
matches "Add queue to playlist"; transport controls need
|
|
`exact: true`.
|
|
- **`e2e/` is its own npm package** with `"type": "module"`. Without
|
|
that, Playwright transpiles the specs to CJS and every `import.meta`
|
|
throws — reported, unhelpfully, as "No tests found".
|