buckets/e2e/README.md

E2E smoke tests (Playwright)

End-to-end smoke tests that drive a real browser against the live dev stack. These verify the cross-stack behavior the component tests mock away: the real session cookie, the Vite /api → php:80 proxy, and the actual API contract.

Runs in a container, not the host

Playwright needs real browser binaries. Rather than installing them on the host (the NixOS host can't launch Chromium — missing shared libraries), the suite runs in the playwright compose service (mcr.microsoft.com/playwright, browsers + libs preinstalled). It's gated behind a compose profile so it never starts with a plain dev-up.

Running

1. Bring the stack up: dev-up (needs frontend, php, database services).
2. Run the suite via the e2e profile (installs deps + runs the tests in the container; the image already has the browsers):

   podman-compose -f compose.yaml -f compose.override.yaml --profile e2e run --rm playwright
   

   The runner targets the SPA by compose service name (http://frontend:5173, set via E2E_BASE_URL) — container-to-container, no host browsers involved.

Version coupling

@playwright/test in package.json is pinned to an exact version that must match the mcr.microsoft.com/playwright:vX.Y.Z-jammy image tag in compose.override.yaml. A mismatch makes Playwright refuse to launch (the runner and the image's bundled browsers must agree). Bump both together.