Skip to content

Editorial diagram design for Claude Code, Codex, GitHub Copilot, Cursor, Factory Droid, Qoder, and Pi. 45 diagram types. Self-contained HTML + SVG. No shadows. No Mermaid slop.

16.1 KB
Raw Blame
#!/usr/bin/env python3
"""Deterministic tests for the packaged PNG exporter's stalled-load fallback.

Drives ``skills/diagram-design/scripts/export_png.py`` against local fixtures:

- a stalled stylesheet request is cancelled with window.stop(), the renderer
  warns about fallback typography, and capture completes quickly;
- an actual stalled font download is cancelled and font readiness finishes;
- a normal load captures cleanly with no warning;
- fractional scales produce exact viewBox-sized PNGs; invalid scales and
  viewBoxes fail;
- non-timeout errors are not swallowed by the fallback.

Requires Playwright (and its Chromium); skips otherwise, matching the export
procedure's own detection step.
"""

from __future__ import annotations

import contextlib
import importlib.util
import io
import re
import struct
import subprocess
import sys
import tempfile
import threading
import time
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from pathlib import Path

ROOT = Path(__file__).resolve().parent.parent
EXPORT_PNG = ROOT / "skills/diagram-design/scripts/export_png.py"

# Fast-but-deterministic substitutes for the renderer's production waits.
FAST_IDLE_TIMEOUT_MS = 1_500
FAST_SETTLE_MS = 150
STALL_HOLD_SECONDS = 30  # must outlast the test's networkidle timeout
WARNING_ANCHOR = "fallback typography"
# The full fallback (fast timeout + settle + capture) must stay far below the
# production path's 15s networkidle + 4s settle budget.
FALLBACK_BUDGET_SECONDS = 15.0


def load_exporter():
    source = EXPORT_PNG.read_text(encoding="utf-8")
    for anchor in (
        "except PlaywrightTimeoutError:",
        'page.evaluate("window.stop()")',
        "NETWORK_IDLE_TIMEOUT_MS = 15_000",
        "?motion=static",
        "document.fonts.ready",
        "[data-motion-root]",
    ):
        if anchor not in source:
            raise AssertionError(f"packaged exporter is missing required anchor {anchor!r}")
    if "except Exception" in source or "except:" in source:
        raise AssertionError(
            "packaged exporter must not swallow non-timeout errors with a "
            "broad or bare except"
        )
    spec = importlib.util.spec_from_file_location("diagram_export_png", EXPORT_PNG)
    if spec is None or spec.loader is None:
        raise AssertionError(f"could not import {EXPORT_PNG}")
    module = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(module)
    return module


class _StallHandler(BaseHTTPRequestHandler):
    """Serves nothing: holds /stall* requests open so the load never settles."""

    def do_GET(self) -> None:  # noqa: N802 - stdlib naming
        if self.path.startswith("/stall"):
            time.sleep(STALL_HOLD_SECONDS)
            self.send_error(500)
            return
        self.send_error(404)

    def log_message(self, *args: object) -> None:
        pass


def start_stall_server(handler: type[BaseHTTPRequestHandler] = _StallHandler) -> ThreadingHTTPServer:
    server = ThreadingHTTPServer(("127.0.0.1", 0), handler)
    server.daemon_threads = True
    threading.Thread(target=server.serve_forever, daemon=True).start()
    return server


def run_export(exporter, src: Path, out: Path, **kwargs: int) -> str:
    """Run the packaged renderer and return captured stderr."""
    stderr = io.StringIO()
    with contextlib.redirect_stderr(stderr):
        exporter.rasterize(src, out, 2, **kwargs)
    return stderr.getvalue()


def run_export_with_timeout(src: Path, out: Path) -> str:
    """Run the packaged renderer with fast waits in a killable subprocess."""
    runner = """
import importlib.util
import pathlib
import sys

spec = importlib.util.spec_from_file_location("diagram_export_png", sys.argv[1])
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
module.rasterize(
    pathlib.Path(sys.argv[2]),
    pathlib.Path(sys.argv[3]),
    2,
    network_idle_timeout_ms=int(sys.argv[4]),
    fallback_settle_ms=int(sys.argv[5]),
)
"""
    result = subprocess.run(
        [
            sys.executable,
            "-c",
            runner,
            str(EXPORT_PNG),
            str(src),
            str(out),
            str(FAST_IDLE_TIMEOUT_MS),
            str(FAST_SETTLE_MS),
        ],
        capture_output=True,
        text=True,
        check=True,
        timeout=FALLBACK_BUDGET_SECONDS,
    )
    return result.stderr


