test(ci): exercise browser and release contracts with pytest

.github/workflows/release.yml

@@ -40,27 +40,17 @@ jobs:
           echo "candidate=$release_version-candidate-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT" >> "$GITHUB_OUTPUT"
           echo "PUBLIC_RELEASE_VERSION=$release_version" >> "$GITHUB_ENV"
 
-      - name: Install contract dependency
-        run: python -m pip install PyYAML==6.0.3
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install contract dependencies
+        run: uv sync --locked --extra dev
 
       - name: Verify public release contract
         shell: bash
         run: |
-          python - <<'PY'
-          import runpy
-
-          namespace = runpy.run_path("tests/unit/test_public_release_contract.py")
-          tests = sorted(
-              (name, value)
-              for name, value in namespace.items()
-              if name.startswith("test_") and callable(value)
-          )
-          if not tests:
-              raise SystemExit("No public release contract tests were discovered.")
-          for name, contract_test in tests:
-              contract_test()
-              print(f"passed: {name}")
-          PY
+          # Keep this gate independent of application fixtures and coverage.
+          uv run --locked --extra dev pytest tests/unit/test_public_release_contract.py --noconftest --no-cov -q
 
   images:
     name: ${{ matrix.name }}

README.md

@@ -106,7 +106,7 @@ IMAGE_TAG=source docker compose -f docker-compose.yml -f docker-compose.build.ym
 
 ## 浏览器引擎与 CloakBrowser
 
-内置浏览器默认使用 Chromium。需要切换到 CloakBrowser 时，先在未提交的 .env 中设置构建和运行配置；BROWSER_ENGINE 必须与镜像构建时的变体一致：
+内置浏览器在未设置 `BROWSER_ENGINE` 时默认使用 `chromium`；显式空值或不支持的引擎值会报错退出，不会回退。Agent 保留对已安装 Chromium 的自动检测，也识别镜像内置运行时标记 `AGENT_HAS_CHROME=true`，不只依赖系统 `chromium` 命令来判断是否启动内置浏览器。需要切换到 CloakBrowser 时，先在未提交的 .env 中设置构建和运行配置；BROWSER_ENGINE 必须与镜像构建时的变体一致：
 
 ~~~bash
 BROWSER_ENGINE=cloakbrowser

TESTING.md

@@ -559,3 +559,19 @@ Edge 见下方"多浏览器"小节。
    `TaskRunEvent` 行对测试自己的查询可见（conftest 里那个 per-test 内存 `db_session` 是**另一个**库，
    环路不会写它）。需要事后翻库时，可改设 `DATABASE_URL` 指向一个一次性文件库。`playwright install
    chromium` 是每台机器一次性的准备步骤。
+
+## Release Contract 本地复现
+
+在仓库根目录使用 Python 3.13、uv 和原生 Bash（需可调用 `openssl`），执行与
+`.github/workflows/release.yml` 相同的发布契约检查：
+
+```bash
+uv sync --locked --extra dev
+uv run --locked --extra dev pytest tests/unit/test_public_release_contract.py --noconftest --no-cov -q
+```
+
+依赖统一来自项目的锁文件及 `dev` extra，避免在发布工作流维护另一份版本固定列表。
+`--noconftest` 隔离应用级 `tests/conftest.py`，不禁用 pytest 内置的 `tmp_path`
+fixture 或参数化用例；`--no-cov` 仅为此定向发布门禁关闭无关的全应用覆盖率阈值。
+应运行该文件的全部契约用例且无跳过，包括真实密码初始化成功和失败的路径。
+测试替代了 Docker 调用，不代表已验证镜像构建、容器部署或标签发布。

tests/unit/test_browser_executable.py

@@ -1,8 +1,12 @@
+import json
 import os
-import re
+import shlex
+import shutil
 import subprocess
 from pathlib import Path
 
+import pytest
+
 ROOT = Path(__file__).parents[2]
 
 
@@ -22,6 +26,7 @@ def run_resolver(
         env=env,
         capture_output=True,
         text=True,
+        timeout=30,
     )
 
 
@@ -43,9 +48,7 @@ def test_resolver_uses_existing_cloak_binary(tmp_path):
 def test_resolver_rejects_cloak_directory(tmp_path):
     binary_directory = tmp_path / "cloak"
     binary_directory.mkdir()
-    result = run_resolver(
-        "cloakbrowser", {"CLOAKBROWSER_BINARY_PATH": str(binary_directory)}
-    )
+    result = run_resolver("cloakbrowser", {"CLOAKBROWSER_BINARY_PATH": str(binary_directory)})
     assert result.returncode != 0
     assert result.stdout == ""
 
@@ -56,7 +59,6 @@ def test_resolver_rejects_unknown_engine():
     assert "webkit" in result.stderr
 
 
-
 def test_resolver_rejects_empty_environment_engine():
     result = run_resolver(None, {"BROWSER_ENGINE": ""})
     assert result.returncode != 0
