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 条） ： 数据隔离（红线） ：测试数据统一 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。