Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.

0 downloads

dbbasic-object-server/tests/test_app_docs_package.py
Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-object-server.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-object-server.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-object-server.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

danq9 signup: the person chooses the password and name on the confirm page 83c7aa6 2 weeks, 5 days ago History
test_app_docs_package.py · 13.8 KB · 334 lines
1"""Tests for packages/app-docs: the public documentation site at /docs and
2/docs/{slug}. A Rails-Guides-shaped guide site -- sidebar grouped by
3category, client-side search, per-page table of contents, prev/next paging
4-- built as bespoke page objects (not the view_render block system) on top
5of the shared /style theme and the ONE shared markdown renderer at
6/markdown. Content is seeded doc_pages records adapted from the internal
7docs/ tree; the whole surface is public and unauthenticated.
8
9Behavioral JS tests follow the repo's node-execution pattern (see
10tests/test_markdown_object.py): extract the real function source from the
11Python-embedded script string, run it under node with stubbed globals,
12assert on real output -- not just source-text greps.
13"""
14
15import csv
16import json
17import re
18import shutil
19import subprocess
20from pathlib import Path
21
22import pytest
23
24import object_packages
25
26PACKAGES_ROOT = Path(__file__).resolve().parents[1] / "packages"
27APP_DOCS_DIR = PACKAGES_ROOT / "app-docs"
28
29NAV_SOURCE = (APP_DOCS_DIR / "objects" / "site" / "docs_nav.py").read_text()
30INDEX_SOURCE = (APP_DOCS_DIR / "objects" / "site" / "docs_index.py").read_text()
31DETAIL_SOURCE = (APP_DOCS_DIR / "objects" / "site" / "docs_detail.py").read_text()
32
33
34def _seed_rows(name):
35 with open(APP_DOCS_DIR / "seed" / f"{name}.tsv", newline="") as fh:
36 return list(csv.DictReader(fh, delimiter="\t"))
37
38
39def _node():
40 node = shutil.which("node")
41 if node is None:
42 pytest.skip("node not available")
43 return node
44
45
46# --- package shape -----------------------------------------------------------
47
48
49def test_manifest_ships_three_objects_schema_permissions_and_both_seeds():
50 package = object_packages.get_package("app-docs", root=PACKAGES_ROOT)
51 assert {o["id"] for o in package["objects"]} == {
52 "site_docs_nav", "site_docs_index", "site_docs_detail",
53 }
54 assert {s["collection"] for s in package["schemas"]} == {"doc_pages"}
55 assert {entry["collection"] for entry in package["seed"]} == {
56 "site_routes", "doc_pages",
57 }
58
59
60def test_routes_seed_detail_and_index_with_articles_style_priorities():
61 rows = _seed_rows("site_routes")
62 by_id = {r["id"]: r for r in rows}
63 detail = by_id["route_docs_detail"]
64 index = by_id["route_docs_index"]
65 assert detail["pattern"] == "/docs/{slug}"
66 assert detail["object_id"] == "site_docs_detail"
67 assert index["pattern"] == "/docs"
68 assert index["object_id"] == "site_docs_index"
69 # Same convention as app-articles: the more specific pattern gets the
70 # lower (higher-precedence) priority number.
71 assert int(detail["priority"]) < int(index["priority"])
72
73
74def test_routes_seed_pins_the_script_objects_for_prefixed_hosts():
75 """/docs/{slug} matches on every host as a route record, but the two
76 scripts the page loads (/docs-nav, /markdown) were convention-only, so on
77 a site_hosts domain with its own prefix they resolved to {prefix}_docs_nav
78 and {prefix}_markdown, 404ed, and the page sat on "Loading..." forever.
79 Route rows make them resolve wherever the docs page itself does."""
80 by_id = {r["id"]: r for r in _seed_rows("site_routes")}
81 assert by_id["route_docs_nav"]["pattern"] == "/docs-nav"
82 assert by_id["route_docs_nav"]["object_id"] == "site_docs_nav"
83 assert by_id["route_docs_markdown"]["pattern"] == "/markdown"
84 assert by_id["route_docs_markdown"]["object_id"] == "site_markdown"
85
86
87def test_permissions_make_every_surface_public():
88 payload = json.loads((APP_DOCS_DIR / "permissions" / "rules.json").read_text())
89 rules = payload["rules"]
90 assert all(rule["principal"] == "public" for rule in rules)
91 read_rules = [r for r in rules if "read" in r["actions"]]
92 assert any(r.get("collection") == "doc_pages" for r in read_rules)
93 # A doc page is public unconditionally -- no row_filter gate like
94 # articles' is_public, because nothing non-public is ever seeded.
95 assert all("row_filter" not in r for r in read_rules)
96 executable = {r.get("object_id") for r in rules if "execute" in r["actions"]}
97 # All three page objects, including the shared nav script -- without
98 # site_docs_nav here the sidebar 403s for anonymous visitors and the
99 # whole site is broken for exactly the audience it exists for.
100 assert executable == {"site_docs_nav", "site_docs_index", "site_docs_detail"}
101
102
103def test_doc_pages_seed_is_nonempty_and_every_row_is_complete():
104 rows = _seed_rows("doc_pages")
105 assert len(rows) >= 30
106 slug_re = re.compile(r"^[a-z0-9][a-z0-9-]*$")
107 seen = set()
108 for row in rows:
109 assert slug_re.fullmatch(row["id"]), row["id"]
110 assert row["id"] not in seen
111 seen.add(row["id"])
112 assert row["title"].strip()
113 assert row["category"].strip()
114 assert int(row["nav_order"]) > 0
115 assert row["summary"].strip()
116 assert len(row["content"]) > 500, f"{row['id']} content suspiciously short"
117 # The page template renders the title itself -- content starting
118 # with an H1 would double the title on every page.
119 assert not row["content"].lstrip().startswith("# ")
120
121
122def test_seeded_cross_links_resolve_to_seeded_slugs_only():
123 rows = _seed_rows("doc_pages")
124 slugs = {row["id"] for row in rows}
125 link_re = re.compile(r"\]\(/docs/([A-Za-z0-9_-]+)")
126 for row in rows:
127 for slug in link_re.findall(row["content"]):
128 assert slug in slugs, f"{row['id']} links to unseeded /docs/{slug}"
129 # No internal-tree .md links should survive the seed build.
130 assert ".md)" not in row["content"], f"{row['id']} kept a raw .md link"
131
132
133def test_no_disallowed_org_names_leak_into_the_package():
134 banned = re.compile(r"\bq9\b|askrobots|\bwold\b", re.IGNORECASE)
135 for path in sorted(APP_DOCS_DIR.rglob("*")):
136 if path.is_file():
137 hits = banned.findall(path.read_text(errors="replace"))
138 assert not hits, f"{path} contains banned names: {hits}"
139
140
141def test_dry_run_is_safe(tmp_path):
142 object_root = tmp_path / "objects"
143 object_root.mkdir()
144 plan = object_packages.dry_run_package(
145 "app-docs",
146 root=PACKAGES_ROOT,
147 base_dir=tmp_path / "data",
148 object_roots=[object_root],
149 )
150 assert plan["safe_to_install"] is True
151 assert plan["warnings"] == []
152
153
154# --- page structure ----------------------------------------------------------
155
156
157def test_pages_are_public_chrome_not_the_signed_in_apps():
158 for source in (INDEX_SOURCE, DETAIL_SOURCE):
159 # The shared building blocks every themed page uses...
160 assert '<link rel="stylesheet" href="/style">' in source
161 assert '<script src="/markdown"></script>' in source
162 assert '<script src="/docs-nav"></script>' in source
163 # ...but never the internal signed-in shell's nav or a login nudge.
164 assert 'src="/nav"' not in source
165 assert "/login" not in source
166
167
168def test_detail_gates_the_slug_before_interpolating_into_script():
169 # `slug` is URL-derived and lands inside a <script> block via {slug!r};
170 # repr-escaping alone cannot stop a "</script>" payload from closing
171 # the tag, so the same regex gate view_render.py uses must run first.
172 assert "_SLUG_RE" in DETAIL_SOURCE
173 gate = DETAIL_SOURCE.index("_SLUG_RE.fullmatch(slug)")
174 interpolate = DETAIL_SOURCE.index("{slug!r}")
175 assert gate < interpolate
176 pattern = re.search(r'_SLUG_RE = re\.compile\(r"([^"]+)"\)', DETAIL_SOURCE)
177 compiled = re.compile(pattern.group(1))
178 assert not compiled.fullmatch("</script><script>alert(1)</script>")
179 assert not compiled.fullmatch("")
180 assert compiled.fullmatch("single-vm-deployment")
181
182
183def test_nav_manifest_fetch_is_cached_per_tab_not_per_navigation():
184 # Every /docs/{slug} click is a full page load; the manifest (all page
185 # bodies included) is a few hundred KB -- so it must come from
186 # sessionStorage after the first load, not refetch each navigation.
187 assert "sessionStorage.getItem" in NAV_SOURCE
188 assert "sessionStorage.setItem" in NAV_SOURCE
189 assert NAV_SOURCE.count("/collections/doc_pages/records") == 1
190
191
192# --- real JS behavior (node-executed) ---------------------------------------
193
194
195def _extract_js(source, marker):
196 """Extract a top-level `function name(...) {...}` from the embedded JS
197 by brace counting, starting at `marker`."""
198 start = source.index(marker)
199 depth = 0
200 for i in range(start, len(source)):
201 if source[i] == "{":
202 depth += 1
203 elif source[i] == "}":
204 depth -= 1
205 if depth == 0:
206 return source[start:i + 1]
207 raise AssertionError(f"unbalanced braces after {marker}")
208
209
210def test_sidebar_sorts_by_nav_order_and_groups_by_first_appearance(tmp_path):
211 node = _node()
212 sort_fn = _extract_js(NAV_SOURCE, "function sortManifest(")
213 group_fn = _extract_js(NAV_SOURCE, "function groupByCategory(")
214 probe = tmp_path / "probe.js"
215 probe.write_text(
216 sort_fn + "\n" + group_fn + "\n" + """
217const records = [
218 {id: "c", title: "C", category: "Two", nav_order: "300"},
219 {id: "a", title: "A", category: "One", nav_order: "100"},
220 {id: "d", title: "D", category: "One", nav_order: "110"},
221 {id: "b", title: "B", category: "Two", nav_order: "250"},
222 {id: "x", title: "X", category: "", nav_order: "junk"},
223];
224const sorted = sortManifest(records);
225const groups = groupByCategory(sorted);
226console.log(JSON.stringify({
227 order: sorted.map((r) => r.id),
228 groups: groups.map((g) => [g.category, g.items.map((i) => i.id)]),
229}));
230""")
231 out = subprocess.run([node, str(probe)], capture_output=True, text=True)
232 assert out.returncode == 0, out.stderr
233 result = json.loads(out.stdout)
234 # Numeric sort (not string sort -- "300" > "1000" as strings), with the
235 # unparseable nav_order sinking to the end.
236 assert result["order"] == ["a", "d", "b", "c", "x"]
237 # Groups keep first-appearance order over the sorted list; a blank
238 # category lands in "General".
239 assert result["groups"] == [
240 ["One", ["a", "d"]],
241 ["Two", ["b", "c"]],
242 ["General", ["x"]],
243 ]
244
245
246def test_toc_builder_assigns_ids_dedupes_and_indents_h3(tmp_path):
247 node = _node()
248 slug_fn = _extract_js(DETAIL_SOURCE, "function slugify(")
249 toc_fn = _extract_js(DETAIL_SOURCE, "function buildToc(")
250 probe = tmp_path / "probe.js"
251 probe.write_text("""
252const esc = (s) => String(s == null ? "" : s).replace(/[&<>"']/g,
253 (c) => ({"&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;"}[c]));
254""" + slug_fn + "\n" + toc_fn + "\n" + """
255global.document = {getElementById: () => null};
256function head(tag, text) {
257 return {tagName: tag.toUpperCase(), textContent: text, id: ""};
258}
259const heads = [head("h2", "Setup"), head("h3", "Setup"), head("h2", "Run & verify")];
260const container = {querySelectorAll: () => heads};
261const html = buildToc(container);
262console.log(JSON.stringify({ids: heads.map((h) => h.id), html: html}));
263""")
264 out = subprocess.run([node, str(probe)], capture_output=True, text=True)
265 assert out.returncode == 0, out.stderr
266 result = json.loads(out.stdout)
267 # Duplicate heading text gets a deduped id, punctuation slugifies away.
268 assert result["ids"] == ["setup", "setup-2", "run-verify"]
269 assert '#setup"' in result["html"]
270 assert '#setup-2"' in result["html"]
271 assert "doctocsub" in result["html"] # the h3 is indented
272
273
274def test_search_filter_hides_nonmatching_items_and_empty_groups(tmp_path):
275 node = _node()
276 wire_fn = _extract_js(NAV_SOURCE, "function wireSearch(")
277 probe = tmp_path / "probe.js"
278 probe.write_text(wire_fn + "\n" + """
279function item(haystack) {
280 return {
281 style: {display: ""},
282 getAttribute: (name) => (name === "data-search" ? haystack : null),
283 };
284}
285const one = item("quickstart from a fresh vm start here");
286const two = item("permissions model security");
287const groupOne = {style: {display: ""}, querySelectorAll: () => [one]};
288const groupTwo = {style: {display: ""}, querySelectorAll: () => [two]};
289let handler = null;
290const inputEl = {
291 value: "",
292 addEventListener: (evt, fn) => { handler = fn; },
293};
294const listEl = {
295 querySelectorAll: (sel) =>
296 (sel === ".navitem" ? [one, two] : [groupOne, groupTwo]),
297};
298wireSearch(inputEl, listEl);
299inputEl.value = "PERMISS";
300handler();
301const filtered = [one.style.display, two.style.display, groupOne.style.display, groupTwo.style.display];
302inputEl.value = "";
303handler();
304const restored = [one.style.display, two.style.display, groupOne.style.display, groupTwo.style.display];
305console.log(JSON.stringify({filtered, restored}));
306""")
307 out = subprocess.run([node, str(probe)], capture_output=True, text=True)
308 assert out.returncode == 0, out.stderr
309 result = json.loads(out.stdout)
310 # Case-insensitive match keeps only the permissions item and its group.
311 assert result["filtered"] == ["none", "", "none", ""]
312 # Clearing the box restores everything.
313 assert result["restored"] == ["", "", "", ""]
314
315
316def test_prev_next_pager_walks_the_manifest_sequence(tmp_path):
317 node = _node()
318 pager_fn = _extract_js(DETAIL_SOURCE, "function pagerHtml(")
319 probe = tmp_path / "probe.js"
320 probe.write_text("""
321const esc = (s) => String(s == null ? "" : s).replace(/[&<>"']/g,
322 (c) => ({"&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;"}[c]));
323""" + pager_fn + "\n" + """
324const middle = pagerHtml({id: "why", title: "Why"}, {id: "quickstart", title: "Quickstart"});
325const first = pagerHtml(null, {id: "quickstart", title: "Quickstart"});
326const last = pagerHtml({id: "why", title: "Why"}, null);
327console.log(JSON.stringify({middle, first, last}));
328""")
329 out = subprocess.run([node, str(probe)], capture_output=True, text=True)
330 assert out.returncode == 0, out.stderr
331 result = json.loads(out.stdout)
332 assert '/docs/why' in result["middle"] and '/docs/quickstart' in result["middle"]
333 assert '/docs/why' not in result["first"] and '/docs/quickstart' in result["first"]
334 assert '/docs/quickstart' not in result["last"] and '/docs/why' in result["last"]