"""Phase 3 — app screenshot capture (plan-phase3-results-ux.md §4.2, R4/U1). Captures a real screenshot of the deployed app while it is up (before teardown), reusing the Phase-1 Playwright browser already in the harness — no new heavy dep. The PNG is embedded in the summary card (R3) and the dashboard (R5). Secret-safety (R7, the cardinal screenshot guardrail): the screenshot step must NEVER capture a page that displays generated credentials (an install wizard showing the initial admin password, a secrets page, etc.). The DEFAULT capture is the app's **landing page** (a login form shows fields, not the password) — safe for every recipe. A recipe that needs a post-login view opts in via a recipe-meta `SCREENSHOT` hook: a callable `SCREENSHOT(page, ctx) -> None` that drives Playwright to a safe, credential-free view and is responsible for not landing on a secrets page. The harness never auto-fills a wizard. Robustness (R7, cosmetics never block): every entry point is best-effort — any failure (Playwright missing, app slow, navigation error) is swallowed and returns None so the run/verdict is unaffected. """ from __future__ import annotations import contextlib import os from . import browser as harness_browser from . import meta as meta_mod # Default viewport for the captured screenshot — a desktop-ish frame that crops well into the card. VIEWPORT = {"width": 1280, "height": 800} # Hard cap so a wedged app can never hang the run on the screenshot step (R7 / Phase-1 timeouts). NAV_DEADLINE_S = 45 # ---- post-navigation settle (phase-shot fix, 2026-06-11) ---- # SPAs (immich, n8n, cryptpad, the keycloak admin console, lasuite-*, mumble-web, mattermost) fire # `domcontentloaded` on their empty HTML shell and only paint after the JS bundle loads — snapping # immediately produced solid blank frames (byte-stable 4801-2 B) or loading spinners. After nav, # wait for network-idle up to SETTLE_TIMEOUT_MS (apps that never go idle — continuous polling — # simply spend the cap; bounded, never raises), then RENDER_GRACE_MS for the final paint. SETTLE_TIMEOUT_MS = 10_000 RENDER_GRACE_MS = 500 # A 1280x800 PNG below this is near-certainly a solid frame or a bare loading spinner (phase-shot # audit: blank frames were 4801-2 B across three different apps, lone spinners 5.9-8.8 KB; the # smallest real page was 12950 B). One bounded retry with an extra settle, then keep what we get — # an honest late frame beats none, and the retry only ever replaces a tiny frame with a later one. BLANK_SIZE_BYTES = 10_000 BLANK_RETRY_SETTLE_MS = 4_000 # Wait-budget arithmetic (plan-phase-shot §3 P3: step worst case ≤ ~60s): NAV_DEADLINE_S (45s, # spent only while the app isn't serving yet) + SETTLE_TIMEOUT_MS + RENDER_GRACE_MS + # BLANK_RETRY_SETTLE_MS + RENDER_GRACE_MS = 60s of bounded waiting; tested in unit tests. def _settle(page, idle_timeout_ms: int) -> None: """Best-effort bounded settle: network-idle up to the cap, then a short render grace. Never raises (R7) — a timeout just means the page kept polling; we snap what's painted.""" # cosmetic path (R7): a timeout on a never-idle app is expected — the cap IS the wait with contextlib.suppress(Exception): page.wait_for_load_state("networkidle", timeout=idle_timeout_ms) with contextlib.suppress(Exception): page.wait_for_timeout(RENDER_GRACE_MS) def settle(page, idle_timeout_ms: int = SETTLE_TIMEOUT_MS) -> None: """Public settle for recipe SCREENSHOT hooks: after the hook navigates to its safe view, call this so the snap happens post-paint. Same bounded best-effort contract as the default path.""" _settle(page, idle_timeout_ms) def _snap_with_blank_retry(page, out_path: str) -> None: """Screenshot the page; if the PNG is blank/spinner-sized, retry ONCE after a longer settle. The retry is snapped to a temp path and kept only if it is >= the first frame's size — later is usually more painted, but a page can also regress (redirect, error overlay) and a worse frame must never overwrite a better one (adversary finding A1).""" page.screenshot(path=out_path, full_page=False) try: first = os.path.getsize(out_path) except OSError: return if first >= BLANK_SIZE_BYTES: return print( f" screenshot: frame looks blank/loading ({first} B < {BLANK_SIZE_BYTES} B) — " "one retry after a longer settle", flush=True, ) _settle(page, BLANK_RETRY_SETTLE_MS) retry_path = out_path + ".retry" try: page.screenshot(path=retry_path, full_page=False) retry = os.path.getsize(retry_path) if retry >= first: os.replace(retry_path, out_path) print(f" screenshot: retry frame kept ({retry} B >= {first} B)", flush=True) else: os.remove(retry_path) print(f" screenshot: retry frame discarded ({retry} B < {first} B)", flush=True) finally: with contextlib.suppress(OSError): os.remove(retry_path) def screenshot_path(run_artifact_dir: str) -> str: """Canonical on-disk path for a run's app screenshot (pure).""" return os.path.join(run_artifact_dir, "screenshot.png") def _load_screenshot_hook(recipe_meta): """Return the recipe's optional SCREENSHOT hook (a callable) if it declared one, else None. The hook drives Playwright to a safe post-login view; default is the landing page. `recipe_meta` is the loaded RecipeMeta (rcust P1 — the single loader actually delivers SCREENSHOT now; under the old L1 allowlist the key never arrived, spec §8 R2). A plain dict is still accepted for direct/manual callers.""" if recipe_meta is None: return None if isinstance(recipe_meta, dict): hook = recipe_meta.get("SCREENSHOT") else: hook = getattr(recipe_meta, "SCREENSHOT", None) return hook if callable(hook) else None def capture(domain: str, out_path: str, *, recipe_meta: dict | None = None) -> str | None: """Capture a screenshot of the live app at https:/// into out_path. Default: navigate to the landing page and screenshot it (credential-free, safe for any recipe). If the recipe declared a SCREENSHOT hook in recipe_meta, run it instead (post-login / app-specific view, recipe-responsible for avoiding secret pages). Returns out_path on success, else None (best-effort — never raises into the run; cosmetics never block, R7).""" try: from playwright.sync_api import sync_playwright except ImportError: # pragma: no cover — playwright is always present in cc-ci-run print(" screenshot: playwright unavailable — skipping (verdict unaffected)", flush=True) return None os.makedirs(os.path.dirname(out_path) or ".", exist_ok=True) url = f"https://{domain}/" hook = _load_screenshot_hook(recipe_meta) try: with sync_playwright() as p: browser = p.chromium.launch(args=["--no-sandbox"]) try: context = browser.new_context(ignore_https_errors=True, viewport=VIEWPORT) page = context.new_page() if hook is not None: # Recipe-specific safe view (post-login etc.). The hook owns navigation + # the no-secret-page guarantee; it should call page.screenshot itself, but if # it doesn't, we still snap the resulting page below. SCREENSHOT(page, ctx) — # the uniform ctx convention (rcust P3). hook(page, meta_mod.hook_ctx(domain, recipe_meta)) if not os.path.exists(out_path): _snap_with_blank_retry(page, out_path) else: # Default: landing page. Accept any rendered status (200 or an auth redirect to a # login form) — both are credential-free and representative of "the app is up". harness_browser.goto_with_retry( page, url, accept_statuses=(200, 301, 302, 303, 401, 403), deadline_seconds=NAV_DEADLINE_S, wait_until="domcontentloaded", ) # SPA paint race fix (phase-shot): settle before snapping, retry a blank frame. _settle(page, SETTLE_TIMEOUT_MS) _snap_with_blank_retry(page, out_path) finally: browser.close() if os.path.exists(out_path) and os.path.getsize(out_path) > 0: print(f" screenshot: captured {out_path}", flush=True) return out_path print(" screenshot: produced no file — skipping (verdict unaffected)", flush=True) return None except Exception as e: # noqa: BLE001 — screenshot is cosmetic; never fail/hang a run (R7) print(f" screenshot: capture failed (non-fatal, verdict unaffected): {e}", flush=True) return None