e2e-test

name	e2e-test
description	为 BiSheng 生成和运行 E2E 测试。两种模式： (1) SDD 模式 — 基于 feature spec.md 的 AC 生成覆盖； (2) 自由模式 — 对指定页面/功能写测试。 采用双层策略：API 端到端测试（pytest + httpx）+ 页面手动验证清单。 自动处理认证、多租户隔离、权限检查、Radix UI 交互等常见问题。 用法：/e2e-test [feature_dir] 或 /e2e-test <描述> 当用户说"写 E2E 测试"、"端到端测试"、"E2E coverage"， 或使用 /e2e-test 命令时触发。

E2E Test Skill

概述

生成并运行 BiSheng 的 E2E 测试，覆盖 API 链路和 UI 交互流程。自动处理 JWT 认证、多租户数据隔离、OpenFGA 权限检查验证、UnifiedResponseModel 响应断言等 BiSheng 特有问题。

调用方式

/e2e-test <feature_dir>          # SDD 模式：基于 spec.md AC 生成
/e2e-test <描述>                  # 自由模式：对指定页面/功能写测试

示例：

/e2e-test features/v2.5.0/004-rebac-core
/e2e-test 为租户管理页面写创建流程测试

---

六步流程

Step 1：模式识别

解析用户参数：

• SDD 模式：参数是 features/ 开头的路径 → 读取该目录下的 spec.md
• 自由模式：参数是自由文本描述 → 直接进入 Step 3

Step 2：AC 分析（仅 SDD 模式）

读取 <feature_dir>/spec.md，从 AC 表格中分类：

API 行为类（自动化 pytest 测试）：

• CRUD 操作及响应格式
• 权限检查（允许/拒绝）
• 分页、过滤、排序
• 错误码返回（MMMEE）
• 跨租户访问拒绝

UI 交互类（手动验证清单）：

• 表单填写、按钮点击
• 列表展示、搜索过滤
• 弹窗/抽屉交互
• 路由跳转
• 权限控制（按钮隐藏/禁用）

排除：

• 纯样式/布局调整
• 纯内部状态逻辑

输出分类后的 AC 列表，作为测试用例依据。

Step 3：基础设施检查

检查共享 helpers 是否存在：

src/backend/test/e2e/
├── conftest.py       # pytest fixtures（认证、client、cleanup）
├── helpers/
│   ├── __init__.py
│   ├── auth.py       # JWT 认证 + 用户创建
│   ├── api.py        # API 常量 + 通用 CRUD helpers
│   └── cleanup.py    # 数据隔离 + 安全 cleanup
└── test_e2e_xxx.py   # 各 Feature 的测试文件

如果不存在，按照 references/test-template.md 创建基础设施。 如果需要新增共享函数，先加到对应的 helpers 文件中。

Step 4：生成测试

基于 references/test-template.md 生成测试文件。

文件命名：src/backend/test/e2e/test_e2e_{feature_name}.py

强制生成规则（12 条）：

1. 数据隔离（红线）：测试数据统一 e2e-{feature}- 前缀（≥5 字符）。禁止无条件删除所有资源——cleanup 必须按前缀过滤，只删本套件创建的数据。E2E 运行前后，非测试数据必须保持不变
2. 双重 cleanup：setup fixture 清理上次残留 + teardown 清理本次数据
3. 测试租户隔离：使用专用 test_tenant_id，不影响正式租户数据。创建测试数据前先确保测试租户存在
4. 认证流程：通过 helpers 获取 JWT token，注入到请求 headers。测试管理员和普通用户两种角色
5. 响应格式断言：所有 API 响应必须断言 UnifiedResponseModel 格式（status_code, status_message, data）
6. 权限测试配对：每个"允许"操作配对一个"拒绝"测试（不同角色/不同租户）
7. 共享 helpers：导入 test/e2e/helpers/ 的函数，禁止在测试文件内重新定义通用工具函数
8. AC 追溯：每个测试方法的 docstring 标注 AC-NN: <描述>
9. API 验证：数据变更操作后，通过 GET 请求断言最终状态（不仅依赖创建响应）
10. 错误码精确断言：业务错误断言具体的 MMMEE 错误码，不仅检查非 200
11. 串行执行：使用 pytest-ordering 或 class 内方法顺序保证 setup → tests → cleanup
12. 幂等性：测试可重复运行，不依赖特定的数据库状态（除测试自己创建的数据）

Step 5：运行与修复

运行生成的测试：

cd src/backend
.venv/bin/pytest test/e2e/test_e2e_{feature_name}.py -v