@@ -78,52 +80,156 @@ def test_resolver_does_not_fallback_when_override_missing(tmp_path):
     assert "fallback" not in result.stderr.lower()
 
 
-def _read_entrypoint(name: str) -> str:
-    return (ROOT / name / "entrypoint.sh").read_text(encoding="utf-8")
-
+def bash_executable() -> str:
+    git = shutil.which("git")
+    candidates = [
+        Path(git).parent / "bash.exe" if git else None,
+        Path(git).parent.parent / "bin" / "bash.exe" if git else None,
+        Path(r"C:\Program Files\Git\bin\bash.exe"),
+        Path(r"C:\Program Files\Git\usr\bin\bash.exe"),
+    ]
+    if os.name != "nt":
+        candidates.append(Path(shutil.which("bash") or "/bin/bash"))
+    for candidate in candidates:
+        if candidate and candidate.is_file():
+            return str(candidate)
+    pytest.skip("A native Bash executable is unavailable.")
+
+
+def run_entrypoint(
+    tmp_path: Path,
+    name: str,
+    engine: str | None,
+    *,
+    image_has_chrome: bool = False,
+    stock_chromium: bool = False,
+) -> tuple[subprocess.CompletedProcess[str], list[str]]:
+    """Run the complete startup script with real Node resolvers, not real services."""
+    bash = bash_executable()
+    node = shutil.which("node")
+    assert node is not None, "Node is required by the browser entrypoints"
+    for directory in ("bin", "etc/nginx/conf.d", "tmp", "home", "usr/local/bin", "opt"):
+        (tmp_path / directory).mkdir(parents=True, exist_ok=True)
+    (tmp_path / "etc/nginx/conf.d/cdp.conf.template").write_text("")
+    (tmp_path / "etc/browser-bridge-extension-id").write_text("")
+    manifest = tmp_path / "opt/manifest.json"
+    manifest.write_text(json.dumps({"name": "test", "version": "1", "components": []}))
+    for resolver in (
+        "resolve-browser-executable.mjs",
+        "resolve-browser-runtime-bundle.mjs",
+    ):
+        shutil.copyfile(ROOT / "scripts" / resolver, tmp_path / "usr/local/bin" / resolver)
+
+    # Only filesystem locations change; all production branching remains intact.
+    source = (ROOT / name / "entrypoint.sh").read_text(encoding="utf-8")
+    source = source.replace("/tmp/", f"{tmp_path.as_posix()}/tmp/")
+    for prefix in ("/etc/", "/home/", "/usr/local/bin/", "/usr/share/", "/opt/"):
+        source = source.replace(prefix, f"{tmp_path.as_posix()}{prefix}")
+    entrypoint = tmp_path / "entrypoint.sh"
+    entrypoint.write_text(source, encoding="utf-8", newline="\n")
+    events = tmp_path / "events"
+    for executable, event in (
+        ("chromium-double", "chromium"),
+        ("cloak-double", "cloak"),
+        ("uvicorn", "server"),
+    ):
+        binary = tmp_path / "bin" / executable
+        binary.write_text(
+            f'#!/bin/bash\nprintf \'{event} %s\\n\' "$*" >> "$STARTUP_EVENTS"\n',
+            encoding="utf-8",
+            newline="\n",
+        )
+        binary.chmod(0o755)
 
