TBC/specs/AUTOMATION-SPEC.md
d-robotics 633a797226 AutoFlow v2.0: 合并 Test (Robogo) + data-loop-automation (D-Cloud) 为统一平台
- 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 模块
2026-06-23 11:48:29 +08:00

6.3 KiB
Raw Blame History

自动化测试工程规范

文档联动关系

本文档规定 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 状态码、业务状态码和关键字段。
  • 资源创建类测试具备清理逻辑。
  • 文档和覆盖率需要同步时已回写。