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