def require_png(out: Path, name: str) -> None:
    if not out.exists() or out.stat().st_size == 0:
        raise AssertionError(f"{name}: expected a non-empty screenshot at {out}")


def run_cli_without_scale(src: Path, out: Path) -> str:
    run = subprocess.run(
        [sys.executable, str(EXPORT_PNG), str(src), str(out)],
        capture_output=True,
        text=True,
        timeout=FALLBACK_BUDGET_SECONDS,
    )
    if run.returncode != 0:
        raise AssertionError(f"normal-load: packaged renderer failed\n{run.stderr}")
    return run.stderr


def png_dimensions(out: Path) -> tuple[int, int]:
    png = out.read_bytes()
    if not png.startswith(b"\x89PNG\r\n\x1a\n") or len(png) < 24:
        raise AssertionError("normal-load: renderer did not produce a valid PNG header")
    return struct.unpack(">II", png[16:24])


def require_stalled_fallback(tmp: Path) -> None:
    server = start_stall_server()
    try:
        port = server.server_address[1]
        src = tmp / "stall-fixture.html"
        src.write_text(
            "<!doctype html>\n<html>\n<head>\n<meta charset='utf-8'>\n"
            f"<link rel='stylesheet' href='http://127.0.0.1:{port}/stall.css'>\n"
            "</head>\n<body>\n"
            "<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 400 240' "
            "width='400' height='240' role='img' aria-labelledby='stall-title'>\n"
            "<title id='stall-title'>Stall fixture diagram</title>\n"
            "<rect width='400' height='240' fill='#ffffff'/>\n"
            "<text x='200' y='124' text-anchor='middle' font-family='sans-serif' "
            "font-size='24' fill='#111111'>stall fixture</text>\n"
            "</svg>\n</body>\n</html>\n",
            encoding="utf-8",
        )
        out = tmp / "stall-fixture.png"

        started = time.monotonic()
        stderr = run_export_with_timeout(src, out)
        elapsed = time.monotonic() - started

        require_png(out, "stalled-fallback")
        if WARNING_ANCHOR not in stderr:
            raise AssertionError(
                f"stalled-fallback: expected a {WARNING_ANCHOR!r} warning on stderr\n{stderr}"
            )
        if elapsed > FALLBACK_BUDGET_SECONDS:
            raise AssertionError(
                f"stalled-fallback: capture took {elapsed:.1f}s, over the "
                f"{FALLBACK_BUDGET_SECONDS:.0f}s budget - window.stop() did not "
                "release the stalled load"
            )
        print(
            f"OK: stalled stylesheet cancels via window.stop(), warns, "
            f"and captures in {elapsed:.1f}s"
        )
    finally:
        server.shutdown()
        server.server_close()


def require_stalled_font_fallback(tmp: Path) -> None:
    font_requested = threading.Event()

    class FontStallHandler(_StallHandler):
        def do_GET(self) -> None:  # noqa: N802 - stdlib naming
            if self.path == "/stall.woff2":
                font_requested.set()
            super().do_GET()

    server = start_stall_server(FontStallHandler)
    try:
        port = server.server_address[1]
        src = tmp / "stalled-font.html"
        src.write_text(
            "<!doctype html><meta charset='utf-8'><style>"
            "@font-face{font-family:OwnedStalledFont;src:url("
            f"http://127.0.0.1:{port}/stall.woff2) format('woff2')}}"
            "</style><svg xmlns='http://www.w3.org/2000/svg' "
            "viewBox='0 0 400 240' width='400' height='240'>"
            "<text x='20' y='120' font-family='OwnedStalledFont,sans-serif'>"
            "stalled font fixture</text></svg>",
            encoding="utf-8",
        )
        out = tmp / "stalled-font.png"
        started = time.monotonic()
        stderr = run_export_with_timeout(src, out)
        elapsed = time.monotonic() - started
        if not font_requested.is_set():
            raise AssertionError("stalled-font: fixture never started its font download")
        require_png(out, "stalled-font")
        if not out.read_bytes().startswith(b"\x89PNG\r\n\x1a\n"):
            raise AssertionError("stalled-font: output is not a PNG")
        if WARNING_ANCHOR not in stderr:
            raise AssertionError(f"stalled-font: fallback warning did not fire\n{stderr}")
        if elapsed > FALLBACK_BUDGET_SECONDS:
            raise AssertionError(
                f"stalled-font: capture took {elapsed:.1f}s, over the "
                f"{FALLBACK_BUDGET_SECONDS:.0f}s budget after font cancellation"
            )
        print(f"OK: actual stalled font cancels, fonts.ready finishes, and PNG captures in {elapsed:.1f}s")
    finally:
        server.shutdown()
        server.server_close()