-def _start_chrome_body(entrypoint: str) -> str:
-    match = re.search(
-        r"start_chrome\(\)\s*\{(?P<body>.*?)\n[ \t]*\}", entrypoint, re.DOTALL
+    env = os.environ.copy()
+    for key in tuple(env):
+        if key.startswith(("BROWSER_", "CHROMIUM_", "CLOAKBROWSER_", "AGENT_HAS_CHROME")):
+            env.pop(key)
+    env.update(
+        {
+            "NODE_BIN": Path(node).as_posix(),
+            "STARTUP_EVENTS": events.as_posix(),
+            "SANDBOX_BIN": (tmp_path / "bin").as_posix(),
+            "BROWSER_RUNTIME_BUNDLE_ROOT": (tmp_path / "opt").as_posix(),
+            "BROWSER_RUNTIME_BUNDLE_MANIFEST": manifest.as_posix(),
+            "CHROMIUM_BINARY": (tmp_path / "bin/chromium-double").as_posix(),
+            "CLOAKBROWSER_BINARY_PATH": (tmp_path / "bin/cloak-double").as_posix(),
+            "AGENT_HAS_CHROME": str(image_has_chrome).lower(),
+            "OPENCLI_BROWSER_PROFILE_KIND": "authenticated",
+            "CLOAKBROWSER_LICENSE_KEY": "startup-test-private-license",
+        }
     )
-    assert match is not None
-    return match.group("body")
-
-
-def test_entrypoints_resolve_browser_engine_with_shared_resolver():
-    for name in ("chrome", "agent"):
-        entrypoint = _read_entrypoint(name)
-        assert 'BROWSER_ENGINE="${BROWSER_ENGINE-chromium}"' in entrypoint
-        assert 'BROWSER_ENGINE="${BROWSER_ENGINE:-chromium}"' not in entrypoint
-        assert (
-            'CHROME_BIN="$(node /usr/local/bin/resolve-browser-executable.mjs '
-            '"$BROWSER_ENGINE")" || {'
-        ) in entrypoint
-
-
-def test_agent_resolver_is_gated_by_embedded_chrome_flag():
-    entrypoint = _read_entrypoint("agent")
-    assert (
-        'if [ "${AGENT_HAS_CHROME:-false}" = "true" ]; then HAVE_CHROME=true; fi'
-        in entrypoint
+    if engine is not None:
+        env["BROWSER_ENGINE"] = engine
+    script = r"""
+# A private PATH makes stock Chromium detection independent of the test host.
+export PATH="$(cd "$SANDBOX_BIN" && pwd)"
+node() { "$NODE_BIN" "$@"; }
+Xvfb() { :; }
+nginx() { :; }
+x11vnc() { :; }
+websockify() { :; }
+envsubst() { :; }
+rm() { :; }
+find() { :; }
+xargs() { :; }
+tr() { :; }
+npm() { printf '%s\n' "$SANDBOX_BIN"; }
+seq() { printf '1\n'; }
+curl() { return 1; }
+# End daemon/browser restart loops after their first invocation.
+bbx-daemon() { exit 0; }
+sleep() { if [ "$1" = 2 ]; then exit 0; fi; }
+"""
+    if stock_chromium:
+        script += "\nchromium() { :; }\n"
+    script += f"\nsource {shlex.quote(entrypoint.as_posix())}\n"
+    result = subprocess.run(
+        [bash, "-c", script],
+        cwd=ROOT,
+        env=env,
+        text=True,
+        encoding="utf-8",
+        capture_output=True,
+        timeout=30,
+        check=False,
     )
-    embedded_branch = entrypoint.index('if [ "$HAVE_CHROME" = "true" ]; then')
-    resolver_call = entrypoint.index(
-        "node /usr/local/bin/resolve-browser-executable.mjs", embedded_branch
+    return result, events.read_text().splitlines() if events.exists() else []
+
+
+@pytest.mark.parametrize("name", ["chrome", "agent"])
+def test_entrypoints_reject_explicit_empty_engine(tmp_path, name):
+    result, events = run_entrypoint(tmp_path, name, "", stock_chromium=True)
+    assert result.returncode != 0
+    assert "unsupported browser engine" in result.stderr
+    assert events == []
+
+
+@pytest.mark.parametrize("name", ["chrome", "agent"])
+def test_entrypoints_default_unset_engine_to_chromium(tmp_path, name):
+    result, events = run_entrypoint(tmp_path, name, None, stock_chromium=True)
+    assert result.returncode == 0, result.stderr
+    assert any(
+        event.startswith("chromium ") and "--remote-debugging-port=9222" in event
+        for event in events
     )
-    host_branch = entrypoint.index("\nelse\n", embedded_branch)
-    assert embedded_branch < resolver_call < host_branch
+    assert "startup-test-private-license" not in result.stdout + result.stderr
 
 
-def test_entrypoints_start_chrome_with_resolved_binary_and_cdp_port():
-    for name in ("chrome", "agent"):
-        body = _start_chrome_body(_read_entrypoint(name))
-        assert '"$CHROME_BIN" --remote-debugging-port=9222' in body
-        assert not re.search(r"^\s*chromium(?:\s|$)", body, re.MULTILINE)
+def test_agent_image_marker_starts_cloak_without_stock_chromium(tmp_path):
+    result, events = run_entrypoint(tmp_path, "agent", "cloakbrowser", image_has_chrome=True)
+    assert result.returncode == 0, result.stderr
+    assert any(
+        event.startswith("cloak ") and "--remote-debugging-port=9222" in event for event in events
+    )
+    assert any(event.startswith("server ") for event in events)
+    assert "startup-test-private-license" not in result.stdout + result.stderr
 
 
-def test_entrypoints_do_not_interpolate_license_key_in_logs():
-    for name in ("chrome", "agent"):
-        for line in _read_entrypoint(name).splitlines():
-            if re.search(r"\b(?:echo|printf)\b", line):
-                assert "CLOAKBROWSER_LICENSE_KEY" not in line
+def test_agent_host_mode_does_not_resolve_browser_engine(tmp_path):
+    # An invalid engine would abort startup if host mode called the resolver.
+    result, events = run_entrypoint(tmp_path, "agent", "")
+    assert result.returncode == 0, result.stderr
+    assert len(events) == 1
+    assert events[0].startswith("server ")
+    assert "unsupported browser engine" not in result.stderr