# 全站测试体系设计（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