Metadata-Version: 2.4
Name: mgf-uitest-web
Version: 0.1.1
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 console errors, zero failed requests.
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, prove-first. Built and proven locally against two consoles
(`mgf-fed-web`, `mgf-test-web`) before it is registered in the federation or wired
as a blocking CI gate — that promotion is a deliberate, founder-fired step. See the
decision package under the MGF Court workspace.

## §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. 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 a per-rule audit. The audit is
[`docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`](docs/inprogress/MGF_STANDARDS_CONFORMANCE.md)
— all **265** MUSTs of the corpus accounted for: 118 ✅ · 143 N/A · 3 declined-with-rationale
· **1 in flight** (AP-02 per-name usage examples). The open item is named there with its
closing action — a level claim is only worth what its ledger shows.

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