test(e2e): first Playwright slice — real browser asserts no Pyodide errors

The bug surfaced in commit 0923863 (NameError: name 'store' is not
defined) only manifested when the bundle actually ran in Pyodide in a
real browser. Compile-time tests passed; the failure was invisible
to the existing suite. This slice fixes that.

New: tests/test_examples_e2e.py
- One @pytest.mark.e2e test that boots example 03 on a real uvicorn
  server, drives a headless Chromium via Playwright, waits for the
  violetear-cloak element to be removed (hydration-complete signal),
  and asserts no console.error / pageerror fired during the load.
- A cheap sanity check that the SSR-rendered meters value is present
  after hydration.

New: tests/conftest.py
- Session-scoped autouse fixture that pre-warms the Pyodide local
  cache (~14MB download once if missing — no-op after).
- example_server fixture that boots an example via uvicorn-in-thread
  on a free port and returns the base URL.
- browser_type_launch_args override that points executable_path at
  the full chromium binary on disk instead of the headless_shell
  variant pytest-playwright defaults to — works around a chronic
  version-mismatch where `playwright install chromium` doesn't always
  fetch the matching headless_shell. Opt out via env var if needed.

New: pytest config
- e2e marker registered in pyproject.toml.
- `addopts = "-m 'not e2e'"` keeps the default fast gate skipping them.
- Run e2e with `make e2e` or `uv run pytest -m e2e -v`.

CI:
- New `e2e` job in tests.yaml that runs after the fast `test` job.
- Caches ~/.cache/ms-playwright and ~/.cache/violetear so the
  per-run cost is one-time per cache miss.
- Uses `playwright install --with-deps chromium` (sudo OK on the
  ubuntu runner; not on local dev — that's why we override
  executable_path locally).

43 passed (fast gate, 1 deselected) + 1 e2e passed locally.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: apiad

.github/workflows/tests.yaml

@@ -30,3 +30,40 @@ jobs:
 
       - name: Run tests with coverage
         run: uv run pytest --cov=violetear --cov-report=xml --cov-report=term
+
+  e2e:
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      - name: Install dependencies
+        run: uv sync --all-extras --all-groups --no-editable
+
+      - name: Cache Playwright browsers
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('uv.lock') }}
+
+      - name: Cache violetear Pyodide assets
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/violetear
+          key: violetear-pyodide-0.29.0
+
+      - name: Install Playwright Chromium
+        run: uv run playwright install --with-deps chromium
+
+      - name: Run e2e tests
+        run: uv run pytest -m e2e -v

makefile

@@ -20,14 +20,21 @@ format-check:
 type-check:
 	mypy
 
-.PHONY: test-unit test-all
+.PHONY: test-unit test-all e2e
 
 test-unit: format-check
 	uv run pytest tests --cov=violetear
 
 test-all: format-check
 	uv run pytest --cov=violetear
 
+# End-to-end browser tests via Playwright. Slow (~5s/test for Pyodide load),
+# so kept out of the default `make` gate. Run when you change anything that
+# affects the bundle, hydration, reactive bindings, or Pyodide hosting.
+e2e:
+	uv run playwright install chromium
+	uv run pytest -m e2e -v
+
 .PHONY: docker-build
 docker-build:
 	docker build -t violetear:latest -f dockerfile .

pyproject.toml

@@ -30,7 +30,15 @@ dev = [
     "ruff>=0.13.0",
     "pytest>=9.0.2",
     "pytest-cov>=7.0.0",
+    "pytest-playwright>=0.5",
 ]
 
 [tool.setuptools.package-data]
 violetear = ["*.png"]
+
+[tool.pytest.ini_options]
+markers = [
+    "e2e: end-to-end browser tests via Playwright (slow; run separately from the fast unit gate)",
+]
+# Default pytest run excludes e2e — invoke `pytest -m e2e` or `make e2e` to run them.
+addopts = "-m 'not e2e'"

tests/conftest.py

