test_doc_gs.py
python
sha256:c2ee54efa85fcbdeea4ffc84a2dd1b8fcd4623463b22e35765df3013a26834aa
merge: #276 public URLs + muse#181 docs onto dev (#313 present)
Opus 5.5
minor
⚠ breaking
1 day ago
| 1 | """DOC_GS — /muse/getting-started first-run contract (musehub#244). |
| 2 | |
| 3 | Each claim below was walked against the installed muse 0.2.1rc20 CLI in a disposable sandbox |
| 4 | (2026-11-06): a commit is signed only with ``--sign`` or ``commit.sign = true``, and |
| 5 | ``verify-commit --strict`` confirms it; a new repo starts on ``main``; keys are derived at a |
| 6 | hub-scoped HD path; ``muse hub connect`` rejects non-loopback ``http://``; the edge redirects |
| 7 | ``http://…/install.sh`` with a 301. Rendering is the shared in-process fixture (no database). |
| 8 | """ |
| 9 | |
| 10 | from __future__ import annotations |
| 11 | |
| 12 | import re |
| 13 | from collections.abc import Iterator |
| 14 | from pathlib import Path |
| 15 | from urllib.parse import urlsplit |
| 16 | |
| 17 | import pytest |
| 18 | from fastapi.testclient import TestClient |
| 19 | |
| 20 | from musehub.api.routes.musehub.ui_docs import _PHASES |
| 21 | from musehub.main import app |
| 22 | from musehub.api.routes.musehub import ui_docs |
| 23 | from tests.docs_contract import registry_check as rc |
| 24 | from tests.docs_contract.cli_check import extract_commands |
| 25 | from tests.docs_contract.pages import _render |
| 26 | |
| 27 | PAGE = rc.phase_path("getting-started") |
| 28 | |
| 29 | |
| 30 | @pytest.fixture(scope="module") |
| 31 | def html(rendered: dict[str, str]) -> str: |
| 32 | return rendered[PAGE].replace("'", "'") |
| 33 | |
| 34 | |
| 35 | def _render_on(base_url: str) -> str: |
| 36 | """The page as served from ``base_url`` (host-dependent examples; same version pin as ``rendered``).""" |
| 37 | return _render(TestClient(app, base_url=base_url), [PAGE])[PAGE].replace("'", "'") |
| 38 | |
| 39 | |
| 40 | @pytest.fixture(scope="module") |
| 41 | def staging_html() -> str: |
| 42 | return _render_on("https://staging.musehub.ai") |
| 43 | |
| 44 | |
| 45 | @pytest.fixture(scope="module") |
| 46 | def commands(html: str) -> list[str]: |
| 47 | """Documented ``muse …`` lines in first-appearance order.""" |
| 48 | return [c.line for c in extract_commands(html)] |
| 49 | |
| 50 | |
| 51 | def _section(html: str, section_id: str) -> str: |
| 52 | """One ``<section>``'s HTML, whitespace-collapsed so wrapped prose matches.""" |
| 53 | return " ".join(html.split(f'id="{section_id}"', 1)[1].split("</section>", 1)[0].split()) |
| 54 | |
| 55 | |
| 56 | # ── DOC_GS_02: "What's next" is the registry ──────────────────────────────── |
| 57 | |
| 58 | |
| 59 | def test_whats_next_lists_every_other_section_in_registry_order(html: str) -> None: |
| 60 | rows = re.findall(r'<a href="(/muse/[\w-]+)">([^<]+)</a>', _section(html, "next")) |
| 61 | expected = [(rc.phase_path(s), f"{n} — {t}") for s, n, t, _ in _PHASES if s != "getting-started"] |
| 62 | assert rows == expected |
| 63 | |
| 64 | |
| 65 | # ── DOC_GS_03: sample output follows the request host ─────────────────────── |
| 66 | |
| 67 | |
| 68 | def test_identity_sample_output_does_not_hard_code_a_hub_host(html: str) -> None: |
| 69 | assert "staging.musehub.ai" not in _section(html, "identity") |
| 70 | |
| 71 | |
| 72 | # ── DOC_GS_07: the first-run path never teaches an unsigned commit ────────── |
| 73 | |
| 74 | |
| 75 | def test_every_documented_commit_and_merge_signs(commands: list[str]) -> None: |
| 76 | writes = [c for c in commands if c.startswith(("muse commit ", "muse merge "))] |
| 77 | assert writes, "the page documents no commit" |
| 78 | assert [c for c in writes if "--sign" not in c.split()] == [] |
| 79 | |
| 80 | |
| 81 | def test_signing_is_confirmed_with_strict_verification(commands: list[str]) -> None: |
| 82 | assert any(c.startswith("muse verify-commit ") and "--strict" in c.split() for c in commands) |
| 83 | |
| 84 | |
| 85 | def test_no_signing_output_the_cli_does_not_print(html: str) -> None: |
| 86 | # rc20 `commit --sign` prints the commit line and file summary only; there is no "signed with" line. |
| 87 | assert "signed with ed25519:" not in html |
| 88 | |
| 89 | |
| 90 | def test_bridge_note_does_not_claim_native_commits_are_always_signed(html: str) -> None: |
| 91 | assert "all commits made natively in Muse going forward will" not in _section(html, "migrate") |
| 92 | |
| 93 | |
| 94 | # ── DOC_GS_08: examples run in a brand-new repo, in order ─────────────────── |
| 95 | |
| 96 | |
| 97 | def test_branch_cycle_creates_dev_before_checking_it_out(commands: list[str]) -> None: |
| 98 | # `muse init` creates `main` only; `muse checkout dev` fails until dev exists. |
| 99 | assert "muse checkout -b dev" in commands |
| 100 | assert commands.index("muse checkout -b dev") < commands.index("muse checkout dev") |
| 101 | |
| 102 | |
| 103 | def test_hd_paths_include_the_hub_level(html: str) -> None: |
| 104 | # Since hub scoping, identity keys sit at m/1075233755'/1660078172'/0'/0'/0'/<hub>'/0'. |
| 105 | assert "m/1075233755'/1660078172'/0'/0'/0'/0'" not in html |
| 106 | |
| 107 | |
| 108 | # ── DOC_GS_09: troubleshooting matches the deployed edge and CLI ──────────── |
| 109 | |
| 110 | |
| 111 | def test_troubleshooting_has_no_stale_http_522_row(html: str) -> None: |
| 112 | assert "error: 522" not in html |
| 113 | |
| 114 | |
| 115 | # ── DOC_GS_10–12: hub-side QA findings on staging (2026-11-06, rc19 = rc20 for these paths) ── |
| 116 | |
| 117 | |
| 118 | def _hub_of(cmd: str) -> str | None: |
| 119 | toks = cmd.split() |
| 120 | return toks[toks.index("--hub") + 1] if "--hub" in toks[:-1] else None |
| 121 | |
| 122 | |
| 123 | def _add_remote_html(html: str) -> str: |
| 124 | return html.split('id="add-remote"', 1)[1].split("</section>", 1)[0] |
| 125 | |
| 126 | |
| 127 | def test_whoami_targets_the_registration_hub(html: str, commands: list[str]) -> None: |
| 128 | # GS-17: outside a repo, `muse auth whoami` falls back to https://localhost:1337 and finds no identity. |
| 129 | reg = {_hub_of(c) for c in commands if c.startswith(("muse auth keygen ", "muse auth register "))} |
| 130 | assert len(reg) == 1 and None not in reg |
| 131 | hub = next(iter(reg)) |
| 132 | assert "testserver" in hub, "hub must come from the request host, not a hard-coded deployment" |
| 133 | sec = html.split('id="identity"', 1)[1].split("</section>", 1)[0] |
| 134 | shown = [c.line for c in extract_commands(sec) if c.in_pre and c.line.startswith("muse auth whoami")] |
| 135 | shown += re.findall(r'devdocs-code-label">(muse auth whoami[^<]*)<', sec) # e.g. the --json example's label |
| 136 | assert shown, "the identity section documents whoami" |
| 137 | assert all(f"--hub {hub}" in s for s in shown), shown |
| 138 | |
| 139 | |
| 140 | def test_remote_setup_accounts_for_remotes_created_by_init(staging_html: str) -> None: |
| 141 | # GS-18: after registration, `muse init` writes local/staging/production remotes as <hub>/<handle>/<directory>. |
| 142 | sec = _add_remote_html(staging_html) |
| 143 | text = " ".join(re.sub(r"<[^>]+>", " ", sec).split()) |
| 144 | runnable = [c.line for c in extract_commands(sec) if c.in_pre] |
| 145 | assert not [c for c in runnable if re.match(r"muse remote add (local|staging|production)\b", c)], runnable |
| 146 | assert "muse init" in text and all(n in text for n in ("local", "staging", "production")), "explain init's remotes" |
| 147 | assert "directory" in text, "explain that the remote URL is derived from the directory name" |
| 148 | assert "muse remote -v" in runnable and any(c.startswith("muse remote set-url staging ") for c in runnable) |
| 149 | assert runnable.index("muse remote -v") < next(i for i, c in enumerate(runnable) if c.startswith("muse remote set-url")) |
| 150 | created = next(c for c in runnable if c.startswith("muse hub repo create ")) |
| 151 | name = created.split("--name", 1)[1].split()[0] |
| 152 | target = next(c for c in runnable if c.startswith("muse remote set-url staging ")).split()[-1] |
| 153 | assert target.rstrip("/").endswith(f"/your-handle/{name}"), (target, name) |
| 154 | |
| 155 | |
| 156 | def test_push_404_troubleshooting_checks_the_remote_url(html: str) -> None: |
| 157 | # GS-19: a 404 is a missing repo OR a remote URL pointing at one; a missing login is a 401, not a 404. |
| 158 | callout = next(" ".join(re.sub(r"<[^>]+>", " ", c.split("</div>", 1)[0]).split()) |
| 159 | for c in html.split('class="devdocs-callout') if "Repository not found on remote" in c.split("</div>", 1)[0]) |
| 160 | assert "muse remote -v" in callout and "muse remote set-url" in callout |
| 161 | assert "muse hub repo create" in callout |
| 162 | assert "401" in callout and "muse auth" in callout, "distinguish authentication failures" |
| 163 | |
| 164 | |
| 165 | # ── DOC_GS_06: no verified release → the page stays readable, nothing is installable ── |
| 166 | # Owner ruling 2026-11-07 (#244 "Getting Started without an active release"): 200 with an explicit |
| 167 | # notice and no version string; /install.sh keeps failing closed. The real selector runs against an |
| 168 | # empty releases directory (no active.json), so this is the production code path, not a patch. |
| 169 | |
| 170 | _UNAVAILABLE = 'data-release-state="unavailable"' |
| 171 | |
| 172 | |
| 173 | @pytest.fixture |
| 174 | def no_release(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Iterator[tuple[TestClient, Path]]: |
| 175 | from musehub.config import settings |
| 176 | |
| 177 | monkeypatch.setattr(settings, "musehub_releases_dir", str(tmp_path)) |
| 178 | yield TestClient(app), tmp_path # no context manager → no lifespan → no database |
| 179 | |
| 180 | |
| 181 | def test_page_renders_without_an_active_release(no_release: tuple[TestClient, Path]) -> None: |
| 182 | client, releases = no_release |
| 183 | r = client.get(PAGE) |
| 184 | assert r.status_code == 200 |
| 185 | page = r.text |
| 186 | assert page.count(_UNAVAILABLE) == 2, "both the install step and the version sample say so" |
| 187 | assert "No verified Muse release is available on this instance" in page |
| 188 | for section in ("prerequisites", "install", "identity", "new-repo", "workflow", "migrate", "next"): |
| 189 | assert f'id="{section}"' in page, f"static content stays readable: #{section}" |
| 190 | assert str(releases) not in page, "the selector's message names server paths; it must not reach the page" |
| 191 | |
| 192 | |
| 193 | def test_no_version_is_shown_without_an_active_release(no_release: tuple[TestClient, Path]) -> None: |
| 194 | from musehub.protocol.version import MUSE_VERSION |
| 195 | |
| 196 | r = no_release[0].get(PAGE) |
| 197 | assert r.status_code == 200, "an error page shows no version vacuously" |
| 198 | page = r.text |
| 199 | assert re.search(r"<pre>\s*muse \S", page) is None, "no `muse <version>` sample output" |
| 200 | assert f"muse {MUSE_VERSION}" not in page, "never musehub's own app version (musehub#191)" |
| 201 | |
| 202 | |
| 203 | def test_install_script_still_fails_closed_without_an_active_release(no_release: tuple[TestClient, Path]) -> None: |
| 204 | r = no_release[0].get("/install.sh") |
| 205 | assert r.status_code == 503 |
| 206 | assert "MUSE_VERSION=" not in r.text |
| 207 | |
| 208 | |
| 209 | def test_active_release_shows_its_version_and_no_notice(html: str) -> None: |
| 210 | # The shared fixture pins the pointer to 0.0.0-docs-contract (pages.py). |
| 211 | assert "<pre>muse 0.0.0-docs-contract</pre>" in html |
| 212 | assert _UNAVAILABLE not in html |
| 213 | |
| 214 | |
| 215 | # ── DOC_GS_13: the workflow pushes to the remote for the hub that serves the page (GS-20) ── |
| 216 | # Identity commands follow the request host, so a reader registered on musehub.ai must not be told to |
| 217 | # push to `staging` (staging.musehub.ai, where they hold no identity). |
| 218 | |
| 219 | |
| 220 | def test_init_remote_table_matches_muse_init() -> None: |
| 221 | from muse.cli.commands.init import _DEFAULT_REMOTES |
| 222 | |
| 223 | assert ui_docs._INIT_REMOTES == {urlsplit(url).netloc: (name, url) for name, url in _DEFAULT_REMOTES.items()} |
| 224 | |
| 225 | |
| 226 | @pytest.mark.parametrize(("base_url", "remote"), [ |
| 227 | ("https://musehub.ai", "production"), |
| 228 | ("https://staging.musehub.ai", "staging"), |
| 229 | ("https://localhost:1337", "local"), |
| 230 | ("https://hub.example.org", "hub"), # self-hosted: init wires no remote for it |
| 231 | ]) |
| 232 | def test_push_examples_use_the_remote_for_the_serving_hub(base_url: str, remote: str) -> None: |
| 233 | runnable = [c.line for c in extract_commands(_render_on(base_url)) if c.in_pre] |
| 234 | pushes = [c for c in runnable if c.startswith("muse push ")] |
| 235 | assert pushes and {c.split()[2] for c in pushes} == {remote}, pushes |
| 236 | if remote == "hub": |
| 237 | assert f"muse remote add hub {base_url}/your-handle/my-project" in runnable |
| 238 | assert not [c for c in runnable if c.startswith("muse remote set-url ")] |
| 239 | else: |
| 240 | assert f"muse remote set-url {remote} {base_url}/your-handle/my-project" in runnable |
| 241 | |
| 242 | |
| 243 | # ── DOC_GS_04: the installer description matches the script /install.sh serves ── |
| 244 | |
| 245 | |
| 246 | def test_installer_options_are_the_ones_the_served_script_reads(html: str) -> None: |
| 247 | from musehub.api.routes.musehub import install |
| 248 | |
| 249 | script = install.generate_install_script("https://musehub.ai", "0.0.0-docs-contract") |
| 250 | header = "\n".join(line for line in script.splitlines() if line.startswith("#")) |
| 251 | supported = set(re.findall(r"\bMUSE_[A-Z_]+", header)) |
| 252 | documented = set(re.findall(r"<code>(MUSE_[A-Z_]+)", _section(html, "install"))) |
| 253 | assert documented <= supported, documented - supported |
| 254 | # MUSE_EXTRAS=swift cannot install on any supported Python yet (2026-11-07 QA), so it stays undocumented. |
| 255 | assert supported - documented == {"MUSE_EXTRAS"} |
| 256 | for default in ("$HOME/.local/share/muse/venv", "$HOME/.local/bin"): |
| 257 | assert default in script and default.replace("$HOME", "~") in _section(html, "install") |
| 258 | |
| 259 | |
| 260 | def test_installer_outline_does_not_claim_pypi_is_never_used(html: str) -> None: |
| 261 | # The sdist comes from the hub; its dependencies and build backend come from PyPI unless MUSE_WHEELHOUSE is set. |
| 262 | text = _section(html, "prerequisites") + _section(html, "install") |
| 263 | assert "No PyPI involved" not in text and "not from PyPI" in text and "MUSE_WHEELHOUSE" in text |
| 264 | |
| 265 | |
| 266 | # ── DOC_GS_14: claims corrected by the 2026-11-07 end-to-end QA run (rc20) ── |
| 267 | |
| 268 | |
| 269 | @pytest.mark.parametrize("stale", [ |
| 270 | "curl -I ", # HEAD /healthz is 405 on both hosts |
| 271 | "/releases</code>", # not a version list (profile catch-all) |
| 272 | "see the local dev setup guide", # no such page |
| 273 | "recreates the venv in place", # the venv is reused; muse is reinstalled into it |
| 274 | "always prints a reminder", # printed only after a successful install |
| 275 | "uploading objects", # rc20 push prints no progress lines |
| 276 | "Identity ID: ident_", # register prints sha256:… |
| 277 | "required before pushing", # push signs with the identity for the remote's host |
| 278 | "authenticated via a signed Ed25519 challenge-response", # only registration; requests carry MSign |
| 279 | "exactly as in Git", # diff3-style markers with Muse labels + muse resolve |
| 280 | "will be a drop-in swap", # forward-looking guarantee with no roadmap reference |
| 281 | "cannot be changed after init", # init --force --domain switches it |
| 282 | "produced by the agent holding the matching private key", # agent commits carry the human's key |
| 283 | ]) |
| 284 | def test_corrected_claims_stay_corrected(html: str, stale: str) -> None: |
| 285 | assert stale not in " ".join(html.split()) |
| 286 | |
| 287 | |
| 288 | def test_whoami_explains_the_repository_hub_not_a_default_lookup(html: str) -> None: |
| 289 | sec = _section(html, "identity") |
| 290 | assert "Outside a repository it lists every identity you have stored" in sec |
| 291 | assert "until you run <code>muse hub connect</code>" in sec |
| 292 | |
| 293 | |
| 294 | # ── DOC_GS_15: the first-push figure (V1) is drawn from verified behaviour ── |
| 295 | # Each row was checked against muse 0.2.1rc20 and the 2026-11-07 staging run (#244): register, repo create |
| 296 | # and push are the only steps that reach the hub; every step that signs reads the keychain. |
| 297 | |
| 298 | |
| 299 | def test_first_push_steps_name_real_muse_symbols() -> None: |
| 300 | import importlib |
| 301 | |
| 302 | for step in ui_docs._FIRST_PUSH: |
| 303 | module, symbol = step.implemented_by.split(":") |
| 304 | assert callable(getattr(importlib.import_module(module), symbol)), step.implemented_by |
| 305 | |
| 306 | |
| 307 | def test_first_push_steps_are_documented_commands(html: str) -> None: |
| 308 | import argparse |
| 309 | |
| 310 | from tests.docs_contract import cli_check as cc |
| 311 | |
| 312 | parser: argparse.ArgumentParser = cc.capture_parser() |
| 313 | for step in ui_docs._FIRST_PUSH: |
| 314 | assert cc.check_line(parser, cc.DocCommand(step.command, in_pre=False)).kind == "ok", step.command |
| 315 | assert f'id="{step.anchor}"' in html, step.anchor |
| 316 | |
| 317 | |
| 318 | def test_first_push_figure_matches_the_verified_calls() -> None: |
| 319 | steps = {s.command: s for s in ui_docs._FIRST_PUSH} |
| 320 | assert [c for c, s in steps.items() if s.network] == ["muse auth register", "muse hub repo create", "muse push"] |
| 321 | assert all(s.keychain for s in steps.values() if s.signs), "signing always reads the keychain" |
| 322 | assert not steps["muse hub connect"].network and not steps["muse init"].keychain |
| 323 | |
| 324 | |
| 325 | def test_first_push_figure_renders_as_an_accessible_figure(html: str) -> None: |
| 326 | fig = html.split('id="first-push-figure"', 1)[1].split("</figure>", 1)[0] |
| 327 | assert 'aria-labelledby="first-push-figure-title"' in html and 'id="first-push-figure-title"' in fig |
| 328 | assert fig.count('class="seqfig__step"') == len(ui_docs._FIRST_PUSH) |
| 329 | assert fig.count("seqfig__cell--hub seqfig__cell--idle") == len(ui_docs._FIRST_PUSH) - 3 |
| 330 | assert "<script" not in fig, "complete without JavaScript" |
| 331 | |
| 332 | |
| 333 | # ── DOC_GS_16: the Git bridge section matches the GS-BR-01…13 run (isolated sandbox, rc20, 2026-11-07) ── |
| 334 | |
| 335 | |
| 336 | def test_bridge_examples_do_not_teach_a_signing_flag_that_does_nothing(commands: list[str]) -> None: |
| 337 | imports = [c for c in commands if c.startswith("muse bridge git-import ")] |
| 338 | assert imports and not [c for c in imports if "--sign" in c.split()], imports # muse#139 |
| 339 | |
| 340 | |
| 341 | @pytest.mark.parametrize("stale", [ |
| 342 | "bidirectional Git interoperability layer", # import replays history; export writes one snapshot per run |
| 343 | "keep both in sync indefinitely", # re-importing the mirror duplicates native work |
| 344 | "Author names, emails, and timestamps are preserved verbatim", # names/emails/committer are not stored |
| 345 | "walks a Git repo's DAG and writes equivalent", # merges flattened, intermediate snapshots differ (muse#140) |
| 346 | "Add it to <code>.museignore</code>", # .muse/ is never snapshotted; a plain line breaks the TOML file |
| 347 | "Imported commits are signed only when you pass", # --sign is a no-op (muse#139) |
| 348 | ]) |
| 349 | def test_bridge_claims_corrected_by_the_run_stay_corrected(html: str, stale: str) -> None: |
| 350 | assert stale not in " ".join(html.split()) |
| 351 | |
| 352 | |
| 353 | def test_bridge_status_example_passes_the_git_dir_that_drift_needs(html: str) -> None: |
| 354 | sec = _section(html, "migrate") |
| 355 | assert "muse bridge git-status --git-dir /path/to/git-repo --json" in sec |
| 356 | assert '"drift"' in sec |
| 357 | |
| 358 | |
| 359 | @pytest.mark.parametrize(("issue", "topic"), [(77, "full history"), (139, "--sign"), (140, "single parent"), (141, "untracked")]) |
| 360 | def test_bridge_known_limitations_link_their_tickets(html: str, issue: int, topic: str) -> None: |
| 361 | sec = _section(html, "migrate") |
| 362 | assert f'href="https://staging.musehub.ai/gabriel/muse/issues/{issue}"' in sec and topic in sec |
File History
7 commits
sha256:c2ee54efa85fcbdeea4ffc84a2dd1b8fcd4623463b22e35765df3013a26834aa
merge: #276 public URLs + muse#181 docs onto dev (#313 present)
Opus 5.5
minor
⚠
1 day ago
sha256:c777acd5605d4a83bbf9d2903bff0b0d419325b7bc49317700e4037b56594e8e
fix(web): absolute public URLs come from the canonical publ…
Opus 5.5
minor
⚠
1 day ago
sha256:71e7849472a1545f06b42a349e127eb355fd30953cb39a182a5ae0c5e2da7fb0
docs(getting-started): QA contract v2 audit — no-release pa…
Opus 5.5
minor
⚠
10 days ago
sha256:f7413c1abec6d6a8e5bdabcd4cc7ad5fcd059ce6a6f50f566e2b0118a0a8b578
tests: make tests/docs_contract/ database-free by directory…
Opus 5.5
10 days ago
sha256:0ce2a1580273a4939c58cc0f18ad5ae19a56c6c352b56cfb3ce87fd9283b0f07
Merge task/244-gs17-19 (#244 GS-17/18/19 Getting Started fi…
Opus 5.5
patch
10 days ago
sha256:ec087989520c874c2febaba20b9bcedffe03ff8fcd78e9c0eb92b36d64f2e2a7
docs(getting-started): whoami targets the hub; account for …
Opus 5.5
patch
10 days ago
sha256:5745f056592123707326093fbe1c8fb6430304821fa6edf5263606624fc45883
docs(getting-started): teach a signed, verifiable first-run…
Opus 5.5
minor
⚠
10 days ago