def require_normal_load(exporter, tmp: Path) -> None:
    src = tmp / "normal-fixture.html"
    src.write_text(
        "<!doctype html>\n<html>\n<head>\n<meta charset='utf-8'>\n</head>\n<body>\n"
        "<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 400 240' "
        "width='400' height='240' role='img' aria-labelledby='normal-title'>\n"
        "<title id='normal-title'>Normal fixture diagram</title>\n"
        "<rect width='400' height='240' fill='#ffffff'/>\n"
        "<text x='200' y='124' text-anchor='middle' font-family='sans-serif' "
        "font-size='24' fill='#111111'>normal fixture</text>\n"
        "</svg>\n</body>\n</html>\n",
        encoding="utf-8",
    )
    out = tmp / "normal-fixture.png"

    stderr = run_cli_without_scale(src, out)

    require_png(out, "normal-load")
    if png_dimensions(out) != (800, 480):
        raise AssertionError(
            "normal-load: omitted CLI scale did not produce the default 2x dimensions"
        )
    if WARNING_ANCHOR in stderr:
        raise AssertionError(f"normal-load: fallback warning fired unexpectedly\n{stderr}")
    print("OK: normal load captures with no fallback warning")


def require_encoded_paths(exporter, tmp: Path) -> None:
    # Both characters are legal filename content, not a URL fragment/escape.
    original = tmp / "normal-fixture.html"
    for filename in ("diagram #1.html", "diagram %25.html", "diagram ?draft.html"):
        # Question marks are not valid Windows filename characters.
        if "?" in filename and sys.platform == "win32":
            continue
        source = tmp / filename
        source.write_text(original.read_text(encoding="utf-8"), encoding="utf-8")
        output = tmp / (filename + ".png")
        stderr = run_export(exporter, source, output)
        require_png(output, filename)
        if stderr:
            raise AssertionError(f"encoded-path capture emitted a warning: {stderr}")
    print("OK: legal filename characters are encoded in the file URL")


def run_cli_with_scale(src: Path, out: Path, scale: str) -> subprocess.CompletedProcess[str]:
    return subprocess.run(
        [sys.executable, str(EXPORT_PNG), str(src), str(out), scale],
        capture_output=True,
        text=True,
        timeout=FALLBACK_BUDGET_SECONDS,
    )


