Metadata-Version: 2.5
Name: mgf-uitest-web
Version: 0.1.2
Summary: Shared browser-level UI testing for the Magogi web consoles — drives each FastAPI+Jinja console (ProofWarden, fed-web, cloud-web) in a real Chromium via Playwright and asserts the pillars an in-process TestClient can't see: layout integrity (no content spilling past its box), functionality, accessibility (axe-core), and runtime health (no console/network errors), across a width x theme matrix. The web half of the mgf-uitest family (Qt sibling: mgf-uitest-qt). Sibling under the mgf.* namespace.
Project-URL: Homepage, https://codeberg.org/magogi-admin/mgf-uitest-web
Project-URL: Issues, https://codeberg.org/magogi-admin/mgf-uitest-web/issues
Author: Bassam Alsanie, mgf-uitest-web contributors
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: accessibility,magogi,playwright,ui-testing,visual-regression,web
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: axe-playwright-python<1,>=0.1.4
Requires-Dist: playwright<2,>=1.50
Requires-Dist: pytest<10,>=8.0
Provides-Extra: dev
Requires-Dist: coverage[toml]>=7.10; extra == 'dev'
Requires-Dist: import-linter>=2.0; extra == 'dev'
Requires-Dist: mgf-standard<0.2,>=0.1.6; extra == 'dev'
Requires-Dist: mgf-test-supervisor<0.2,>=0.1.3; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-timeout<3,>=2.3; extra == 'dev'
Requires-Dist: ruff<0.16,>=0.4; extra == 'dev'
Provides-Extra: standards
Requires-Dist: mgf-common[standards]<1.0,>=0.47; extra == 'standards'
Description-Content-Type: text/markdown

# 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`](https://codeberg.org/magogi-admin/mgf-fed-web)
and [`mgf-test-web`](https://codeberg.org/magogi-admin/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`](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`](PUBLIC_API.md) (every name, its stability
tier); the boundary is [`SCOPE.md`](SCOPE.md).