如果失败，按照 references/common-pitfalls.md 的诊断表定位问题。

最多 3 轮修复。如果 3 轮后仍有失败，输出剩余问题让用户决定。

调试技巧：

# 单个测试
.venv/bin/pytest test/e2e/test_e2e_{feature}.py::TestE2E{Feature}::test_ac01 -v -s

# 显示完整请求/响应
.venv/bin/pytest test/e2e/test_e2e_{feature}.py -v -s --log-cli-level=DEBUG

# 只运行失败的
.venv/bin/pytest test/e2e/test_e2e_{feature}.py --lf -v

Step 6：覆盖报告

输出 AC 覆盖表：

# E2E 覆盖报告: <feature_name>

## API 测试结果

| AC-ID | 描述 | 状态 | 测试方法 |
|-------|------|------|---------|
| AC-01 | 创建租户成功 | ✅ 通过 | test_ac01_create_tenant |
| AC-02 | 重复租户名拒绝 | ✅ 通过 | test_ac02_duplicate_name |
| AC-05 | 表单提交创建 | ⏭️ 跳过（UI 交互，见手动清单） | — |

通过: N/M | 跳过: K（UI 交互类）| 失败: J

## 手动验证清单

生成位置: `features/v2.5.0/{NNN}-{name}/e2e-checklist.md`
覆盖 AC: AC-05, AC-06, ...

## 整体状态: PASS / PARTIAL / FAIL

---

手动验证清单格式

当 AC 涉及 UI 交互时，生成结构化验证清单。

文件位置：features/v2.5.0/{NNN}-{name}/e2e-checklist.md

# E2E 验证清单: {feature_name}

**测试环境**: http://192.168.106.114:4001 (Platform) / :4001/workspace (Client)
**前置条件**: <描述测试前需要的数据/账号>

## Platform 前端

### AC-05: <描述>
- [ ] 步骤 1: 以管理员登录 Platform (admin/admin123)
- [ ] 步骤 2: 导航到 <页面路径>
- [ ] 步骤 3: 点击 <按钮/元素>
- [ ] 步骤 4: 填写表单: <字段=值>
- [ ] 预期: <具体可观察结果，如 toast 提示、列表刷新>
- [ ] 验证: 刷新页面后数据仍存在

### AC-06: <错误场景描述>
- [ ] 步骤: <触发错误的操作>
- [ ] 预期: <错误提示内容>

## Client 前端（如适用）

### AC-07: <描述>
- [ ] ...

## 回归检查
- [ ] 相关页面（<列出>）正常加载，无 console 错误
- [ ] 既有功能（<列出>）不受影响
- [ ] 不同角色（管理员/普通用户）看到的内容符合权限设定

---

参考文件

生成测试前必须阅读以下参考文件：

文件	用途	何时阅读
references/test-template.md	pytest E2E 测试骨架模板	生成新测试文件时
references/common-pitfalls.md	BiSheng E2E 常见陷阱诊断表	测试失败时

---

已有共享 Helpers 清单

首次运行时由 Step 3 自动创建。以下是目标结构。

test/e2e/helpers/auth.py

函数	签名	用途
get_admin_token	(client) -> str	获取管理员 JWT token
get_user_token	(client, username, password) -> str	获取指定用户 JWT token
create_test_user	(client, admin_token, username, role_id) -> dict	创建测试用户
auth_headers	(token) -> dict	构建认证请求头

test/e2e/helpers/api.py

导出	用途
API_BASE	后端 API 基础 URL 常量 (http://localhost:7860/api/v1)
assert_resp_200(resp)	断言 UnifiedResponseModel 成功响应
assert_resp_error(resp, code)	断言 UnifiedResponseModel 错误码
create_resource(client, path, data, token)	通用 POST 创建
list_resources(client, path, token, params)	通用 GET 列表
delete_resource(client, path, resource_id, token)	通用 DELETE

test/e2e/helpers/cleanup.py

函数	用途
cleanup_by_prefix(client, path, prefix, token)	安全删除指定前缀的资源。前缀必须 ≥5 字符，否则抛错防止误删
ensure_test_tenant(client, admin_token, tenant_code)	确保测试租户存在（不存在则创建）

---

新增 Helper 的规则

当测试需要新的共享函数时：

1. 认证相关 → 加到 helpers/auth.py
2. API 请求/断言 → 加到 helpers/api.py
3. 数据管理/fixtures → 加到 helpers/cleanup.py
4. 特定 feature 的 helper → 留在测试文件内，不提取

提取标准：2 个以上测试文件使用 → 提取到 helpers。