全站测试体系设计（2026-06-08）

背景与目标

Nexus 6.0 已有 ~60 个 pytest 模块、tests/test_api.py 门控脚本、frontend/e2e/full-acceptance.spec.mjs（15 条 UI 冒烟）、scripts/run_nexus_acceptance.py 统一验收入口。缺口在于：

单元测试按功能域未全覆盖，前端几乎无单测
集成测试以手写 urllib 为主，缺契约快照与 DB 夹具规范
链条测试（多 API / 多页面 / WS / 后台任务）用例未系统化
Agent MCP 浏览器点页有 Playwright MCP，但未沉淀为可重复用例清单

目标：建立四层测试金字塔 + Agent MCP 探索层，全部有编号用例、可 CI、可 run_nexus_acceptance.py 汇总。

方案对比

方案	优点	缺点	结论
A. 仅扩 pytest	与现门控一致	无真实 UI 交互	作为 L1–L3 底座
B. 仅 Playwright	贴近用户	慢、脆、难测纯逻辑	作为 L4
C. MCP 临时点页	Agent 灵活	不可 CI、难回归	作为 L5 探索 + 用例沉淀到 B
D. 四层 + MCP 规程（选定）	分工清晰、可渐进	初期文档/用例工作量大	✅

选定架构

                    ┌─────────────────────┐
                    │ L5 Agent MCP 探索   │  新功能/回归抽测 → 沉淀为 L4
                    └──────────┬──────────┘
                    ┌──────────▼──────────┐
                    │ L4 UI E2E (Playwright)│  frontend/e2e/*.spec.mjs
                    └──────────┬──────────┘
                    ┌──────────▼──────────┐
                    │ L3 链条 (Chain)     │  tests/chain/ + pytest markers
                    └──────────┬──────────┘
                    ┌──────────▼──────────┐
                    │ L2 集成 (API+DB)    │  tests/integration/ + test_api.py
                    └──────────┬──────────┘
                    ┌──────────▼──────────┐
                    │ L1 单元 (Unit)      │  tests/unit/ 按域拆分
                    └─────────────────────┘

工具链

层	工具	CI	Agent MCP
L1	pytest + pytest-asyncio + 内存 SQLite/假 Redis	✅ gitea workflow	否
L2	pytest + httpx AsyncClient + docker mysql/redis	✅ 可选 job	MySQL MCP 验数
L3	pytest markers `@pytest.mark.chain`	✅ nightly	否
L4	`@playwright/test`	✅ `--with-ui`	Playwright MCP 对照用例
L5	Playwright MCP `browser_*`	❌ 人工触发 Agent	✅

目录规划（渐进迁移，不一次性搬空 tests/）

tests/
  unit/           # 纯函数、schema、utils（从现有 test_*.py 归类迁入）
  integration/    # API + DB，httpx TestClient / 活 API
  chain/          # 多步业务流
  fixtures/       # 共享 conftest 分层
  acceptance_catalog.py  # 扩展 layer: unit|integration|chain|ui|mcp
frontend/e2e/
  pages/          # 每页一个 spec（从 full-acceptance 拆分）
  flows/          # 链条：登录→推送→进度→历史
docs/testing/
  test-case-matrix.md   # 全量用例 SSOT（编号）
  mcp-browser-playbook.md  # Agent MCP 点页规程

MCP Agent 点页规程（原则）

用例先行：每个 MCP 探索必须对应 docs/testing/test-case-matrix.md 中 MCP-* 编号
步骤可复现：snapshot → click → assert 文本；截图存 docs/reports/e2e-screenshots/
禁止生产破坏性操作：推送/脚本执行/批量删除仅对 test-* 子机或 dry-run
沉淀：MCP 通过的流程 7 日内写入 Playwright spec（L4）

安全与性能约束

测试账号：NEXUS_TEST_ADMIN_*，禁止写生产密钥入 git
E2E 默认 127.0.0.1:8600；生产 URL 仅只读冒烟且需用户批准
链条测试子机：标记 is_test=1 或使用 ID 段约定（文档化）
单 CI job pytest 目标 < 10min；chain/ui 放 nightly

验收标准（体系本身）

docs/testing/test-case-matrix.md 覆盖 15 SPA 页 + 安装向导 + Agent 心跳
每层有 ≥1 个可运行示例用例与命令
run_nexus_acceptance.py 能 rollup unit/integration/chain/ui 四层
Agent 手册 mcp-browser-playbook.md 含登录、推送提交、脚本执行看板 3 条标准 MCP 流
CI：PR 跑 L1+L2；main nightly 跑 L3+L4

4.7 KiB Raw Permalink Blame History Unescape Escape