def require_fractional_scales(exporter, tmp: Path) -> None:
    source = tmp / "normal-fixture.html"  # 400 by 240 viewBox units
    # Page layout must not change dimensions promised by the viewBox contract.
    source.write_text(source.read_text(encoding="utf-8").replace("</head>", "<style>svg { width:1200px; min-width:1200px; height:auto; }</style></head>"), encoding="utf-8")
    for scale, dimensions in (("1", (400, 240)), ("1.25", (500, 300)),
                               ("1.5", (600, 360)), ("3", (1200, 720)), ("4", (1600, 960))):
        output = tmp / f"scale-{scale}.png"
        run = run_cli_with_scale(source, output, scale)
        if run.returncode != 0:
            raise AssertionError(f"scale {scale}: packaged renderer failed\n{run.stderr}")
        require_png(output, scale)
        actual = struct.unpack(">II", output.read_bytes()[16:24])
        if actual != dimensions:
            raise AssertionError(f"scale {scale}: expected {dimensions}, got {actual}")
    for viewbox in ("0 0 0 240", "0 0 400 0", "not-a-viewbox"):
        broken = tmp / "invalid-viewbox.html"
        broken.write_text(source.read_text(encoding="utf-8").replace("viewBox='0 0 400 240'", f"viewBox='{viewbox}'"), encoding="utf-8")
        output = tmp / "invalid-viewbox.png"
        try:
            run_export(exporter, broken, output)
        except Exception as exc:
            if "viewBox" not in str(exc) or output.exists():
                raise AssertionError(f"invalid viewBox failed incorrectly: {exc}")
        else:
            raise AssertionError(f"invalid viewBox {viewbox!r} was accepted")
    for scale in ("0.5", "4.1", "nan", "inf", "not-a-number"):
        output = tmp / "invalid-scale.png"
        run = run_cli_with_scale(source, output, scale)
        if run.returncode == 0:
            raise AssertionError(f"invalid scale {scale} was accepted")
        if "scale" not in run.stderr:
            raise AssertionError(f"invalid scale {scale} failed without a scale diagnostic\n{run.stderr}")
        if output.exists():
            raise AssertionError(f"invalid scale {scale} wrote a PNG")
    print("OK: fractional scales produce exact dimensions; invalid scales fail")


def require_other_errors_propagate(exporter, tmp: Path) -> None:
    missing = tmp / "does-not-exist.html"
    out = tmp / "never.png"
    try:
        run_export(exporter, missing, out)
    except Exception as exc:
        if type(exc).__name__ == "TimeoutError":
            raise AssertionError(
                "missing-source: goto failure surfaced as a TimeoutError; "
                "the fallback caught the wrong error class"
            )
        print(f"OK: non-timeout failure propagates ({type(exc).__name__})")
        return
    raise AssertionError("missing-source: expected goto on a missing file to raise")



def require_static_motion_frame(exporter, tmp: Path) -> None:
    # Exercise the exact shipped controller, avoiding external font requests.
    source = (ROOT / "skills/diagram-design/assets/example-policy-trace-animated.html").read_text(encoding="utf-8")
    source = re.sub(r"<link\b[^>]*>", "", source, flags=re.I)
    src = tmp / "motion-fixture.html"
    src.write_text(source, encoding="utf-8")
    first, second = tmp / "motion-first.png", tmp / "motion-second.png"
    run_export(exporter, src, first)
    run_export(exporter, src, second)
    require_png(first, "static-motion")
    if first.read_bytes() != second.read_bytes():
        raise AssertionError("motion captures from the same static source are not identical")

    # A broken controller must fail rather than silently capture hidden steps.
    broken = re.sub(r"<script\b[^>]*>.*?</script>", "", source, flags=re.I | re.S)
    broken = broken.replace('data-frame="static" data-static-frame=', 'data-frame="start" data-static-frame=', 1)
    src.write_text(broken, encoding="utf-8")
    never = tmp / "incomplete.png"
    try:
        run_export(exporter, src, never)
    except RuntimeError as exc:
        if "static" not in str(exc) or never.exists():
            raise AssertionError(f"incomplete motion frame failed incorrectly: {exc}")
    else:
        raise AssertionError("incomplete motion frame was exported without an error")
    print("OK: motion exports show the complete static frame, repeat identically, and reject incomplete roots")

def main() -> int:
    try:
        import playwright  # noqa: F401
    except ImportError:
        print("SKIP: playwright is not installed; packaged export tests skipped")
        return 0

    exporter = load_exporter()
    with tempfile.TemporaryDirectory(prefix="diagram-export-wait-") as raw_tmp:
        tmp = Path(raw_tmp)
        require_stalled_fallback(tmp)
        require_stalled_font_fallback(tmp)
        require_normal_load(exporter, tmp)
        require_encoded_paths(exporter, tmp)
        require_fractional_scales(exporter, tmp)
        require_other_errors_propagate(exporter, tmp)
        require_static_motion_frame(exporter, tmp)
    print("All export-wait cases passed.")
    return 0


if __name__ == "__main__":
    sys.exit(main())