openclaw-agent-dashboard 1.0.39 → 1.0.40

package/dashboard/tests/test_api_contracts.py

@@ -0,0 +1,372 @@
+"""CA-001 / CA-002 / CA-003：核心 API 与数据校验响应结构契约（轻量回归）。"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+BACKEND = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(BACKEND))
+
+
+def _stub_watcher(monkeypatch):
+    import watchers.file_watcher as fw
+    monkeypatch.setattr(fw, "start_file_watcher", lambda loop: None)
+    monkeypatch.setattr(fw, "stop_file_watcher", lambda: None)
+
+
+@pytest.mark.asyncio
+async def test_contract_health_root(monkeypatch):
+    import httpx
+    _stub_watcher(monkeypatch)
+    from main import app
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as c:
+        r = await c.get("/health")
+        assert r.status_code == 200
+        assert r.json().get("status") == "healthy"
+
+
+@pytest.mark.asyncio
+async def test_contract_api_version_shape(monkeypatch):
+    import httpx
+    _stub_watcher(monkeypatch)
+    from main import app
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as c:
+        r = await c.get("/api/version")
+        assert r.status_code == 200
+        body = r.json()
+        assert "version" in body and "name" in body and "description" in body
+
+
+@pytest.mark.asyncio
+async def test_contract_cache_stats_fortify_keys(monkeypatch):
+    import httpx
+    _stub_watcher(monkeypatch)
+    from main import app
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as c:
+        r = await c.get("/api/cache/stats")
+        assert r.status_code == 200
+        j = r.json()
+        for k in ("hit_rate", "ttl_seconds", "stats", "cache_double_check", "fp_probe_interval_sec"):
+            assert k in j, f"missing {k}"
+        assert "hits" in j["stats"]
+
+
+@pytest.mark.asyncio
+async def test_contract_errors_stats_has_framework(monkeypatch):
+    import httpx
+    _stub_watcher(monkeypatch)
+    from main import app
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as c:
+        r = await c.get("/api/errors/stats")
+        assert r.status_code == 200
+        j = r.json()
+        assert "framework" in j
+        fw = j["framework"]
+        assert "total_count" in fw
+        assert "retry_budget_blocks" in fw
+
+
+@pytest.mark.asyncio
+async def test_contract_agents_list_is_array(monkeypatch):
+    import httpx
+    _stub_watcher(monkeypatch)
+    from main import app
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as c:
+        r = await c.get("/api/agents")
+        assert r.status_code == 200
+        data = r.json()
+        assert isinstance(data, list)
+        if data:
+            row = data[0]
+            for k in ("id", "status", "name"):
+                assert k in row
+
+
+@pytest.mark.asyncio
+async def test_contract_health_watcher_shape(monkeypatch):
+    import httpx
+    _stub_watcher(monkeypatch)
+    from main import app
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as c:
+        r = await c.get("/api/health/watcher")
+        assert r.status_code == 200
+        j = r.json()
+        for k in (
+            "status",
+            "mode",
+            "error_count",
+            "switch_count",
+            "resume_watchdog_success_count",
+            "resume_watchdog_failure_count",
+            "uptime_seconds",
+            "poll_interval_sec",
+            "persisted_snapshot",
+        ):
+            assert k in j, f"missing {k}"
+
+
+@pytest.mark.asyncio
+async def test_contract_api_config_has_main_agent_id(monkeypatch):
+    import httpx
+    _stub_watcher(monkeypatch)
+    from main import app
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as c:
+        r = await c.get("/api/config")
+        assert r.status_code == 200
+        j = r.json()
+        assert "mainAgentId" in j
+        assert isinstance(j["mainAgentId"], str)
+        assert j["mainAgentId"]
+
+
+@pytest.mark.asyncio
+async def test_contract_data_validate_report_shape(monkeypatch, tmp_path):
+    """CA-003：GET /api/data/validate 稳定字段（与 session_reader 报告结构对齐）。"""
+    import httpx
+    import data.session_reader as session_reader
+    monkeypatch.setattr(session_reader, "get_openclaw_root", lambda: tmp_path)
+    _stub_watcher(monkeypatch)
+    from main import app
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as c:
+        r = await c.get("/api/data/validate", params={"agent_id": "main"})
+        assert r.status_code == 200
+        j = r.json()
+        for k in (
+            "agent_id",
+            "validation_passed",
+            "sessions_index_path",
+            "session_file",
+            "session_file_query",
+            "file_integrity",
+            "read_path_policy",
+            "total_lines",
+            "valid_messages",
+            "repaired_messages",
+            "errors",
+            "repair_report",
+        ):
+            assert k in j, f"missing {k}"
+        rp = j["repair_report"]
+        assert "repaired_count" in rp and "repair_success_rate" in rp and "failed_repairs" in rp
+        assert isinstance(j["errors"], list)
+        assert isinstance(rp["failed_repairs"], list)
+        pol = j["read_path_policy"]
+        assert "memory_auto_repair_default" in pol and "disk_write_back_enabled" in pol
+
+
+# ---------------------------------------------------------------------------
+# CA-001 / CA-002：timeline / chains 响应结构契约
+# ---------------------------------------------------------------------------
+
+def _stub_root(monkeypatch, tmp_path):
+    """隔离 openclaw_root，避免依赖真实数据目录。"""
+    _stub_watcher(monkeypatch)
+    import data.session_reader as sr
+    import api.timeline as tl
+    monkeypatch.setattr(sr, "get_openclaw_root", lambda: tmp_path)
+    monkeypatch.setattr(tl, "get_agent_config", lambda agent_id: {"id": agent_id, "name": agent_id, "model": "test-model"})
+
+
+@pytest.mark.asyncio
+async def test_contract_timeline_shape(monkeypatch, tmp_path):
+    """CA-002：GET /timeline/{agent_id} 稳定字段（agentId / steps / stats / model / agentName）。"""
+    import httpx
+    _stub_root(monkeypatch, tmp_path)
+    from main import app
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as c:
+        r = await c.get("/api/timeline/main")
+        assert r.status_code == 200
+        j = r.json()
+        for k in ("agentId", "status", "steps", "stats"):
+            assert k in j, f"missing {k}"
+        stats = j["stats"]
+        for k in ("totalDuration", "totalInputTokens", "totalOutputTokens", "toolCallCount", "stepCount"):
+            assert k in stats, f"missing stats.{k}"
+        assert isinstance(j["steps"], list)
+        assert isinstance(j["agentId"], str)
+
+
+@pytest.mark.asyncio
+async def test_contract_timeline_steps_shape(monkeypatch, tmp_path):
+    """CA-002：GET /timeline/{agent_id}/steps 返回 {steps, count}。"""
+    import httpx
+    _stub_root(monkeypatch, tmp_path)
+    from main import app
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as c:
+        r = await c.get("/api/timeline/main/steps")
+        assert r.status_code == 200
+        j = r.json()
+        assert "steps" in j
+        assert "count" in j
+        assert j["count"] == len(j["steps"])
+        assert isinstance(j["steps"], list)
+
+
+@pytest.mark.asyncio
+async def test_contract_chains_list_shape(monkeypatch, tmp_path):
+    """CA-002：GET /chains 返回 {chains, activeChain}。"""
+    import httpx
+    _stub_root(monkeypatch, tmp_path)
+    from main import app
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as c:
+        r = await c.get("/api/chains")
+        assert r.status_code == 200
+        j = r.json()
+        assert "chains" in j
+        assert "activeChain" in j
+        assert isinstance(j["chains"], list)
+        assert j["activeChain"] is None or isinstance(j["activeChain"], dict)
+
+
+@pytest.mark.asyncio
+async def test_contract_chains_summary_shape(monkeypatch, tmp_path):
+    """CA-002：GET /chains/summary 返回 {total, running, completed, error, chains}。"""
+    import httpx
+    _stub_root(monkeypatch, tmp_path)
+    from main import app
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as c:
+        r = await c.get("/api/chains/summary")
+        assert r.status_code == 200
+        j = r.json()
+        for k in ("total", "running", "completed", "error", "chains"):
+            assert k in j, f"missing {k}"
+        assert isinstance(j["total"], int)
+        assert isinstance(j["chains"], list)
+
+
+@pytest.mark.asyncio
+async def test_contract_chains_active_shape(monkeypatch, tmp_path):
+    """CA-002：GET /chains/active 返回 {activeChain} 或含 message。"""
+    import httpx
+    _stub_root(monkeypatch, tmp_path)
+    from main import app
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as c:
+        r = await c.get("/api/chains/active")
+        assert r.status_code == 200
+        j = r.json()
+        assert "activeChain" in j
+        if j["activeChain"] is None:
+            assert "message" in j
+
+
+# ---------------------------------------------------------------------------
+# CA-003：数据校验 fixture 驱动测试
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_contract_data_validate_with_fixture(monkeypatch, fake_openclaw_root):
+    """CA-003：GET /api/data/validate 用真实 fixture 验证 sessions.json + JSONL 解析。"""
+    import httpx
+    import data.session_reader as sr
+    import api.timeline as tl
+
+    monkeypatch.setattr(sr, "get_openclaw_root", lambda: fake_openclaw_root)
+    monkeypatch.setattr(tl, "get_agent_config", lambda agent_id: {"id": agent_id, "name": agent_id, "model": "test-model"})
+    _stub_watcher(monkeypatch)
+    from main import app
+
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as c:
+        r = await c.get("/api/data/validate", params={"agent_id": "main"})
+        assert r.status_code == 200, r.text
+        j = r.json()
+        # sessions_index 被找到
+        assert j["sessions_index_path"] is not None
+        # JSONL 行被解析（valid_messages = lines with type=message）
+        assert j["total_lines"] >= 3
+        assert j["valid_messages"] >= 1
+        assert "file_integrity" in j
+
+
+@pytest.mark.asyncio
+async def test_contract_data_validate_session_file_param(monkeypatch, fake_openclaw_root):
+    """CA-003：GET /api/data/validate 支持 session_file query 参数（无 agent_id 时走默认）。"""
+    import httpx
+    import data.session_reader as sr
+    import api.timeline as tl
+
+    monkeypatch.setattr(sr, "get_openclaw_root", lambda: fake_openclaw_root)
+    monkeypatch.setattr(tl, "get_agent_config", lambda agent_id: {"id": agent_id, "name": agent_id, "model": "test-model"})
+    _stub_watcher(monkeypatch)
+    from main import app
+
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as c:
+        r = await c.get("/api/data/validate", params={"agent_id": "main", "max_lines": 5})
+        assert r.status_code == 200
+        j = r.json()
+        assert "validation_passed" in j
+        assert "repair_report" in j
+
+
+# ---------------------------------------------------------------------------
+# CA-002 扩展：agents / cache / errors 更多字段断言
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_contract_agents_list_item_extended_fields(monkeypatch):
+    """CA-002：GET /api/agents 列表项含 status / name / role。"""
+    import httpx
+    _stub_watcher(monkeypatch)
+    from main import app
+
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as c:
+        r = await c.get("/api/agents")
+        assert r.status_code == 200
+        data = r.json()
+        assert isinstance(data, list)
+        if data:
+            row = data[0]
+            for k in ("id", "status", "name", "role"):
+                assert k in row, f"missing field: {k}"
+
+
+@pytest.mark.asyncio
+async def test_contract_cache_stats_stats_fields(monkeypatch):
+    """CA-002：GET /api/cache/stats.stats 含 hits / misses / fp_invalidations / stale_fallback_reads。"""
+    import httpx
+    _stub_watcher(monkeypatch)
+    from main import app
+
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as c:
+        r = await c.get("/api/cache/stats")
+        assert r.status_code == 200
+        stats = r.json()["stats"]
+        for k in ("hits", "misses", "fp_invalidations", "stale_fallback_reads"):
+            assert k in stats, f"missing stats.{k}"
+            assert isinstance(stats[k], int)
+
+
+@pytest.mark.asyncio
+async def test_contract_errors_stats_by_type_fields(monkeypatch):
+    """CA-002：GET /api/errors/stats.framework 含 by_type / by_scope_top / retry_budget_blocks。"""
+    import httpx
+    _stub_watcher(monkeypatch)
+    from main import app
+
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as c:
+        r = await c.get("/api/errors/stats")
+        assert r.status_code == 200
+        fw = r.json()["framework"]
+        assert "by_type" in fw
+        assert "by_scope_top" in fw
+        assert "retry_budget_blocks" in fw
+        assert isinstance(fw["by_type"], dict)
+        assert isinstance(fw["by_scope_top"], list)
+
+
+@pytest.mark.asyncio
+async def test_contract_watcher_poll_ticks_counter(monkeypatch):
+    """CA-002：GET /api/health/watcher 含 persisted_snapshot（内含 poll_ticks_counter）。"""
+    import httpx
+    _stub_watcher(monkeypatch)
+    from main import app
+
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as c:
+        r = await c.get("/api/health/watcher")
+        assert r.status_code == 200
+        snap = r.json().get("persisted_snapshot")
+        if snap:
+            assert "poll_ticks_counter" in snap, "persisted_snapshot should contain poll_ticks_counter"

package/dashboard/tests/test_bench_fortify.py

@@ -0,0 +1,176 @@
+"""轻量探针：§3 NFR-P 相关（非严格 SLA，慢机可能波动；CI 可用 -m benchmark 筛选）。"""
+from __future__ import annotations
+
+import json
+import sys
+import time
+from pathlib import Path
+
+import pytest
+
+BACKEND = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(BACKEND))
+
+pytestmark = pytest.mark.benchmark
+
+
+def _stub_watcher(monkeypatch):
+    import watchers.file_watcher as fw
+    monkeypatch.setattr(fw, "start_file_watcher", lambda loop: None)
+    monkeypatch.setattr(fw, "stop_file_watcher", lambda: None)
+
+
+def test_nfr_p003_record_error_overhead(monkeypatch):
+    """PA-003：record_error 单次调用平均开销 <10ms（NFR-P-003）。"""
+    from core.error_handler import record_error
+    record_error("unknown", "warmup", "bench:warmup")
+    n = 40
+    t0 = time.perf_counter()
+    for i in range(n):
+        record_error("validation-error", f"e{i}", "bench:loop")
+    elapsed_ms = (time.perf_counter() - t0) * 1000
+    per_ms = elapsed_ms / n
+    assert per_ms < 10.0, f"mean record_error {per_ms:.3f}ms (target <10ms)"
+
+
+def test_nfr_p004_parse_large_message_line():
+    from utils.data_repair import parse_session_jsonl_line
+
+    inner = {"role": "user", "content": [{"type": "text", "text": "x" * 40_000}]}
+    line = json.dumps({"type": "message", "message": inner}, ensure_ascii=False)
+    t0 = time.perf_counter()
+    env, msg = parse_session_jsonl_line(line, json_strict=True, auto_repair=False)
+    elapsed_ms = (time.perf_counter() - t0) * 1000
+    assert env is not None and msg is not None
+    assert elapsed_ms < 800.0, f"parse took {elapsed_ms:.1f}ms"
+
+
+@pytest.mark.asyncio
+async def test_nfr_p005_api_response_health(monkeypatch):
+    """PA-005：GET /health 端到端 <200ms。"""
+    import httpx
+    _stub_watcher(monkeypatch)
+    from main import app
+
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as c:
+        t0 = time.perf_counter()
+        r = await c.get("/health")
+        elapsed_ms = (time.perf_counter() - t0) * 1000
+        assert r.status_code == 200
+        assert elapsed_ms < 200.0, f"/health took {elapsed_ms:.1f}ms"
+
+
+@pytest.mark.asyncio
+async def test_nfr_p005_api_response_version(monkeypatch):
+    """PA-005：GET /api/version 端到端 <200ms。"""
+    import httpx
+    _stub_watcher(monkeypatch)
+    from main import app
+
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as c:
+        t0 = time.perf_counter()
+        r = await c.get("/api/version")
+        elapsed_ms = (time.perf_counter() - t0) * 1000
+        assert r.status_code == 200
+        assert elapsed_ms < 200.0, f"/api/version took {elapsed_ms:.1f}ms"
+
+
+@pytest.mark.asyncio
+async def test_nfr_p005_api_response_cache_stats(monkeypatch):
+    """PA-005：GET /api/cache/stats 端到端 <200ms。"""
+    import httpx
+    _stub_watcher(monkeypatch)
+    from main import app
+
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as c:
+        t0 = time.perf_counter()
+        r = await c.get("/api/cache/stats")
+        elapsed_ms = (time.perf_counter() - t0) * 1000
+        assert r.status_code == 200
+        assert elapsed_ms < 200.0, f"/api/cache/stats took {elapsed_ms:.1f}ms"
+
+
+@pytest.mark.asyncio
+async def test_nfr_p005_api_response_errors_stats(monkeypatch):
+    """PA-005：GET /api/errors/stats 端到端 <200ms。"""
+    import httpx
+    _stub_watcher(monkeypatch)
+    from main import app
+
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as c:
+        t0 = time.perf_counter()
+        r = await c.get("/api/errors/stats")
+        elapsed_ms = (time.perf_counter() - t0) * 1000
+        assert r.status_code == 200
+        assert elapsed_ms < 200.0, f"/api/errors/stats took {elapsed_ms:.1f}ms"
+
+
+def test_nfr_p001_resume_watchdog_full_resync(monkeypatch, tmp_path):
+    """PA-001 / NFR-P-001：轮询恢复 watchdog 时的全量同步 <1s。测 _full_resync_cache_and_push 耗时。"""
+    import threading
+    import watchers.file_watcher as fw
+    import data.session_reader as sr
+    monkeypatch.setattr(sr, "get_openclaw_root", lambda: tmp_path)
+    monkeypatch.setattr(fw, "_watcher_mode", "polling")
+    monkeypatch.setattr(fw, "_monitor_stop", threading.Event())
+    fake_calls = []
+    def fake_on_file_changed(_):
+        fake_calls.append(1)
+    monkeypatch.setattr(fw, "_on_file_changed", fake_on_file_changed)
+    monkeypatch.setattr(fw, "_persist_watcher_state", lambda: None)
+
+    t0 = time.perf_counter()
+    fw._full_resync_cache_and_push()
+    elapsed_ms = (time.perf_counter() - t0) * 1000
+    assert len(fake_calls) == 1, "full resync should trigger one _on_file_changed"
+    assert elapsed_ms < 1000.0, f"_full_resync_cache_and_push took {elapsed_ms:.1f}ms (target <1000ms)"
+
+
+def test_nfr_p001_switch_to_polling(monkeypatch, tmp_path):
+    """PA-001 / NFR-P-001：watchdog 切换到 polling 模式 <1s。测 _switch_to_polling 耗时。"""
+    import threading
+    import asyncio
+    import watchers.file_watcher as fw
+    import data.session_reader as sr
+    monkeypatch.setattr(sr, "get_openclaw_root", lambda: tmp_path)
+    # start in watchdog mode with a stub observer
+    monkeypatch.setattr(fw, "_watcher_mode", "watchdog")
+    monkeypatch.setattr(fw, "_observer", None)  # no real observer
+    monkeypatch.setattr(fw, "_stop_watchdog_observer", lambda: None)
+    monkeypatch.setattr(fw, "_start_polling_mode", lambda loop: None)
+    monkeypatch.setattr(fw, "_persist_watcher_state", lambda: None)
+
+    fake_loop = asyncio.new_event_loop()
+    t0 = time.perf_counter()
+    fw._switch_to_polling(fake_loop)
+    elapsed_ms = (time.perf_counter() - t0) * 1000
+    assert elapsed_ms < 1000.0, f"_switch_to_polling took {elapsed_ms:.1f}ms (target <1000ms)"
+    fake_loop.close()
+
+
+def test_nfr_p002_cache_hit_rate(monkeypatch, tmp_path):
+    """PA-002 / NFR-P-002：缓存命中率 ≥60%。通过 StatusCache 直接验证。"""
+    import data.session_reader as sr
+    monkeypatch.setattr(sr, "get_openclaw_root", lambda: tmp_path)
+    from status.status_cache import StatusCache
+
+    cache = StatusCache(ttl_ms=60_000)
+    cache.get("agent-x")  # cold miss
+    cache.get("agent-y")  # cold miss
+    cache.set("agent-a", {"status": "running"})
+    cache.get("agent-a")  # warm hit
+    cache.get("agent-a")  # warm hit
+    cache.get("agent-a")  # warm hit
+    cache.get("agent-a")  # warm hit
+    cache.get("agent-b")  # cold miss
+    cache.set("agent-b", {"status": "idle"})
+    cache.get("agent-b")  # warm hit
+    cache.get("agent-b")  # warm hit
+    # 5 hits / (5+3) = 5/8 = 62.5% >= 60%
+
+    stats = cache.get_stats()
+    total = stats["stats"]["hits"] + stats["stats"]["misses"]
+    hit_rate = (stats["stats"]["hits"] / total) if total else 0.0
+    assert hit_rate >= 0.60, f"hit_rate {hit_rate:.2%} < 60% (hits={stats['stats']['hits']}, misses={stats['stats']['misses']})"
+
+