Codex Release Bot
91 lines
4.7 KiB
Markdown
91 lines
4.7 KiB
Markdown
# 全站测试体系设计（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 点页规程（原则）
|
||
|
||
1. **用例先行**：每个 MCP 探索必须对应 `docs/testing/test-case-matrix.md` 中 `MCP-*` 编号
|
||
2. **步骤可复现**：snapshot → click → assert 文本；截图存 `docs/reports/e2e-screenshots/`
|
||
3. **禁止生产破坏性操作**：推送/脚本执行/批量删除仅对 `test-*` 子机或 dry-run
|
||
4. **沉淀**：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
|