"""Tests for tools/google_viewer_check.py: Google's viewer reads a bundle without error, with one graph node per concept page (PLAN.md criterion 5, brief SC5; wave 2 order 7). The tool runs the generator of an upstream checkout (src/reference_agent/viewer/generator.py) with `python3 -I -B` from another folder, on an unchanged copy of the bundle, and passes when the run exits 0, prints no traceback, draws as many concept nodes as the auditor counts concept pages, and one node per log.md (the viewer at ad30107 draws the update log as a node; they are counted apart). These tests use a stub generator in a temporary upstream folder, never Google's code; the real run is on the bench. The fixtures are synthetic text about bread (CLAUDE.md rule 3). Run: python3 -m unittest discover -s tests -p 'test_google_viewer_check.py' """ from __future__ import annotations import contextlib import importlib.util import io import json import sys import tempfile import unittest from pathlib import Path from typing import Any ROOT = Path(__file__).resolve().parents[1] # Loaded from its file, as tests/test_fetch_docs.py loads its tool; mypy checks the tool when it is named. _SPEC = importlib.util.spec_from_file_location("google_viewer_check", ROOT / "tools" / "google_viewer_check.py") assert _SPEC is not None and _SPEC.loader is not None gv: Any = importlib.util.module_from_spec(_SPEC) sys.modules["google_viewer_check"] = gv _SPEC.loader.exec_module(gv) # Like Google's generator at ad30107: every .md except index.md is a node, and the graph is embedded in the page as # one line "window.BUNDLE = ;". MODE changes one thing per test. STUB = ''' import json, os, sys from pathlib import Path MODE = {mode!r} def generate_visualization(bundle_root, out_path, *, bundle_name=None): bundle_root, out_path = Path(bundle_root), Path(out_path) if MODE == "raise": raise RuntimeError("boom") if MODE == "exit": sys.exit(3) if MODE == "touch": (bundle_root / "written-by-the-viewer.md").write_text("x", encoding="utf-8") ids = sorted(str(p.relative_to(bundle_root).with_suffix("")) for p in bundle_root.rglob("*.md") if p.name != "index.md") if MODE == "drop": ids = ids[1:] if MODE == "droplog": ids = [i for i in ids if i.split("/")[-1] != "log"] graph = {{"nodes": [{{"data": {{"id": i}}}} for i in ids], "edges": [], "isolated": sys.flags.isolated, "cwd": os.getcwd(), "pycache": sys.dont_write_bytecode}} if MODE == "traceback": print("Traceback (most recent call last):", file=sys.stderr) if MODE != "nofile": out_path.parent.mkdir(parents=True, exist_ok=True) out_path.write_text("\\n\\n\\n", encoding="utf-8") return {{"concepts": len(ids), "edges": 0, "bytes": 1}} ''' PAGE = """--- type: Concept title: {title} --- # {title} A note about {title}. """ class Fixture(unittest.TestCase): def setUp(self) -> None: self._tmp = tempfile.TemporaryDirectory(prefix="google-viewer-test-") self.root = Path(self._tmp.name) self.bundle = self.root / "bundle" (self.bundle / "sub").mkdir(parents=True) for rel, title in (("sourdough.md", "Sourdough"), ("crust.md", "Crust"), ("sub/rye.md", "Rye")): (self.bundle / rel).write_text(PAGE.format(title=title), encoding="utf-8") (self.bundle / "index.md").write_text("# Bread\n\n* [Sourdough](sourdough.md) - A bread.\n", encoding="utf-8") (self.bundle / "log.md").write_text("# Directory Update Log\n\n## 2026-10-09\n* Added.\n", encoding="utf-8") (self.bundle / "sub" / "log.md").write_text("# Directory Update Log\n\n## 2026-10-09\n* Added.\n", encoding="utf-8") self.upstream = self.root / "upstream" self.stub("ok") def tearDown(self) -> None: self._tmp.cleanup() def stub(self, mode: str) -> None: viewer = self.upstream / "src" / "reference_agent" / "viewer" viewer.mkdir(parents=True, exist_ok=True) (self.upstream / "src" / "reference_agent" / "__init__.py").write_text("", encoding="utf-8") (viewer / "__init__.py").write_text("", encoding="utf-8") (viewer / "generator.py").write_text(STUB.format(mode=mode), encoding="utf-8") def run_check(self, *extra: str) -> tuple[int, str]: out = io.StringIO() with contextlib.redirect_stdout(out), contextlib.redirect_stderr(out): code = gv.main([str(self.bundle), "--upstream", str(self.upstream), *extra]) return code, out.getvalue() def graph(self, path: Path) -> dict[str, Any]: line = next(x for x in path.read_text(encoding="utf-8").splitlines() if x.startswith("window.BUNDLE = ")) return json.loads(line[len("window.BUNDLE = "):-1]) # type: ignore[no-any-return] class CheckTest(Fixture): def test_one_node_per_concept_page_passes(self) -> None: code, out = self.run_check() self.assertEqual(0, code, out) self.assertIn("PASS", out) self.assertIn("nodes 3", out) self.assertIn("concept pages 3", out) def test_the_viewer_reads_the_whole_bundle_and_counts_the_log_nodes_apart(self) -> None: # The stub, like Google's generator, draws every .md but index.md, the two log.md files too. graph_file = self.root / "graph.html" code, out = self.run_check("--out", str(graph_file)) self.assertEqual(0, code, out) ids = sorted(n["data"]["id"] for n in self.graph(graph_file)["nodes"]) self.assertEqual(["crust", "log", "sourdough", "sub/log", "sub/rye"], ids) self.assertIn("log nodes 2 of 2", out) def test_a_log_md_the_viewer_does_not_draw_fails(self) -> None: self.stub("droplog") code, out = self.run_check() self.assertEqual(1, code, out) self.assertIn("log nodes 0 of 2", out) def test_it_runs_isolated_without_bytecode_from_another_folder(self) -> None: graph_file = self.root / "graph.html" self.assertEqual(0, self.run_check("--out", str(graph_file))[0]) graph = self.graph(graph_file) self.assertEqual(1, graph["isolated"]) self.assertTrue(graph["pycache"]) cwd = Path(graph["cwd"]).resolve() for inside in (self.upstream, self.bundle, ROOT): self.assertFalse(cwd == inside.resolve() or inside.resolve() in cwd.parents, cwd) self.assertEqual([], list(self.upstream.rglob("__pycache__"))) def test_the_bundle_itself_is_never_changed(self) -> None: self.stub("touch") self.run_check() self.assertFalse((self.bundle / "written-by-the-viewer.md").exists()) def test_a_viewer_that_exits_non_zero_fails(self) -> None: self.stub("exit") code, out = self.run_check() self.assertEqual(1, code, out) self.assertIn("FAIL", out) def test_a_viewer_that_raises_fails(self) -> None: self.stub("raise") code, out = self.run_check() self.assertEqual(1, code, out) self.assertIn("Traceback", out) def test_a_traceback_in_the_output_fails_even_with_exit_0(self) -> None: self.stub("traceback") code, out = self.run_check() self.assertEqual(1, code, out) self.assertIn("FAIL", out) def test_one_node_too_few_fails(self) -> None: self.stub("drop") code, out = self.run_check() self.assertEqual(1, code, out) self.assertIn("nodes 2", out) def test_a_viewer_that_writes_no_graph_fails(self) -> None: self.stub("nofile") self.assertEqual(1, self.run_check()[0]) def test_a_bundle_without_concept_pages_fails(self) -> None: for rel in ("sourdough.md", "crust.md", "sub/rye.md"): (self.bundle / rel).unlink() self.assertEqual(1, self.run_check()[0]) def test_a_missing_bundle_or_generator_cannot_run(self) -> None: self.assertEqual(2, gv.main([str(self.root / "nope"), "--upstream", str(self.upstream)])) (self.upstream / "src" / "reference_agent" / "viewer" / "generator.py").unlink() self.assertEqual(2, self.run_check()[0]) if __name__ == "__main__": unittest.main()