yellowjacket/.pi/skills/yellowjacket-dev/references/harness.md

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.

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".