@@ -0,0 +1,147 @@
+"""
+Shared test fixtures for violetear.
+
+Most of the suite runs against `TestClient` (sync, in-process). The e2e tests
+(marked `@pytest.mark.e2e`) need a real port-bound server because Playwright
+drives a real Chromium that fetches HTTP/WS resources from a URL.
+"""
+
+import importlib.util
+import os
+import socket
+import sys
+import threading
+import time
+from pathlib import Path
+from typing import Callable
+
+import httpx
+import pytest
+import uvicorn
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+EXAMPLES_DIR = REPO_ROOT / "examples"
+
+
+# ---- Playwright browser-launch override ------------------------------------
+# pytest-playwright defaults to the `chromium_headless_shell-<rev>` binary for
+# headless mode. On systems where that variant isn't installed (e.g. the full
+# `chromium-<rev>` was installed but the headless-shell wasn't), we fall back
+# to launching the full chromium binary in headless mode. This avoids the
+# common "Executable doesn't exist at .../chrome-headless-shell" error when
+# CI or dev has only one of the two variants on disk.
+
+
+def _find_full_chromium() -> str | None:
+    """Locate a usable full chromium binary under PLAYWRIGHT_BROWSERS_PATH."""
+    root = Path(
+        os.environ.get("PLAYWRIGHT_BROWSERS_PATH")
+        or (Path.home() / ".cache" / "ms-playwright")
+    )
+    if not root.exists():
+        return None
+    # Pick the newest chromium-<rev>/chrome-linux64/chrome on disk.
+    candidates = sorted(root.glob("chromium-*/chrome-linux64/chrome"), reverse=True)
+    return str(candidates[0]) if candidates else None
+
+
+@pytest.fixture(scope="session")
+def browser_type_launch_args(browser_type_launch_args):
+    """Override pytest-playwright's launch args to use the full chromium
+    binary instead of the headless_shell variant.
+
+    pytest-playwright defaults to a `chromium_headless_shell-<rev>` binary
+    that often isn't installed (the standard `playwright install chromium`
+    sometimes only fetches the full chromium). Pointing executable_path at
+    the full chromium with headless launch produces equivalent behavior
+    without the version-mismatch error.
+
+    Set VIOLETEAR_PLAYWRIGHT_USE_HEADLESS_SHELL=1 to opt out of the override.
+    """
+    args = dict(browser_type_launch_args)
+    if os.environ.get("VIOLETEAR_PLAYWRIGHT_USE_HEADLESS_SHELL"):
+        return args
+    chromium = _find_full_chromium()
+    if chromium:
+        args["executable_path"] = chromium
+    return args
+
+
+def _free_port() -> int:
+    """Bind to port 0, get the OS-assigned port, release. Standard race-tolerant
+    pattern — there's a tiny window between release and uvicorn binding but
+    uvicorn errors loudly if it can't bind."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+def _load_example(filename: str):
+    """Import an example module by filename, registering in sys.modules first
+    so violetear's bundle generator can call inspect.getsource on its state
+    classes (see issues/7.5)."""
+    name = filename.removesuffix(".py").replace(".", "_")
+    spec = importlib.util.spec_from_file_location(name, EXAMPLES_DIR / filename)
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+@pytest.fixture(scope="session", autouse=True)
+def _pyodide_cache_prewarm():
+    """Pre-warm the Pyodide local cache once per test session.
+
+    Without this, the first e2e test that loads a real page triggers a ~14MB
+    download from jsDelivr — fine in dev but flaky in CI and slow on a cold
+    runner. Calling _ensure_pyodide_cached() here populates the cache early
+    (or no-ops if it already exists from a prior run / a CI cache restore).
+
+    Marked autouse so any e2e test inherits a warm cache without opting in.
+    """
+    from violetear.app import _ensure_pyodide_cached
+
+    _ensure_pyodide_cached()
+
+
+@pytest.fixture
+def example_server() -> Callable[[str], str]:
+    """Boot one of the canonical examples on a free port via uvicorn-in-thread,
+    yield a factory that returns the base URL. The server tears down at end of
+    test."""
+    servers: list[tuple[uvicorn.Server, threading.Thread]] = []
+
+    def _start(filename: str) -> str:
+        port = _free_port()
+        module = _load_example(filename)
+
+        config = uvicorn.Config(
+            module.app.api,
+            host="127.0.0.1",
+            port=port,
+            log_level="warning",
+            lifespan="on",
+        )
+        server = uvicorn.Server(config)
+        thread = threading.Thread(target=server.run, daemon=True)
+        thread.start()
+        servers.append((server, thread))
+
+        # Wait for the server to actually accept connections.
+        base = f"http://127.0.0.1:{port}"
+        deadline = time.monotonic() + 10.0
+        while time.monotonic() < deadline:
+            try:
+                httpx.get(base + "/", timeout=0.4)
+                return base
+            except httpx.HTTPError:
+                time.sleep(0.05)
+        raise RuntimeError(f"Example server {filename} did not start within 10s")
+
+    yield _start
+
+    # Teardown — request graceful exit, give it a moment, then drop the threads.
+    for server, _thread in servers:
+        server.should_exit = True
+    for _server, thread in servers:
+        thread.join(timeout=3.0)

tests/test_examples_e2e.py

@@ -0,0 +1,72 @@
+"""
+End-to-end tests — drive a real headless Chromium against a real uvicorn
+server. Each test boots one canonical example, navigates to it, and asserts on
+the browser-observable state after Pyodide finishes hydrating.
+
+Marked `e2e` so the fast unit gate skips them. Run with:
+
+    uv run pytest -m e2e
+    # or: make e2e
+
+These tests catch the class of bug that compile-time bundle checks miss —
+e.g. a NameError when the bundle exec actually runs in Pyodide. See
+issues/7.6 for the motivating incident.
+"""
+
+import pytest
+
+
+# Maximum wait for Pyodide load + bundle eval + hydration. ~5s typical on a
+# warm cache, more on first run. Generous to absorb CI variance.
+HYDRATION_TIMEOUT_MS = 45_000
+
+
+def _collect_browser_errors(page):
+    """Attach listeners that record any console.error / pageerror events.
+
+    Returns a list that the test reads after navigation. We capture both:
+    - `console.error` (where Pyodide's PythonError lands after exec failure),
+    - `pageerror` (uncaught JS / promise rejections).
+    """
+    errors: list[str] = []
+    page.on(
+        "console",
+        lambda msg: (
+            errors.append(f"[console.{msg.type}] {msg.text}")
+            if msg.type == "error"
+            else None
+        ),
+    )
+    page.on("pageerror", lambda exc: errors.append(f"[pageerror] {exc}"))
+    return errors
+
+
+@pytest.mark.e2e
+def test_03_interactive_loads_with_no_pyodide_errors(example_server, page):
+    """The smoke test: example 03 boots, Pyodide loads, the bundle executes,
+    hydration completes — and no console.error / pageerror fires along the way.
+
+    This is the test that would have caught the `NameError: name 'store' is
+    not defined` bug surfaced in the browser (issues/7.6) before it shipped.
+    """
+    base = example_server("03_interactive.py")
+    errors = _collect_browser_errors(page)
+
+    page.goto(base + "/")
+
+    # Hydration is complete when the bootstrap script removes the "cloak"
+    # <style> element (see app.py:_inject_client_side). If the bundle exec
+    # threw, this signal never arrives and we time out.
+    page.wait_for_function(
+        "() => document.getElementById('violetear-cloak') === null",
+        timeout=HYDRATION_TIMEOUT_MS,
+    )
+
+    # If anything blew up during init (top-level `await restore()` etc.),
+    # PyodideError → console.error before the cloak fires. We assert silence.
+    assert errors == [], "Browser errors after hydration:\n  " + "\n  ".join(errors)
+
+    # Cheap sanity check that the SSR-rendered values are present after
+    # hydration. The meters input was server-rendered with value="1.0".
+    meters_value = page.input_value('input[data-bind-value="UiState.meters"]')
+    assert meters_value == "1.0"