zf-browser-e2e-contract

Files (1)

• SKILL.md

SKILL.md (first lines)

# ZaoFu Browser E2E Contract

## Overview

Use this skill when a ZaoFu task includes browser, Playwright, or E2E
verification. This skill is deliberately narrow: it owns **Docker/Playwright
command shape and the clean-checkout environment checklist** only. Hard
correctness still belongs in `task_map` validation, workflow runtime, and
deterministic gates.

Division of labor (avoid dual-source drift):

- **This skill**: Docker/Playwright command shape, `--user` / host-networking /
  bounded-install environment rules, clean-checkout + pin-commit setup.
- **`verify-review` skill** (canonical: `yoke/verify-review/SKILL.md`): the
  runner-vs-product failure **taxonomy** and the **structured report contract**
  (coverage matrix, gap findings, evidence refs). When this skill mentions
  classification or report fields, `verify-review` is the source of truth —
  cite it, do not fork a second copy of the taxonomy here.

## Core Rules

- Preserve an exact browser command or security boundary supplied by the
  canonical Task, PRD, or owner contract byte-for-byte. That run-scoped
  contract takes precedence over this skill's generic command pattern.
- Treat the host-network / `mcp/playwright:latest` pattern below as a fallback
  only when the canonical contract does not provide an exact command. Never
  replace a contract-pinned image, bridge network, read-only mount, or `tmpfs`
  boundary with the fallback image, host network, writable mount, or install
  sequence.
- Respect `zf.yaml` and `project.state_dir`; do not hard-code `.zf`.
- Use Docker with `mcp/playwright:latest` for browser E2E unless the operator
  explicitly asks for host browsers and no exact run-scoped command is pinned.
- Start local API/UI services on `0.0.0.0` when a container must reach them.
- Declare the exact owner-facing service URL and origin in the Task/real-E2E
  matrix. A pass on `http://localhost` does not prove behavior on
  `http://<LAN-IP>` or another delivery origin.
- Use host networking for local service smoke tests only when the canonical
  contract does not pin a different network boundary.
- Run the container with the host UID/GID so mounted workdirs remain writable.
- Bound browser install commands with `timeout`; never leave
  `playwright install chromium` unbounded.
- Do not wrap an existing Docker Playwright command in another Docker command.
- The `mcp/playwright:latest` image has an MCP CLI entrypoint. A browser
  command MUST either use `--entrypoint bash -lc` (as in the fallback below)
  or explicitly invoke the image's documented runner; never append `node`,
  `npm`, or `playwright` directly after the image name. That form is parsed as
  MCP options (for example `unknown option --test`) and is a runner failure,
  not product evidence.
- Do not downgrade a runner/setup failure into product rework.

## Command Pattern

When no exact Task/PRD/owner command is supplied, use this fallback shape for
browser gates:

```bash
docker run --rm --network host \
  --user "$(id -u):$(id -g)" \
  --entrypoint bash \
  -v "$PWD:/work" -w /work \
  -e PLAYWRIGHT_BROWSERS_PATH=0 \
  mcp/playwright:latest \
  -lc 'set -euo pipefail; timeout 180s ./packages/web-tui/node_modules/.bin/playwright install chromium; ./packages/web-tui/node_modules/.bin/playwright test --config packages/web-tui/playwright.config.ts'
```

Adapt paths to the current `task_map`; keep the runner flags intact. When an
exact command is supplied, preserve it instead of adapting this fallback.

> The `mcp/playwright:latest` image name, the `INSTALLATION_COMPLETE` marker
> referenced below, and this exact command shape are **skill-owned convention
> (no kernel validator)** — the kernel does not parse or enforce them; they are
> operator/agent discipline.

## Task Map Checklist

- Keep verification commands machine-readable. If `verification` is a list, each
  item must be a standalone command; never stringify a Python list into a
  contract field.
- Planning readiness is not execution success. Before implementation, missing
  screenshots, traces, or browser receipts are expected future outputs, not an
  environment blocker. Keep the plan dispatchable when it names a runnable
  Docker Playwright command and assigns the runner/config/test/evidence paths to
  a producer task. Mark the plan blocked only when the declared runner itself is
  unavailable or forbidden and no sanctioned equivalent exists.
- A browser acceptance criterion must be bound before dispatch to an `e2e`
  command plus writable runner/config/test/evidence paths. Do not leave viewport,
  pointer, network, storage, refresh, or screenshot acceptance attached only to
  `npm test`, a build command, or a future Verify interpretation.
- Record `bind_host`, `service_url`, and `browser_origin` in the browser row or
  its evidence contract. Verify the owner-facing origin in addition to any
  runner-internal localhost origin; preserve both receipts when both are part
  of the delivery path.
- When the product depends on WebCrypto or another secure-context API, run a
  capability probe at the exact owner-facing origin (for example
  `window.isSecureContext` and the required `crypto.subtle` operation). An
  unsupported insecure origin is a product failure unless the product contract
  declares and the test proves a supported fallback. Do not replace this with
  a localhost-only assertion, because browsers treat localhost and LAN/IP HTTP
  origins differently.
- Include static/package checks separately from browser E2E checks.
- Mark browser checks with the canonical verification tier **`e2e`**. The kernel
  tier set is `static` / `runtime` / `e2e` / `manual_evidence`
  (`VALID_VERIFICATION_TIERS`, `src/zf/core/task/schema.py`). The underscore
  aliases `live_smoke`, `live_smoke_optional`, and `smoke` normalize to `e2e`
  at the runtime boundary (`src/zf/runtime/task_contract_normalize.py`), so they
  are safe but non-canonical.
  - **Do not** write `browser` or the hyphenated `live-smoke` as a tier: neither
    is a valid tier and neither has an alias, so an unknown token is **silently
    dropped** by `canonical_verification_tiers`, leaving the browser gate with
    no tier. Emit `e2e`.
- Reject or repair host-only commands such as bare `npx playwright test` for
  browser E2E.
- Reject or repair Docker Playwright commands that miss
  `--user "$(id -u):$(id -g)"`.
- Reject or repair unbounded browser install commands.
- When a mixed verification list includes static npm gates and a Docker browser
  gate, show the Docker command pattern for the browser gate only; do not create
  Docker-in-Docker examples.

From uisee-ai/zaofu, Apache-2.0.

More from uisee-ai/zaofu