test: keep webui CI hermetic offline

docs/developer-testing-guidelines.md

@@ -66,6 +66,10 @@ modules when present on the branch.
 WEBUI_CI_FORCE=1 ./scripts/ci-webui-check
 ```
 
+`scripts/test-webui` defaults `WEBUI_TEST_OFFLINE=1` so route coverage never
+needs Gitea credentials or MCP daemon credential access. Set
+`WEBUI_TEST_OFFLINE=0` only for explicit operator live-fetch checks.
+
 Wire `scripts/ci-webui-check` into Jenkins (or equivalent) for PRs that touch
 `webui/`, `tests/test_webui_*`, or `docs/webui*`.
 

docs/webui-local-dev.md

@@ -123,6 +123,11 @@ diff touches `webui/`, `tests/test_webui_*`, or web UI docs/scripts):
 WEBUI_CI_FORCE=1 ./scripts/ci-webui-check   # always run
 ```
 
+`scripts/test-webui` sets `WEBUI_TEST_OFFLINE=1` by default. In that mode the
+queue, lease, and runtime routes use empty offline snapshots instead of Gitea
+credentials, so CI can run without MCP daemon credential access. Set
+`WEBUI_TEST_OFFLINE=0` only when deliberately validating live fetch behavior.
+
 Or invoke unittest directly:
 
 ```bash
@@ -149,4 +154,4 @@ no tokens or MCP restart actions are exposed.
 ```bash
 pytest tests/test_webui_skeleton.py tests/test_webui_project_registry.py tests/test_webui_prompt_library.py tests/test_webui_queue_dashboard.py tests/test_webui_audit.py tests/test_webui_worktree_hygiene.py -q
 pytest tests/test_webui_skeleton.py tests/test_webui_project_registry.py tests/test_webui_prompt_library.py tests/test_webui_queue_dashboard.py tests/test_webui_lease_visibility.py tests/test_webui_runtime_health.py -q
-```
+```

scripts/test-webui

@@ -10,4 +10,5 @@ if [[ -x "$repo_root/venv/bin/python" ]]; then
 fi
 
 pattern="${WEBUI_TEST_PATTERN:-test_webui_*.py}"
-exec "$python_bin" -m unittest discover -s tests -p "$pattern" "$@"
+export WEBUI_TEST_OFFLINE="${WEBUI_TEST_OFFLINE:-1}"
+exec "$python_bin" -m unittest discover -s tests -p "$pattern" "$@"

tests/test_webui_ci_gate.py

@@ -4,10 +4,14 @@ import subprocess
 import sys
 import unittest
 from pathlib import Path
+from unittest import mock
 
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 
 from webui.ci_paths import should_run_webui_ci, touches_webui_surface
+from webui.lease_loader import load_lease_snapshot
+from webui.queue_loader import load_queue_snapshot
+from webui.runtime_health import load_runtime_snapshot
 
 _REPO_ROOT = Path(__file__).resolve().parent.parent
 
@@ -50,5 +54,37 @@ class TestCiRunnerScript(unittest.TestCase):
         self.assertEqual(result.returncode, 0, result.stderr or result.stdout)
 
 
+class TestOfflineWebuiCiMode(unittest.TestCase):
+    def test_offline_mode_avoids_live_queue_auth(self):
+        with mock.patch.dict(os.environ, {"WEBUI_TEST_OFFLINE": "1"}):
+            with mock.patch(
+                "webui.queue_loader.get_auth_header",
+                side_effect=AssertionError("live auth should not run"),
+            ):
+                snapshot = load_queue_snapshot()
+        self.assertIsNone(snapshot.fetch_error)
+        self.assertEqual(snapshot.prs, ())
+        self.assertEqual(snapshot.issues, ())
+
+    def test_offline_mode_avoids_live_lease_auth(self):
+        with mock.patch.dict(os.environ, {"WEBUI_TEST_OFFLINE": "1"}):
+            with mock.patch(
+                "webui.lease_loader.get_auth_header",
+                side_effect=AssertionError("live auth should not run"),
+            ):
+                snapshot = load_lease_snapshot()
+        self.assertIsNone(snapshot.fetch_error)
+        self.assertEqual(snapshot.reviewer_leases, ())
+
+    def test_offline_mode_avoids_live_runtime_identity(self):
+        with mock.patch.dict(os.environ, {"WEBUI_TEST_OFFLINE": "1"}):
+            with mock.patch(
+                "webui.runtime_health.get_auth_header",
+                side_effect=AssertionError("live auth should not run"),
+            ):
+                snapshot = load_runtime_snapshot()
+        self.assertEqual(snapshot.identity_error, "offline web UI test mode")
+
+
 if __name__ == "__main__":
-    unittest.main()
+    unittest.main()

tests/test_webui_queue_dashboard.py

@@ -206,8 +206,9 @@ class TestQueueRoutes(unittest.TestCase):
         self.assertEqual(data["pagination"]["issues"]["returned_count"], 3)
 
     def test_queue_fail_closed_without_credentials(self):
