mgf-uitest-web

Browser-level UI testing for the Magogi web consoles — the missing tier.

Every Magogi web console (ProofWarden / mgf-test-web, the federation dashboard / mgf-fed-web, the cloud console / mgf-cloud-web) is a FastAPI + Jinja server-rendered app that, until now, was tested only through an in-process TestClient. A TestClient renders no CSS, runs no JavaScript, and never opens a browser — so it cannot see the things an operator actually notices. This package closes that gap: it drives each console in a real Chromium via Playwright and asserts the pillars a TestClient can't.

§1. The pillars

1. Layout integrity — reads the browser's real geometry to catch content that spills past its box (text outside a border, an element pushed beyond the viewport). Deterministic; no image baseline to bless.
2. Functional — drive the real golden paths and assert outcomes.
3. Accessibility — axe-core, no serious/critical violations.
4. Runtime health — zero application console errors and network failures. Main-frame accessibility-tool requests are attributed by Chromium request id, so an axe inspection probe cannot fail the application while a real request for the same URL still does. Subframe and unknown-frame failures stay conservative, including out-of-process iframe traffic. Once the page exposes a dedicated worker, the watch permanently uses public network events for all traffic because worker fetches can report the main frame while living outside the page CDP target.
5. Responsive — the above across a width × theme matrix (Chunk 1+).
6. Visual gallery — screenshots (page × width × theme) for human eyeballing.

§2. How it drives a console

The harness treats each console as a black box over HTTP: it launches the console's own mgf-*-web CLI (from the console's own virtualenv) as a subprocess on an ephemeral port, waits until it serves, and points Chromium at it. The harness therefore never imports FastAPI/Jinja or any console's stack — its only dependency is the browser-driving tier (Playwright + axe).

§3. Family

The web half of the mgf-uitest family. A future mgf-uitest-qt sibling will carry the same pillar vocabulary to the PySide desktop apps; genuinely shared pieces (baseline/report plumbing) get extracted into mgf-uitest-core only once that second consumer exists — not on speculation.

§4. Status

Pre-alpha and published as an MGF Family sibling. mgf-fed-web and mgf-test-web consume it as their blocking real-browser UI gate; each console owns the specs that exercise its own rendered behavior.

§5. Setup

The harness uses Playwright's pinned Chromium — never a system-browser fallback, because a different browser can resolve CSS @import / relative URLs differently and produce findings that don't reproduce. Chromium also supplies the CDP request identity used to distinguish main-frame axe inspection traffic from application traffic. Subframes remain on Playwright's public events, so their inspection traffic is not hidden; callers supplying another browser keep that conservative public-event behavior for every frame. Dedicated-worker pages also use the conservative public path for all traffic for the rest of the watch, even after a worker closes. One-time:

uv venv
uv pip install -e ".[dev]"
python -m playwright install chromium

§6. Running the suite

PYTHONPATH=src python -m pytest tests/

Each console provides a console_launch fixture declaring how to start itself; the harness launches it as a black-box server and drives it in a real browser. Screenshots land in tests/_artifacts/gallery/ (page × width × theme).

The console specs live in the consoles, not here. Each console owns its own UI gate — mgf-fed-web and mgf-test-web carry their specs and their console_launch under their own tests/e2e/, so a change to a console's chrome is caught by that console's CI, and this harness stays console-free (it needs no sibling checkout to test itself). Worked examples: mgf-fed-web and mgf-test-web, tests/e2e/conftest.py in each. Consoles pick the gate up by depending on this package — mgf-fed's renderer then splices a dedicated ui-gate step into their pipeline.

This repo's own suite is partitioned by tier: tests/unit/ + tests/smoke/ (no browser) and tests/integration/ (a real Chromium against a stdlib static server — so the Console contract is proven with no console repo present). CI runs tiers 0–2 and covers 95% of the package.

§7. Standards conformance

mgf-uitest-web declares L2 — Standard (CFM-02): conform to every MUST rule, evidenced by the per-rule audit and later seeded corpus rows in docs/inprogress/MGF_STANDARDS_CONFORMANCE.md. The original 265-MUST audit remains its measured historical frame; later rules are tracked explicitly instead of being folded into that old count.

The public contract is PUBLIC_API.md (every name, its stability tier); the boundary is SCOPE.md.