# PUBLIC_API — `mgf-uitest-web`

The contract document (AP-10): every public name, its stability tier (AP-11), and
what it is for. If it is not listed here, it is not public — do not depend on it.

Machine-readable companion: [`PUBLIC_API.json`](PUBLIC_API.json) (generated from
the live `__all__` by [`tools/generate_public_api_json.py`](tools/generate_public_api_json.py)).
Both are pinned to `__all__` by `tests/unit/test_public_api.py`, so this file
cannot silently drift from the code.

## §1. Stability tiers

| Tier | Meaning |
|---|---|
| `experimental` | New. May change shape within a MINOR cycle while it incubates. |
| `stable` | The default consumer expectation — breaking changes need a MAJOR. |
| `deprecated` | Scheduled for removal; raises `DeprecationWarning`. |

**Everything is `experimental` at 0.1.0.** This is the library's first release
(Pre-Alpha): per AP-11 a new name starts `experimental` and earns `stable` after a
MINOR cycle of real consumer use. Nothing has incubated yet, so nothing claims
`stable` — saying otherwise would be a promise we have not earned.

## §2. Importable surface

Synced with `mgf.uitest_web.__all__` (15 names) — the pin test fails if they diverge.

| Name | Kind | Stability | What it is |
|---|---|---|---|
| `Console` | class | `experimental` | The ergonomic wrapper a UI spec drives: `open()` / `text()` / `assert_layout_clean()` / `assert_accessible()` / `assert_healthy()` / `assert_ok()` / `snapshot()`. |
| `ConsoleLaunch` | class | `experimental` | The contract a console provides (from its `console_launch` fixture): the argv to run it as a black-box server, its env, and where to poll for readiness. |
| `Viewport` | class | `experimental` | A named screen size (label + width + height) for the responsive matrix. |
| `LiveServer` | class | `experimental` | A running console under test: its base URL and bound port. |
| `live_server` | context manager | `experimental` | Spawn a console's argv, poll until it serves, yield a `LiveServer`; terminate (then kill) on exit. |
| `free_port` | function | `experimental` | Reserve then release an ephemeral TCP port, returning its number. |
| `UITestWebError` | exception | `experimental` | Base class for every error this library raises deliberately. Subclasses `RuntimeError`. |
| `ServerStartError` | exception | `experimental` | The console died, or never answered, before the deadline. Carries `returncode` and the drained console `output`. |
| `audit_layout` | function | `experimental` | Read the page's real geometry; report content that spills past its box or the viewport. The headline check — deterministic, no image baseline. |
| `LayoutReport` | class | `experimental` | The result of one `audit_layout` call: `.ok` plus `.describe()` for an assertion message. Frozen. |
| `scan_a11y` | function | `experimental` | Run axe-core against the loaded page; return violations at the requested severity. |
| `describe_a11y` | function | `experimental` | Human-readable summary of axe violations, for an assertion message. |
| `watch_health` | function | `experimental` | Attach console/page/network listeners **before** navigation; return a live `HealthWatch`. |
| `HealthWatch` | class | `experimental` | Accumulates browser-console errors, page errors, failed requests and HTTP ≥400 responses. Live — it fills as the page runs. |
| `capture` | function | `experimental` | Write a screenshot of the page to a path (parents created); return the path. |

## §3. Pytest fixtures

Shipped via the `pytest11` entry point, so installing the package makes them
available to a consumer's tests. Not importable names, so not in `__all__` — but
they are just as much a public contract.

| Fixture | Scope | What it gives you |
|---|---|---|
| `console_launch` | function | **You override this.** Return a `ConsoleLaunch` describing how to start your console. The one thing a consumer must provide. |
| `console` | function | The `Console` under test, health listeners already attached — the fixture a spec normally asks for. |
| `console_port` | function | A free ephemeral port for this test's console. |
| `console_server` | function | The console spawned as a black-box subprocess, once it is serving. |
| `ui_page` | function | A fresh browser page at this test's viewport + colour scheme. |
| `ui_context` | function | A fresh browser context (viewport + colour scheme applied). |
| `ui_browser` | session | One pinned bundled Chromium for the whole session. |
| `viewport` | function | The `Viewport` for this test; parametrize indirectly to sweep the matrix. Defaults to `desktop`. |
| `color_scheme` | function | `light` / `dark`; parametrize indirectly. Defaults to `light`. |
| `gallery_dir` | session | Where snapshots land — `<rootdir>/tests/_artifacts/gallery`. |

## §4. What is NOT public

- Anything prefixed `_` (e.g. `mgf.uitest_web.console._slug`, `server._probe`).
- `mgf.uitest_web.plugin`'s module internals — depend on the fixtures, not the module.
- `VIEWPORTS` (the default matrix dict) — read it via the `viewport` fixture.
- The console-specific specs under `tests/e2e/` — they are this repo's proof, not
  an API; a consumer writes its own under its `tests/ui/` (see [SCOPE.md](SCOPE.md)).

## §5. Cross-references

- [README.md](README.md) — what the harness is and how to run it.
- [SCOPE.md](SCOPE.md) — the in/out boundary and the scope gate.
- [CHANGELOG.md](CHANGELOG.md) — breaking changes carry migration guidance (AP-12).