-        with mock.patch("webui.queue_loader.get_auth_header", return_value=None):
-            snapshot = load_queue_snapshot()
+        with mock.patch.dict("os.environ", {"WEBUI_TEST_OFFLINE": "0"}):
+            with mock.patch("webui.queue_loader.get_auth_header", return_value=None):
+                snapshot = load_queue_snapshot()
         self.assertIsNotNone(snapshot.fetch_error)
         self.assertEqual(len(snapshot.prs), 0)
 
@@ -285,4 +286,4 @@ class TestQueueFailClosedUx(unittest.TestCase):
 
 
 if __name__ == "__main__":
-    unittest.main()
+    unittest.main()

webui/lease_loader.py

@@ -228,10 +228,29 @@ def load_lease_snapshot(
         )
 
     host = _host_from_url(project.remote_host)
-    pr_fetch = fetch_prs or _fetch_prs
-    issue_fetch = fetch_issues or _fetch_issues
-    comment_fetch = fetch_comments or _fetch_comments
-    using_live = fetch_prs is None or fetch_issues is None
+    offline_test = (os.environ.get("WEBUI_TEST_OFFLINE") or "").strip() in {
+        "1",
+        "true",
+        "yes",
+    }
+
+    def _empty_pr_fetch(*_args, **_kwargs):
+        return [], None
+
+    def _empty_issue_fetch(*_args, **_kwargs):
+        return [], None
+
+    def _empty_comment_fetch(*_args, **_kwargs):
+        return []
+
+    pr_fetch = fetch_prs or (_empty_pr_fetch if offline_test else _fetch_prs)
+    issue_fetch = fetch_issues or (
+        _empty_issue_fetch if offline_test else _fetch_issues
+    )
+    comment_fetch = fetch_comments or (
+        _empty_comment_fetch if offline_test else _fetch_comments
+    )
+    using_live = not offline_test and (fetch_prs is None or fetch_issues is None)
     auth = get_auth_header(host) if using_live else "test-auth"
 
     if using_live and not auth:
@@ -328,4 +347,4 @@ def snapshot_to_dict(snapshot: LeaseSnapshot) -> dict[str, Any]:
         ],
         "collision_history": list(snapshot.collision_history),
         "fetch_error": snapshot.fetch_error,
-    }
+    }

webui/queue_loader.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import os
 import re
 from dataclasses import dataclass
 from datetime import datetime, timezone
@@ -268,9 +269,23 @@ def load_queue_snapshot(
         )
 
     host = _host_from_url(project.remote_host)
-    pr_fetch = fetch_prs or _fetch_prs
-    issue_fetch = fetch_issues or _fetch_issues
-    using_live_fetch = fetch_prs is None or fetch_issues is None
+    offline_test = (os.environ.get("WEBUI_TEST_OFFLINE") or "").strip() in {
+        "1",
+        "true",
+        "yes",
+    }
+
+    def _empty_fetch(*_args, **_kwargs):
+        return [], _pagination_from_pages(
+            per_page=50,
+            pages_fetched=1,
+            returned_count=0,
+            is_final_page=True,
+        )
+
+    pr_fetch = fetch_prs or (_empty_fetch if offline_test else _fetch_prs)
+    issue_fetch = fetch_issues or (_empty_fetch if offline_test else _fetch_issues)
+    using_live_fetch = not offline_test and (fetch_prs is None or fetch_issues is None)
     auth = get_auth_header(host) if using_live_fetch else "test-auth"
     if using_live_fetch and not auth:
         return QueueSnapshot(
@@ -382,4 +397,4 @@ def snapshot_to_dict(snapshot: QueueSnapshot) -> dict[str, Any]:
             "prs": _page(snapshot.pr_pagination),
             "issues": _page(snapshot.issue_pagination),
         },
-    }
+    }

webui/runtime_health.py

@@ -217,6 +217,11 @@ def load_runtime_snapshot(
     repo = _repo_root()
     host = _host_from_url(project.remote_host)
     remote = _remote_name_for_host(host)
+    offline_test = (os.environ.get("WEBUI_TEST_OFFLINE") or "").strip() in {
+        "1",
+        "true",
+        "yes",
+    }
     profile = get_profile()
     allowed = profile.get("allowed_operations") or []
     forbidden = profile.get("forbidden_operations") or []
@@ -247,10 +252,20 @@ def load_runtime_snapshot(
             fetch_error=str(exc),
         )
 
-    identity_fn = resolve_username or _resolve_username
+    identity_fn = resolve_username
+    if identity_fn is None:
+        if offline_test:
+            identity_fn = lambda _host: (None, "offline web UI test mode")
+        else:
+            identity_fn = _resolve_username
     username, identity_error = identity_fn(host)
 
-    git_fn = git_sync or _git_sync_status
+    git_fn = git_sync
+    if git_fn is None:
+        if offline_test:
+            git_fn = lambda _repo, _remote, _branch: (None, None, None)
+        else:
+            git_fn = _git_sync_status
     remote_ref = "prgs" if remote == "prgs" else "origin"
     local_sha, remote_sha, behind = git_fn(repo, remote_ref, project.default_branch)
 
@@ -317,4 +332,4 @@ def snapshot_to_dict(snapshot: RuntimeSnapshot) -> dict[str, Any]:
         "schema_hashes": [_hash_row(item) for item in snapshot.schema_hashes],
         "restart_guidance": snapshot.restart_guidance,
         "fetch_error": snapshot.fetch_error,
-    }
+    }