US09-03: Write the Architecture Overview

tests/e2e/test_docs_ui.py

@@ -12,6 +12,8 @@ The offline contract — reachability, dead links, pinned checksums — is
 
 from __future__ import annotations
 
+from pathlib import Path
+
 import pytest
 
 from tests.e2e._pipeline_harness import Server, seed_library
@@ -90,6 +92,34 @@ def test_a_mermaid_block_becomes_a_diagram_under_the_unchanged_script_policy(pag
     assert "unsafe-eval" not in policy
 
 
+def test_every_diagram_in_the_architecture_overview_draws(page, server, quiet):
+    """Five diagrams, three of them state machines (US09-03). A mermaid block with a
+    syntax error renders an error node instead of throwing, so a page that merely
+    loaded proves nothing — count the drawings and read the source for the states."""
+    source = (Path(__file__).resolve().parents[2] / "docs" / "architecture.md").read_text()
+    expected = source.count("```mermaid")
+    assert expected >= 5, "the overview lost its diagrams"
+
+    page.goto(f"{server.base}/app/#/docs?page=architecture")
+    page.get_by_test_id("diagram").first.wait_for()
+    page.wait_for_function(
+        "count => document.querySelectorAll('[data-testid=\"diagram\"] svg').length === count",
+        arg=expected,
+    )
+
+    drawn = page.locator('[data-testid="diagram"] svg')
+    assert drawn.count() == expected
+    for index in range(expected):
+        diagram = drawn.nth(index)
+        # Labels may be <text> or HTML inside a <foreignObject> depending on the
+        # diagram type, so ask for the rendered text rather than a specific element.
+        labels = diagram.evaluate("node => node.textContent.trim().length")
+        assert labels > 0, f"diagram {index} drew no labels"
+        assert diagram.locator(".error-icon, .error-text").count() == 0, f"diagram {index} errored"
+    assert page.locator("pre code.language-mermaid").count() == 0
+    assert quiet == []
+
+
 def test_an_unknown_page_says_so_without_naming_a_path(page, server, quiet):
     page.goto(f"{server.base}/app/#/docs?page=no-such-manual")
     message = page.get_by_test_id("doc-not-found")