- 16 个业务模块,856 个测试用例,40 个 E2E 测试 - 单一 React 19 前端 + PlatformSwitcher 二合一切换 - Flask 后端支持 scenario/dcloud_module/dcloud_e2e/dcloud_all 四种任务类型 - E2E 测试面板:API 全链路(8条) + UI 点击(3条) + 分步测试(3个) - SSE 实时日志流 + 飞书告警 + 定时调度 - 完整还原原 ToB 平台 TestPanel E2E 模块
6.3 KiB
6.3 KiB
自动化测试工程规范
文档联动关系
本文档规定 data-loop-automation 工程的自动化测试总体规范。涉及测试代码、运行方式、报告、数据隔离或工程结构的任务,应先读取本文档。
| 文档或目录 | 关系 | 使用场景 |
|---|---|---|
../README.md |
主索引 | 判断是否需要读取本文档 |
TEST-WRITING-SPEC.md |
测试代码规范 | 编写测试方法、断言和 fixture 时读取 |
PAGE-OBJECT-SPEC.md |
Page Object 规范 | 编写页面对象和定位器时读取 |
API-TEST-SPEC.md |
API 测试规范 | 编写接口测试和边界测试时读取 |
TEST-CASES-SPEC.md |
测试用例文档规范 | 更新用例清单时读取 |
../test_cases/ |
测试用例目录 | 测试范围和用例来源 |
../docs/coverage/ |
覆盖率目录 | 模块覆盖率、未覆盖清单和优先级 |
1. 适用范围
本文档适用于:
- pytest + Playwright 自动化测试工程结构。
- UI、API、Flow、E2E、异常、边界和综合测试。
- 测试数据、认证状态、日志、报告、并行执行和清理机制。
- AI/Agent 生成、重构或 Review 测试代码。
2. 目录规范
测试组织采用“业务功能模块优先,模块内按测试类型拆分”的方式。
原则:
- 一级目录按业务功能模块划分,例如
data_space、data_generation、workbench。 - 模块目录内放本模块的 Page Object、API helper、局部 fixture 和测试目录。
- 测试文件按测试类型拆分,例如
ui、api、flow、e2e、exceptions、boundary。 - 页面是 Page Object 的建模粒度,也是 UI 测试中的一个验证维度;不作为仓库顶层测试组织方式。
- 跨页面场景归入对应业务模块的
flow或e2e测试,不拆成多个页面目录。
tests/
├── base/ # BasePage、Mixin、登录页面
├── utils/ # API 客户端、等待、断言、认证工具
├── fixtures/ # 公共 fixture 和清理逻辑
├── data/ # 测试数据工厂和数据管理
└── <module>/
├── <module>_page.py # 页面对象
└── tests/
├── test_<module>_ui.py
├── test_<module>_api.py
├── test_<module>_flow.py
├── test_<module>_e2e.py
└── test_<module>_exceptions.py
文档目录:
specs/ # 规范
test_cases/ # 测试用例清单和模板
docs/coverage/ # 覆盖率报告
api_docs/ # API 测试对接文档
agent_tasks/ # Agent 任务
3. 测试类型
| 类型 | marker | 文件模式 | 说明 |
|---|---|---|---|
| UI 测试 | ui |
test_*_ui.py |
页面元素、交互、可见性 |
| API 测试 | api |
test_*_api.py |
接口功能、响应结构、业务状态码 |
| Flow 测试 | flow |
test_*_flow.py |
多步骤业务流程 |
| E2E 测试 | e2e |
test_*_e2e.py |
完整用户场景 |
| 异常测试 | exceptions |
test_*_exceptions.py |
失败、超时、异常状态 |
| 综合测试 | comprehensive |
test_*_comprehensive.py |
模块完整覆盖 |
| 边界测试 | api 或模块 marker |
test_*_api_boundary.py |
参数边界、非法值、状态冲突 |
3.1 模块、页面、用例的边界
| 概念 | 用途 | 放在哪里 | 示例 |
|---|---|---|---|
| 业务功能模块 | 测试资产的一级归属 | tests/<module>/ |
tests/data_space/ |
| 页面或稳定业务区域 | Page Object 的封装对象 | tests/<module>/<module>_page.py 或拆分页面对象 |
data_space_page.py, data_space_file_list_page.py |
| 测试类型 | 执行和回归的筛选维度 | tests/<module>/tests/test_<module>_<type>.py |
test_data_space_ui.py, test_data_space_api.py |
| 测试场景 | 类或方法的业务粒度 | 测试文件内部 | TestCreateSpaceDialog, test_create_space_with_private_option |
推荐判断方式:
- 如果问题是“测哪个业务能力”,按模块定位。
- 如果问题是“怎么执行一类回归”,按 marker 或测试类型定位。
- 如果问题是“页面元素和交互怎么封装”,看 Page Object。
- 如果问题是“一个用户完整流程是否可用”,放在该模块的
flow或e2e。
4. 运行规范
运行环境:
- 推荐 Python 3.10 或 3.12。
pyproject.toml约束为>=3.10,<3.13。- 不建议使用 Python 3.13 运行 pytest;当前环境中已观察到 Python 3.13 + pytest 插件组合在 pytest 初始化阶段出现段错误。
常用命令:
.venv/bin/python -m pytest tests/ --collect-only -q
.venv/bin/python -m pytest tests/ -v
.venv/bin/python -m pytest -m ui
.venv/bin/python -m pytest -m api
.venv/bin/python -m pytest tests/data_space/ -v
.venv/bin/python scripts/run_and_report.py --tests tests/workbench/ --no-xdist
并行执行需要确保:
- 测试数据通过 worker 隔离。
- 共享资源通过 fixture 分配。
- 创建的数据在 teardown 或清理 fixture 中删除。
- 不依赖测试执行顺序。
5. 环境与敏感信息
- 环境变量通过
.env和config/settings.py读取。 - 文档和代码不得硬编码真实账号、密码、token、cookie。
- 认证状态文件应作为运行产物看待,不应成为业务逻辑依赖。
6. 测试数据与清理
新增会创建资源的测试时,必须提供清理策略:
| 场景 | 推荐方式 |
|---|---|
| 单用例创建资源 | function 级 fixture yield 后清理 |
| 模块共享基础数据 | session 或 module 级 fixture |
| 并行 worker 数据 | 按 PYTEST_XDIST_WORKER 分配唯一资源 |
| 历史残留数据 | setup 脚本或专项清理脚本 |
7. 日志和报告
- API 请求日志通过
tests/logger.py记录到logs/。 - 中文 HTML 报告通过
scripts/generate_report.py生成。 - 一键运行和报告通过
scripts/run_and_report.py执行。 - 测试失败应保留足够上下文:用例名称、请求、响应、截图或失败步骤。
8. 质量门禁
新增或修改测试时至少检查:
- 测试可独立重复执行。
- 断言覆盖真实业务结果,而不是只
assert True。 - UI 测试有稳定等待和明确定位器。
- API 测试校验 HTTP 状态码、业务状态码和关键字段。
- 资源创建类测试具备清理逻辑。
- 文档和覆盖率需要同步时已回写。