# UI 自动化测试最佳实践 — 设计说明

> 2026-07-15 | 状态: 已批准

## 目标

为 QaAutomationHub 团队提供一份统一的 Web + App UI 自动化测试最佳实践文档,同时服务于人类测试工程师（手动执行）和 AI Agent（自动生成脚本时的执行依据）。

## 交付物

- **文件**: `knowledge_base/03_best_practices/ui_automation_best_practices.md`
- **体量**: 单一综合文档，预计 400-600 行 Markdown

## 结构

| # | 章节 | 核心内容 |
| :--- | :--- | :--- |
| 1 | 总则与适用范围 | 定位、读者、与 agents/dod 的关系 |
| 2 | 技术栈与框架选型 | Playwright/Appium 选择决策表 |
| 3 | Web UI 自动化 | 定位策略、等待、Page Object、截图、重试、多浏览器 |
| 4 | App UI 自动化 | 双平台差异、手势、设备管理、截图 |
| 5 | 通用工程实践 | 独立性、数据驱动、配置管理、报告、CI |
| 6 | UI 自动化用例范例 | 按模块给出可运行的 Playwright + Appium 代码 |
| 7 | 附录 | Selector 速查、常见坑、与 agents 对应关系 |

## 关键设计原则

1. **正例/反例**: 每条实践给出好代码与坏代码对比
2. **与现有体系对齐**: 引用已有 agents/DoD/模板中的术语和参数名
3. **可被 AI Agent 消费**: 明确的规则式语句
4. **Web + App 统一视角**: 共享通用实践，差异分别在各自章节

## 与现有文档的关系

- 扩展 `agents/execute/{web,mobile}_executor.md` 中的策略为详细实践指南
- 补充 `knowledge_base/03_best_practices/` 下缺乏的自动化工程视角
- 与 `test_case_template.md`、`definition_of_done.md` 保持术语一致

## 范围边界

- ✅ 包含: 定位策略、等待与同步、Page Object、截图、重试、多浏览器/双平台、数据驱动、代码范例
- ❌ 不包含: API 接口测试、性能压测、安全渗透测试、CI/CD 平台具体配置步骤