askrobots / dbbasic-object-server
Public
Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.
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 |
| 3 | category, 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 |
| 5 | of the shared /style theme and the ONE shared markdown renderer at |
| 6 | /markdown. Content is seeded doc_pages records adapted from the internal |
| 7 | docs/ tree; the whole surface is public and unauthenticated. |
| 8 | |
| 9 | Behavioral JS tests follow the repo's node-execution pattern (see |
| 10 | tests/test_markdown_object.py): extract the real function source from the |
| 11 | Python-embedded script string, run it under node with stubbed globals, |
| 12 | assert on real output -- not just source-text greps. |
| 13 | """ |
| 14 | |
| 15 | import csv |
| 16 | import json |
| 17 | import re |
| 18 | import shutil |
| 19 | import subprocess |
| 20 | from pathlib import Path |
| 21 | |
| 22 | import pytest |
| 23 | |
| 24 | import object_packages |
| 25 | |
| 26 | PACKAGES_ROOT = Path(__file__).resolve().parents[1] / "packages" |
| 27 | APP_DOCS_DIR = PACKAGES_ROOT / "app-docs" |
| 28 | |
| 29 | NAV_SOURCE = (APP_DOCS_DIR / "objects" / "site" / "docs_nav.py").read_text() |
| 30 | INDEX_SOURCE = (APP_DOCS_DIR / "objects" / "site" / "docs_index.py").read_text() |
| 31 | DETAIL_SOURCE = (APP_DOCS_DIR / "objects" / "site" / "docs_detail.py").read_text() |
| 32 | |
| 33 | |
| 34 | def _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 | |
| 39 | def _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 | |
| 49 | def 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 | |
| 60 | def 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 | |
| 74 | def 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 | |
| 87 | def 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 | |
| 103 | def 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 | |
| 122 | def 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 | |
| 133 | def 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 | |
| 141 | def 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 | |
| 157 | def 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 | |
| 168 | def 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 | |
| 183 | def 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 | |
| 195 | def _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 | |
| 210 | def 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" + """ |
| 217 | const 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 | ]; |
| 224 | const sorted = sortManifest(records); |
| 225 | const groups = groupByCategory(sorted); |
| 226 | console.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 | |
| 246 | def 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(""" |
| 252 | const esc = (s) => String(s == null ? "" : s).replace(/[&<>"']/g, |
| 253 | (c) => ({"&": "&", "<": "<", ">": ">", '"': """, "'": "'"}[c])); |
| 254 | """ + slug_fn + "\n" + toc_fn + "\n" + """ |
| 255 | global.document = {getElementById: () => null}; |
| 256 | function head(tag, text) { |
| 257 | return {tagName: tag.toUpperCase(), textContent: text, id: ""}; |
| 258 | } |
| 259 | const heads = [head("h2", "Setup"), head("h3", "Setup"), head("h2", "Run & verify")]; |
| 260 | const container = {querySelectorAll: () => heads}; |
| 261 | const html = buildToc(container); |
| 262 | console.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 | |
| 274 | def 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" + """ |
| 279 | function item(haystack) { |
| 280 | return { |
| 281 | style: {display: ""}, |
| 282 | getAttribute: (name) => (name === "data-search" ? haystack : null), |
| 283 | }; |
| 284 | } |
| 285 | const one = item("quickstart from a fresh vm start here"); |
| 286 | const two = item("permissions model security"); |
| 287 | const groupOne = {style: {display: ""}, querySelectorAll: () => [one]}; |
| 288 | const groupTwo = {style: {display: ""}, querySelectorAll: () => [two]}; |
| 289 | let handler = null; |
| 290 | const inputEl = { |
| 291 | value: "", |
| 292 | addEventListener: (evt, fn) => { handler = fn; }, |
| 293 | }; |
| 294 | const listEl = { |
| 295 | querySelectorAll: (sel) => |
| 296 | (sel === ".navitem" ? [one, two] : [groupOne, groupTwo]), |
| 297 | }; |
| 298 | wireSearch(inputEl, listEl); |
| 299 | inputEl.value = "PERMISS"; |
| 300 | handler(); |
| 301 | const filtered = [one.style.display, two.style.display, groupOne.style.display, groupTwo.style.display]; |
| 302 | inputEl.value = ""; |
| 303 | handler(); |
| 304 | const restored = [one.style.display, two.style.display, groupOne.style.display, groupTwo.style.display]; |
| 305 | console.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 | |
| 316 | def 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(""" |
| 321 | const esc = (s) => String(s == null ? "" : s).replace(/[&<>"']/g, |
| 322 | (c) => ({"&": "&", "<": "<", ">": ">", '"': """, "'": "'"}[c])); |
| 323 | """ + pager_fn + "\n" + """ |
| 324 | const middle = pagerHtml({id: "why", title: "Why"}, {id: "quickstart", title: "Quickstart"}); |
| 325 | const first = pagerHtml(null, {id: "quickstart", title: "Quickstart"}); |
| 326 | const last = pagerHtml({id: "why", title: "Why"}, null); |
| 327 | console.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"] |