yonlu
62c1a95ead
Both specs stage a job through `/__test/emit` and neither cleared it. Nothing resets those stores, so the spec that staged it is the one that should put it back, and `JobsChanged` with `[]` is the whole cleanup -- `JobStore` replaces its list from every snapshot, so `testctl` needs no special case. **The leak as reported did not reproduce, and that is worth recording rather than quietly fixing.** Measured with a temporary probe: a positive control confirmed a staged job really does move the shell at a phone width (`job-band` renders a row, `.main-panel`'s top goes 0 to 55), and the very next page had no job at all. The reason is that every test gets a fresh page and `JobStore.init()` refetches `GetJobs()` from a backend registry `/__test/emit` never writes to -- it calls `events.Deliver`, which touches frontends and no state. So the state cannot cross a spec boundary as described, and the 55px offset the draft assertion saw in that suite run has another cause that is not in evidence. The cleanup stays, because it costs a line and the leak would need only one spec that keeps a page alive, and the comments say what was measured rather than asserting the mechanism. The durable half is the rule, now in the harness reference: measure against the element next to you, not an absolute coordinate. An absolute number in a shell measurement is also a claim about everything above it -- `contentTop === 0` asserts "and no background job is running", which that spec could not arrange. Closes #168
106 lines
5.3 KiB
Markdown
106 lines
5.3 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.
|
|
- **State you stage, you own** (#168). Nothing resets those stores, so
|
|
clear yours in `test.afterEach` with the same event that staged it
|
|
(`emit('JobsChanged', [])`) — the store replaces its list from every
|
|
snapshot, so `testctl` needs no special case. **Measured: this does
|
|
not currently cross a spec boundary**, because every test gets a fresh
|
|
page and `JobStore.init()` refetches `GetJobs()` from a backend
|
|
registry that `/__test/emit` never writes to. Stated anyway, because
|
|
it costs one line and the leak needs only one spec that keeps a page
|
|
alive — but do not cite #168 for a symptom you have not reproduced.
|
|
- **Measure against the thing next to you, not an absolute
|
|
coordinate.** An absolute number in a shell measurement is also a
|
|
claim about everything above it — `contentTop === 0` quietly asserts
|
|
"and no background job is running", which is not what that spec was
|
|
about or could arrange, while `contentTop === jobBandBottom` is true
|
|
either way. This is the half of #168 that stands on its own.
|
|
- **`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.
|
|
- **Two separate browser caches.** `@playwright/test`
|
|
(`make e2e-setup`) and the Vitest provider (`make ui-setup`) each
|
|
download their own Chromium. One working is no guarantee for the
|
|
other. There used to be a third: `playwright-cli` was a *required*
|
|
dependency because `scripts/seed-sandbox.sh` drove `AddLibrary`
|
|
through a real page, `window.go` being v2's only way in. v3 answers
|
|
the same call over HTTP, so the seed is `curl` now and the CLI is
|
|
only an exploratory convenience.
|
|
- **`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".
|