okf-wiki/tests/test_google_viewer_check.py
Kjell Tore Guttormsen 0fd86a23a3
okf-wiki 1.1.1
First public release, published as one snapshot. What changed between
versions is in CHANGELOG.md.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 21:03:20 +01:00

191 lines
8.2 KiB
Python

"""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 = <json>;". 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("<html>\\n<script>\\nwindow.BUNDLE_NAME = " + json.dumps(bundle_name or "") + ";\\n"
"window.BUNDLE = " + json.dumps(graph) + ";\\n</script>\\n</html>\\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()