docs: Web + App UI 自动化测试最佳实践 v1.0

2026-07-15 09:38:01 +08:00
parent 56137c95ed
commit 26ef99f7e7
1 changed files with 835 additions and 0 deletions
@@ -0,0 +1,835 @@
+# Web + App UI 自动化测试最佳实践
+
+> **版本**: v1.0 | **日期**: 2026-07-15 | **维护者**: QE Fleet Team
+>
+> **定位**: 面向测试工程师和 AI Agent 的统一 UI 自动化实践指南。人类工程师可按章查阅、逐条落地；AI Agent（`web-executor`、`mobile-executor`）可将本文档规则作为脚本生成依据。
+>
+> **前置阅读**: 建议先阅读 `knowledge_base/01_standards/test_case_template.md`（用例规范）和 `definition_of_done.md`（完成定义）。
+
+---
+
+## 目录
+
+1. [总则与适用范围](#1-总则与适用范围)
+2. [技术栈与框架选型](#2-技术栈与框架选型)
+3. [Web UI 自动化最佳实践](#3-web-ui-自动化最佳实践)
+4. [App UI 自动化最佳实践](#4-app-ui-自动化最佳实践)
+5. [通用工程实践](#5-通用工程实践)
+6. [UI 自动化用例范例](#6-ui-自动化用例范例)
+7. [附录](#7-附录)
+
+---
+
+## 1. 总则与适用范围
+
+### 1.1 适用场景
+
+| 场景 | Web (Playwright) | App (Appium) | 说明 |
+| :--- | :---: | :---: | :--- |
+| PC Web 管理后台 | ✅ | — | 平台端、商家端等中后台系统 |
+| 移动 H5 页面 | ✅ | — | 微信 H5、手机浏览器页面 |
+| Android 原生 APP | — | ✅ | UiAutomator2 驱动 |
+| iOS 原生 APP | — | ✅ | XCUITest 驱动 |
+| 微信小程序 | ✅ | — | 小程序本质是 WebView，用 Playwright 操作 |
+| 混合场景（Web + App 联动） | ✅ | ✅ | 如后台发起操作 → APP 端验证结果 |
+
+### 1.2 与项目文档体系的关系
+
+```text
+本文档（最佳实践）
+  ├── 引用 agents/execute/web_executor.md（Web 执行规则）
+  ├── 引用 agents/execute/mobile_executor.md（App 执行规则）
+  ├── 符合 knowledge_base/01_standards/test_case_template.md（用例规范）
+  ├── 符合 knowledge_base/01_standards/definition_of_done.md（完成定义）
+  └── 补充 knowledge_base/03_best_practices/（本目录）的自动化工程视角
+```
+
+### 1.3 基础原则
+
+1. **自动化不是目标，质量才是。** 只自动化那些需要频繁回归、手工执行成本高的用例。
+2. **稳定性 > 覆盖率。** 100 个可靠的用例比 500 个频繁误报的用例有价值。
+3. **可维护性优先。** 定位策略、数据准备、断言逻辑必须清晰可读。
+4. **失败必须可追溯。** 每次失败必须产出截图 + 日志 + 操作序列，让接手者无需复现即可定位。
+
+---
+
+## 2. 技术栈与框架选型
+
+### 2.1 框架选择决策表
+
+| 被测端 | 推荐框架 | 当前版本 | 驱动/引擎 |
+| :--- | :--- | :--- | :--- |
+| PC Web | **Playwright** (Python) | ≥1.40 | Chromium / Firefox / WebKit |
+| 移动 H5 | **Playwright** (Python) | ≥1.40 | Chromium (移动视口模拟) |
+| Android APP | **Appium** (Python) | ≥3.0 | UiAutomator2 |
+| iOS APP | **Appium** (Python) | ≥3.0 | XCUITest |
+| 微信小程序 | **Playwright** (Python) | ≥1.40 | Chromium (特定 User-Agent) |
+
+### 2.2 为什么选 Playwright 而非 Selenium？
+
+| 维度 | Playwright | Selenium |
+| :--- | :--- | :--- |
+| 自动等待 | 内置（actionability checks） | 需手动 `WebDriverWait` |
+| 网络拦截 | `page.route()` 原生支持 | 需 CDP 或代理 |
+| 多浏览器 | 单 API，同代码 | 各浏览器 driver 独立 |
+| 调试工具 | `--debug`、Trace Viewer、Codegen | 较弱的原生日志 |
+| 执行速度 | 快（单一 WebSocket 连接） | 慢（HTTP 往返） |
+
+> **团队决策**: 本项目统一使用 Playwright。旧 Selenium 用例应逐步迁移。
+
+### 2.3 为什么选 Appium 而非专用框架？
+
+| 维度 | Appium | Espresso / XCUITest 原生 |
+| :--- | :--- | :--- |
+| 跨平台复用 | 高（一套 API 双平台） | 低（两套独立代码） |
+| 学习成本 | 低（WebDriver 协议） | 高（平台特有 API） |
+| CI 集成 | 成熟（Server-Client 架构） | 需额外工具链 |
+| 脚本语言 | Python / Java / JS 等 | Java/Kotlin (Android) / Swift (iOS) |
+
+> **团队决策**: 本项目统一使用 Appium (Python Client)。除非有性能压测或白盒测试需求，不引入原生框架。
+
+---
+
+## 3. Web UI 自动化最佳实践
+
+### 3.1 定位策略（Element Locator）
+
+**优先级从高到低：**
+
+| 优先级 | 策略 | 示例 | 稳定性 |
+| :---: | :--- | :--- | :---: |
+| 1 | `data-testid` | `page.getByTestId('submit-btn')` | ⭐⭐⭐⭐⭐ |
+| 2 | `role + name` | `page.getByRole('button', {name: '提交'})` | ⭐⭐⭐⭐ |
+| 3 | `text` | `page.getByText('确认删除')` | ⭐⭐⭐ |
+| 4 | `placeholder` | `page.getByPlaceholder('请输入手机号')` | ⭐⭐⭐ |
+| 5 | `label` | `page.getByLabel('用户名')` | ⭐⭐⭐ |
+| 6 | CSS selector | `page.locator('.form .submit-btn')` | ⭐⭐ |
+| 7 | XPath | `page.locator('//div[@class="foo"]//button')` | ⭐ |
+
+**原则**:
+
+- ✅ **永远优先使用语义化定位**（`data-testid`、`role`、`text`）。它们不随 UI 重构而断裂。
+- ❌ **避免使用 CSS class**（尤其是 `_hash_abc123` 这类编译期生成的 class）。
+- ❌ **避免 XPath 长链**（`/html/body/div[3]/div[2]/span[1]`），改一个嵌套层级就全挂。
+- ⚠️ **不确定的 selector 用注释标注 `# ⚠️ 需确认 selector`**，不要捏造。
+
+**反例 vs 正例:**
+
+```python
+# ❌ 反例：CSS class 不稳定，UI 改动就失效
+page.locator('.ant-btn.ant-btn-primary.btn-submit-form-v2').click()
+
+# ❌ 反例：深层 XPath，嵌套改动就挂
+page.locator('/html/body/div[3]/div[2]/div[1]/form/div[4]/button[1]').click()
+
+# ✅ 正例：data-testid，与视觉样式解耦
+page.getByTestId('order-submit-btn').click()
+
+# ✅ 正例：语义化 role + name
+page.getByRole('button', name='提交订单').click()
+
+# ✅ 正例：文本匹配
+page.getByText('确认收货').click()
+```
+
+### 3.2 等待策略
+
+Playwright 内置自动等待（actionability checks），大多数场景**不需要**手动等待。只有在以下情况才显式加等待：
+
+| 场景 | 推荐写法 | 说明 |
+| :--- | :--- | :--- |
+| 页面跳转后等待元素 | `page.waitForSelector('[data-testid="result"]')` | 等待关键元素出现 |
+| 等待网络请求完成 | `page.waitForResponse(lambda r: '/api/order' in r.url)` | 等待 API 返回 |
+| 等待特定状态文本 | `expect(page.getByText('提交成功')).toBeVisible()` | 等待 UI 状态变化 |
+| 等待元素消失 | `expect(page.locator('.loading')).toBeHidden()` | 等待 Loading 结束 |
+
+**反例 vs 正例:**
+
+```python
+# ❌ 反例：硬编码 sleep——浪费时间且不可靠
+import time
+page.click('button')
+time.sleep(3)  # 网速慢时 3 秒不够，快时浪费
+assert page.getByText('成功').is_visible()
+
+# ✅ 正例：使用 Playwright 自动等待 + 显式等待结合
+page.getByTestId('submit-btn').click()
+expect(page.getByText('提交成功')).toBeVisible(timeout=10000)  # 最多等 10 秒
+```
+
+### 3.3 Page Object 模式
+
+将页面元素定位和操作封装为独立的 Page Object 类，实现**用例逻辑与页面结构的分离**。
+
+**结构约定**:
+
+```python
+# pages/order_page.py
+from playwright.sync_api import Page, expect
+
+class OrderPage:
+    """订单确认页"""
+
+    def __init__(self, page: Page):
+        self.page = page
+        # 所有定位器集中定义在 __init__
+        self.submit_btn = page.getByTestId('order-submit-btn')
+        self.amount_text = page.getByTestId('order-total-amount')
+        self.success_tip = page.getByText('下单成功')
+
+    def get_total_amount(self) -> str:
+        """获取订单总金额"""
+        return self.amount_text.inner_text()
+
+    def submit(self) -> None:
+        """提交订单并等待成功提示"""
+        self.submit_btn.click()
+        expect(self.success_tip).toBeVisible(timeout=10000)
+
+    def verify_amount(self, expected: str) -> None:
+        """验证订单金额"""
+        expect(self.amount_text).toContainText(expected)
+```
+
+**原则**:
+
+- 每个 Page Object 对应**一个页面或一个功能区域**（弹窗、抽屉可独立）。
+- 定位器集中声明在 `__init__()`，方法只调用已声明的定位器。
+- 断言尽可能封装在 Page Object 方法内（如 `submit()` 自带成功断言）。
+- 跨页面复用操作封装为**公共组件**（如 `LoginComponent`、`NavBar`），而不是在每个 Page Object 中重复。
+
+### 3.4 截图策略
+
+本项目的截图策略与 `agents/execute/web_executor.md` 对齐：
+
+| 策略 | 配置参数 | 说明 |
+| :--- | :--- | :--- |
+| **失败截图**（默认开启） | `screenshot_on_failure: true` | 断言失败/异常时自动截图 |
+| **每步截图**（默认关闭） | `screenshot_on_step: false` | 量大，仅在调试阶段开启 |
+| **关键节点截图** | 始终开启 | P0 用例的关键验证点 |
+
+```python
+# ✅ 正例：失败自动截图（conftest.py 全局 fixture）
+@pytest.fixture(autouse=True)
+def screenshot_on_failure(request, page):
+    yield
+    if request.node.rep_call.failed:
+        path = f"output/screenshots/{request.node.name}_{datetime.now():%Y%m%d_%H%M%S}.png"
+        page.screenshot(path=path, full_page=True)
+
+# ✅ 正例：关键节点显式截图
+page.getByTestId('pay-btn').click()
+page.screenshot(path=f"output/screenshots/after_payment_{order_id}.png")
+```
+
+截图命名规范: `{用例编号}_{操作描述}_{时间戳}.png`，如 `ORDER_001_click_submit_20260715_143020.png`。
+
+### 3.5 重试与容错
+
+| 配置项 | 推荐值 | 说明 |
+| :--- | :--- | :--- |
+| 失败用例重试 | 1 次 | `retry_on_failure: 1` |
+| 操作超时 | 30 秒 | 单次操作（点击/输入）的超时 |
+| 断言超时 | 10 秒 | `expect().toBeVisible()` 的等待上限 |
+| 页面加载超时 | 60 秒 | `page.goto()` 的导航超时 |
+
+```python
+# ✅ 正例：关键操作加重试（仅在网络相关失败时）
+from playwright.sync_api import TimeoutError as PlaywrightTimeout
+
+def safe_click(locator, max_retries=2):
+    for attempt in range(max_retries):
+        try:
+            locator.click(timeout=30000)
+            return
+        except PlaywrightTimeout:
+            if attempt == max_retries - 1:
+                raise
+            time.sleep(2)
+```
+
+> ⚠️ **注意**: 重试仅适用于网络抖动、临时渲染问题。断言失败（业务逻辑错误）不应重试，直接标记失败。
+
+### 3.6 多浏览器覆盖
+
+```python
+# conftest.py — 按 fleet_config.yml 配置的 browsers 参数化
+import pytest
+from playwright.sync_api import sync_playwright
+
+BROWSERS = ["chromium", "firefox", "webkit"]  # 或从 fleet_config.yml 读取
+
+@pytest.fixture(params=BROWSERS)
+def browser_context(request):
+    with sync_playwright() as p:
+        browser = getattr(p, request.param).launch(headless=True)
+        context = browser.new_context(viewport={"width": 1920, "height": 1080})
+        yield context
+        context.close()
+        browser.close()
+```
+
+> **建议**: P0 用例覆盖 Chromium + 至少一个额外浏览器；P1 用例默认仅 Chromium。
+
+---
+
+## 4. App UI 自动化最佳实践
+
+### 4.1 定位策略（Element Locator）
+
+**优先级从高到低：**
+
+| 优先级 | 策略 | Android 示例 | iOS 示例 | 稳定性 |
+| :---: | :--- | :--- | :--- | :---: |
+| 1 | `accessibility_id` | `driver.find_element(AppiumBy.ACCESSIBILITY_ID, "submit")` | 同 | ⭐⭐⭐⭐⭐ |
+| 2 | `id` | `driver.find_element(AppiumBy.ID, "com.app:id/btn")` | `driver.find_element(AppiumBy.ID, "submitBtn")` | ⭐⭐⭐⭐ |
+| 3 | `class_name + index` | `driver.find_elements(AppiumBy.CLASS_NAME, "android.widget.Button")[0]` | 同 | ⭐⭐ |
+| 4 | XPath | `driver.find_element(AppiumBy.XPATH, "//*[@text='确认']")` | 同 | ⭐ |
+
+**原则**:
+
+- ✅ 优先让开发在关键元素上添加 `content-desc`（Android）或 `accessibilityIdentifier`（iOS），对应 `accessibility_id` 定位。
+- ❌ 避免 XPath，移动端 UI 层级深且频繁变动。
+- ❌ 避免坐标点击（`tap([x, y])`），不同分辨率/设备上位置完全不同。
+- ⚠️ 不确定的定位方式用注释标注 `# ⚠️ 需确认定位方式`。
+
+**反例 vs 正例:**
+
+```python
+# ❌ 反例：坐标点击——换一台设备就挂
+driver.tap([(300, 500)])
+
+# ❌ 反例：深层 XPath
+driver.find_element(AppiumBy.XPATH, "//android.view.View[3]/android.widget.Button[2]")
+
+# ✅ 正例：accessibility_id 最稳定
+driver.find_element(AppiumBy.ACCESSIBILITY_ID, "submit_order_btn").click()
+
+# ✅ 正例：id 定位（Android 资源 ID）
+driver.find_element(AppiumBy.ID, "com.example.app:id/btn_pay").click()
+```
+
+### 4.2 Android vs iOS 双平台差异
+
+```python
+# ✅ 正例：平台感知的 Driver Factory
+import platform
+from appium import webdriver
+from appium.options.android import UiAutomator2Options
+from appium.options.ios import XCUITestOptions
+
+def create_driver():
+    if platform.system() == "Android":
+        options = UiAutomator2Options()
+        options.device_name = "Android Emulator"
+        options.app_package = "com.example.app"       # ⚠️ 必改
+        options.app_activity = ".MainActivity"         # ⚠️ 必改
+        options.no_reset = True
+        options.automation_name = "UiAutomator2"
+        return webdriver.Remote("http://localhost:4723", options=options)
+    else:
+        options = XCUITestOptions()
+        options.device_name = "iPhone 15"
+        options.bundle_id = "com.example.app"           # ⚠️ 必改
+        options.no_reset = True
+        options.automation_name = "XCUITest"
+        return webdriver.Remote("http://localhost:4723", options=options)
+```
+
+| 差异点 | Android | iOS |
+| :--- | :--- | :--- |
+| 驱动 | UiAutomator2 | XCUITest |
+| 应用标识 | `appPackage` + `appActivity` | `bundleId` |
+| 等待策略 | `WebDriverWait` + `expected_conditions` | 同，但部分 condition 支持有限 |
+| 手势 API | `driver.swipe()` | `driver.swipe()`（API 一致） |
+| 截图 | `driver.save_screenshot(path)` | 同 |
+
+### 4.3 手势操作
+
+```python
+# 滑动（从下往上）
+def swipe_up(driver, duration_ms=500):
+    size = driver.get_window_size()
+    driver.swipe(
+        start_x=size['width'] // 2,
+        start_y=int(size['height'] * 0.8),
+        end_x=size['width'] // 2,
+        end_y=int(size['height'] * 0.2),
+        duration=duration_ms
+    )
+
+# 长按
+from appium.webdriver.common.appiumby import AppiumBy
+from appium.webdriver.common.touch_action import TouchAction
+
+def long_press(driver, element, duration_ms=1000):
+    TouchAction(driver).long_press(element, duration=duration_ms).release().perform()
+
+# 双指缩放（地图/图片）
+def pinch(driver, scale=0.5):
+    # ⚠️ 推荐使用 MultiAction API，因设备差异较大，需实际调试
+    pass
+```
+
+### 4.4 等待策略
+
+移动端网络不稳定，等待策略比 Web 更关键：
+
+```python
+from selenium.webdriver.support.ui import WebDriverWait
+from selenium.webdriver.support import expected_conditions as EC
+from appium.webdriver.common.appiumby import AppiumBy
+
+# ✅ 正例：显式等待元素可见后再操作
+wait = WebDriverWait(driver, timeout=30)
+
+element = wait.until(
+    EC.visibility_of_element_located((AppiumBy.ACCESSIBILITY_ID, "order_status"))
+)
+assert element.text == "已完成"
+
+# ❌ 反例：硬编码 sleep
+import time
+time.sleep(5)  # 网络差时 5 秒不够
+driver.find_element(AppiumBy.ACCESSIBILITY_ID, "order_status")
+```
+
+### 4.5 截图策略
+
+| 策略 | 说明 |
+| :--- | :--- |
+| **失败截图**（默认开启） | 断言失败/异常时立即截图 |
+| **关键页面截图** | 登录后首页、核心操作页、结果页 |
+| **状态变化截图** | 状态流转前后各截一张 |
+
+```python
+def take_screenshot(driver, name: str):
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    path = f"output/screenshots/{name}_{timestamp}.png"
+    driver.save_screenshot(path)
+    return path
+
+# 失败自动截图（conftest.py）
+@pytest.hookimpl(hookwrapper=True)
+def pytest_runtest_makereport(item, call):
+    outcome = yield
+    if outcome.get_result().failed and "driver" in item.funcargs:
+        driver = item.funcargs["driver"]
+        take_screenshot(driver, f"FAIL_{item.name}")
+```
+
+---
+
+## 5. 通用工程实践
+
+以下实践同时适用于 Web 和 App 自动化。
+
+### 5.1 用例独立性
+
+每个测试用例必须是**独立且可任意顺序执行**的。
+
+```python
+# ✅ 正例：每个用例独立准备数据 + 独立清理
+class TestOrderSubmit:
+
+    @pytest.fixture(autouse=True)
+    def setup_and_teardown(self):
+        self.test_data = create_test_order()       # 每个用例创建独立数据
+        yield
+        cleanup_test_order(self.test_data['id'])   # 用例结束后清理
+
+    def test_normal_submit(self):
+        result = submit_order(self.test_data['id'])
+        assert result.status == "SUCCESS"
+
+    def test_duplicate_submit(self):
+        submit_order(self.test_data['id'])           # 第一次提交
+        result = submit_order(self.test_data['id'])  # 重复提交
+        assert result.status == "ALREADY_SUBMITTED"
+
+# ❌ 反例：用例之间存在数据依赖
+def test_a_create_order():
+    global order_id  # 全局变量，换执行顺序就挂
+    order_id = create_order()
+
+def test_b_pay_order():
+    pay_order(order_id)  # 依赖 test_a 先执行，且 order_id 不为空
+```
+
+### 5.2 数据驱动
+
+将测试数据与用例逻辑分离，同一套用例覆盖多组数据：
+
+```python
+# ✅ 正例：参数化测试数据
+import pytest
+
+TEST_DATA = [
+    # (支付方式, 金额, 预期结果)
+    ("支付宝", 100,   "支付成功"),
+    ("微信支付", 50,  "支付成功"),
+    ("银行卡", 1000,  "支付成功"),
+    ("支付宝", 0,     "金额不能为0"),
+    ("支付宝", -10,   "金额不能为负"),
+]
+
+class TestPayment:
+    @pytest.mark.parametrize("pay_method,amount,expected", TEST_DATA)
+    def test_payment(self, pay_method, amount, expected):
+        result = pay(method=pay_method, amount=amount)
+        assert result.message == expected
+```
+
+### 5.3 环境配置管理
+
+所有环境相关信息统一管理，不硬编码在测试脚本中：
+
+```python
+# config/test_config.yaml
+base_url: "https://test.example.com"
+timeout_seconds: 120
+accounts:
+  admin: { phone: "13800138000", password: "Test123456" }
+  user:  { phone: "13800138001", password: "Test123456" }
+browsers: ["chromium", "firefox"]
+```
+
+```python
+# ✅ 正例：从配置读取
+import yaml
+from pathlib import Path
+
+def load_config():
+    with open(Path(__file__).parent / "config/test_config.yaml", encoding="utf-8") as f:
+        return yaml.safe_load(f)
+
+config = load_config()
+page.goto(config["base_url"])
+page.getByPlaceholder("手机号").fill(config["accounts"]["admin"]["phone"])
+
+# ❌ 反例：硬编码
+BASE_URL = "https://test.example.com"       # 换环境要改代码
+ADMIN_PHONE = "13800138000"                  # 换账号要改代码
+```
+
+### 5.4 报告与日志
+
+```python
+import logging
+from datetime import datetime
+
+# 日志配置
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(message)s",
+    handlers=[
+        logging.FileHandler(f"output/logs/test_{datetime.now():%Y%m%d_%H%M%S}.log"),
+        logging.StreamHandler()
+    ]
+)
+logger = logging.getLogger(__name__)
+
+class TestOrder:
+    def test_submit(self):
+        logger.info(f"开始执行: 验证正常下单")
+        try:
+            # ...
+            logger.info(f"✅ 通过: 验证正常下单")
+        except Exception as e:
+            logger.error(f"❌ 失败: 验证正常下单 — {e}")
+            raise
+```
+
+**报告输出要求**:
+
+- 每个用例执行后产出: 通过/失败/跳过 + 耗时 + 失败原因（如有）+ 截图路径
+- 批量运行结束后产出汇总: `通过 X / 失败 Y / 跳过 Z`，列出所有失败用例的截图链接
+
+### 5.5 CI 集成
+
+```yaml
+# CI 配置示例 (GitHub Actions / Gitea Actions)
+jobs:
+  web-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - run: pip install -r requirements.txt
+      - run: playwright install chromium
+      - run: pytest tests/web/ --screenshot on_failure --junitxml=report.xml
+
+  app-tests:
+    runs-on: macos-latest  # iOS 测试必须 macOS
+    steps:
+      - uses: actions/checkout@v4
+      - run: |
+          # 启动 Appium Server
+          appium --log-level info --log appium.log &
+          sleep 5
+      - run: pytest tests/app/ --platform android --junitxml=report.xml
+```
+
+---
+
+## 6. UI 自动化用例范例
+
+> 以下范例直接从 `knowledge_base/03_best_practices/` 下的业务用例中提取自动化实现，展示"好的手工用例"如何映射为"可运行的自动化代码"。
+
+### 6.1 Web — 支付流程 (Playwright)
+
+**来源用例**: `payment_flow_cases.md` — `PAY_01_001`（验证正常支付流程成功）
+
+```python
+# tests/web/test_payment.py
+import pytest
+from playwright.sync_api import Page, expect
+
+class TestPaymentFlow:
+    """支付流程自动化测试"""
+
+    @pytest.fixture(autouse=True)
+    def setup(self, page: Page):
+        """每个用例前登录 + 准备可售商品"""
+        self.page = page
+        login(page, user="user_A")                            # 封装好的登录函数
+        self.item_id = add_item_to_cart(page, sku="SKU-001")  # 添加商品到购物车
+        yield
+        cancel_remaining_orders(page)                         # 清理未支付订单
+
+    def test_normal_payment_alipay(self, page: Page):
+        """PAY_01_001: 验证正常支付流程成功"""
+        # Step 1-2: 进入收银台，选择支付宝
+        page.getByTestId("checkout-btn").click()
+        expect(page.getByTestId("cashier-page")).toBeVisible()
+        page.getByTestId("pay-method-alipay").click()
+
+        # Step 3: 完成支付
+        page.getByTestId("confirm-pay-btn").click()
+
+        # 预期 1: 页面跳转支付成功页
+        expect(page.getByText("支付成功")).toBeVisible(timeout=10000)
+
+        # 预期 2: 订单状态变更为"待发货"
+        page.getByTestId("nav-orders").click()
+        order_status = page.getByTestId(f"order-{self.item_id}-status")
+        expect(order_status).toHaveText("待发货")
+
+        # 预期 3: 支付流水金额与订单实付一致
+        page.getByTestId(f"order-{self.item_id}-detail").click()
+        pay_amount = page.getByTestId("pay-record-amount").inner_text()
+        order_amount = page.getByTestId("order-actual-amount").inner_text()
+        assert pay_amount == order_amount, f"支付金额 {pay_amount} ≠ 订单金额 {order_amount}"
+```
+
+### 6.2 Web — 异常流程 (Playwright)
+
+```python
+    def test_payment_balance_insufficient_switch_method(self, page: Page):
+        """PAY_01_003: 验证支付渠道返回余额不足时可切换支付方式"""
+        page.getByTestId("checkout-btn").click()
+
+        # 选择银行卡支付
+        page.getByTestId("pay-method-bankcard").click()
+
+        # 模拟支付渠道返回余额不足
+        page.getByTestId("confirm-pay-btn").click()
+        expect(page.getByText("余额不足")).toBeVisible(timeout=10000)
+
+        # 订单仍保持待支付状态
+        page.getByTestId("nav-orders").click()
+        order_status = page.getByTestId(f"order-{self.item_id}-status")
+        expect(order_status).toHaveText("待支付")
+
+        # 可切换支付方式继续支付
+        page.getByTestId(f"order-{self.item_id}-pay").click()
+        page.getByTestId("pay-method-alipay").click()
+        page.getByTestId("confirm-pay-btn").click()
+        expect(page.getByText("支付成功")).toBeVisible(timeout=10000)
+```
+
+### 6.3 Web — 表单验证 (Playwright)
+
+```python
+# tests/web/test_login.py
+class TestLogin:
+    """登录功能自动化测试"""
+
+    @pytest.mark.parametrize("phone,password,expected_error", [
+        ("",         "Test123456", "请输入手机号"),
+        ("13800138000", "",         "请输入密码"),
+        ("13800138000", "wrong",    "密码错误"),
+        ("13800000000", "Test123456", "账号不存在"),
+    ])
+    def test_login_validation(self, page: Page, phone, password, expected_error):
+        """验证登录表单校验"""
+        page.goto("/login")
+
+        if phone:
+            page.getByPlaceholder("请输入手机号").fill(phone)
+        if password:
+            page.getByPlaceholder("请输入密码").fill(password)
+        page.getByRole("button", name="登录").click()
+
+        expect(page.getByText(expected_error)).toBeVisible()
+```
+
+### 6.4 App — 登录流程 (Appium)
+
+```python
+# tests/app/test_login.py
+import pytest
+from appium.webdriver.common.appiumby import AppiumBy
+from selenium.webdriver.support.ui import WebDriverWait
+from selenium.webdriver.support import expected_conditions as EC
+
+class TestAppLogin:
+    """APP 登录自动化测试"""
+
+    def test_login_success(self, driver):
+        """验证正常登录成功"""
+        wait = WebDriverWait(driver, timeout=30)
+
+        # 输入手机号
+        phone_input = wait.until(
+            EC.visibility_of_element_located((AppiumBy.ACCESSIBILITY_ID, "login_phone_input"))
+        )
+        phone_input.send_keys("13800138000")
+
+        # 输入密码
+        driver.find_element(AppiumBy.ACCESSIBILITY_ID, "login_password_input").send_keys("Test123456")
+
+        # 点击登录
+        driver.find_element(AppiumBy.ACCESSIBILITY_ID, "login_submit_btn").click()
+
+        # 验证跳转主页
+        home_tab = wait.until(
+            EC.visibility_of_element_located((AppiumBy.ACCESSIBILITY_ID, "main_home_tab"))
+        )
+        assert home_tab.is_displayed()
+```
+
+### 6.5 App — 订单列表滑动与加载 (Appium)
+
+```python
+# tests/app/test_order_list.py
+class TestOrderList:
+    """APP 订单列表测试"""
+
+    def test_pull_to_refresh(self, driver):
+        """验证下拉刷新订单列表"""
+        wait = WebDriverWait(driver, timeout=30)
+
+        # 等待列表加载
+        wait.until(
+            EC.visibility_of_element_located((AppiumBy.ACCESSIBILITY_ID, "order_list"))
+        )
+
+        # 下拉刷新
+        size = driver.get_window_size()
+        driver.swipe(
+            start_x=size['width'] // 2,
+            start_y=int(size['height'] * 0.3),
+            end_x=size['width'] // 2,
+            end_y=int(size['height'] * 0.7),
+            duration=500
+        )
+
+        # 验证刷新成功提示
+        toast = wait.until(
+            EC.visibility_of_element_located((AppiumBy.XPATH, "//*[contains(@text,'刷新成功')]"))
+        )
+        assert toast is not None
+
+    def test_scroll_load_more(self, driver):
+        """验证上滑加载更多"""
+        wait = WebDriverWait(driver, timeout=30)
+
+        # 获取当前列表项数量
+        initial_items = len(driver.find_elements(AppiumBy.ACCESSIBILITY_ID, "order_card"))
+
+        # 滑动到底部
+        size = driver.get_window_size()
+        driver.swipe(
+            start_x=size['width'] // 2,
+            start_y=int(size['height'] * 0.8),
+            end_x=size['width'] // 2,
+            end_y=int(size['height'] * 0.2),
+            duration=500
+        )
+
+        # 验证加载更多
+        time.sleep(1)  # 等待渲染完成
+        after_items = len(driver.find_elements(AppiumBy.ACCESSIBILITY_ID, "order_card"))
+        assert after_items >= initial_items, f"加载更多后应不少于加载前: {after_items} < {initial_items}"
+```
+
+---
+
+## 7. 附录
+
+### 7.1 Selector 速查表
+
+#### Playwright (Web)
+
+| 场景 | 写法 |
+| :--- | :--- |
+| 按 data-testid 点击 | `page.getByTestId('my-btn').click()` |
+| 按文本点击 | `page.getByText('确 定').click()` |
+| 按角色+名称点击 | `page.getByRole('button', name='提交').click()` |
+| 按 placeholder 填写 | `page.getByPlaceholder('请输入').fill('hello')` |
+| 按 label 填写 | `page.getByLabel('手机号').fill('13800138000')` |
+| 等待可见 | `expect(page.getByText('成功')).toBeVisible()` |
+| 等待隐藏 | `expect(page.locator('.loading')).toBeHidden()` |
+| 下拉框选择 | `page.selectOption('#type', 'value1')` |
+| 文件上传 | `page.setInputFiles('input[type=file]', 'path/to/file')` |
+| 确认弹窗 | `page.on('dialog', lambda d: d.accept())` |
+| iframe 内操作 | `page.frameLocator('#iframe').getByTestId('btn')` |
+
+#### Appium (App)
+
+| 场景 | Android 写法 | iOS 写法 |
+| :--- | :--- | :--- |
+| 按 accessibility_id | `driver.find_element(AppiumBy.ACCESSIBILITY_ID, "xxx")` | 同 |
+| 按 id | `driver.find_element(AppiumBy.ID, "com.app:id/xxx")` | `driver.find_element(AppiumBy.ID, "xxx")` |
+| 按文本 | `driver.find_element(AppiumBy.XPATH, "//*[@text='xxx']")` | `driver.find_element(AppiumBy.XPATH, "//*[@label='xxx']")` |
+| 滑动 | `driver.swipe(x1,y1,x2,y2,duration)` | 同 |
+| 截图 | `driver.save_screenshot(path)` | 同 |
+| 上下文切换 | `driver.switch_to.context('WEBVIEW')` | 同 |
+| 后台运行 | `driver.background_app(5)` | 同 |
+
+### 7.2 常见坑与解决方案
+
+| 坑 | 现象 | 解决方案 |
+| :--- | :--- | :--- |
+| CSS Module hash | `locator('.btn_abc123')` 找不到 | 用 `getByTestId` 或 `getByText` |
+| iframe 跨域 | `page.locator()` 在 iframe 内失效 | 用 `page.frameLocator('#iframe')` |
+| 非固定等待时间 | `time.sleep(3)` 不够或浪费 | 用 `expect(...).toBeVisible(timeout=N)` |
+| 元素被遮挡 | `click()` 报 Element not clickable | `locator.click(force=True)` 或先滚动到可见区域 |
+| 新标签页 | 点击后在新 tab 打开，操作还在旧 tab | `page.context().pages[1]` 获取新 tab |
+| Appium 连接超时 | `Connection refused` | 检查 Appium Server 是否启动: `appium --log-level info` |
+| iOS 签名过期 | XCUITest 启动失败 | 检查开发者证书有效期；模拟器无需签名 |
+| 设备屏幕尺寸差异 | 坐标点击错位 | 用相对坐标: `size['width'] // 2` |
+| Toast 消息难定位 | 一闪而过，无法截图 | 用 `//*[contains(@text,'关键字')]` 或加短延时后截图 |
+
+### 7.3 与 Agent 执行规则的对应关系
+
+| 本文档章节 | 对应 Agent 文件 | 关系 |
+| :--- | :--- | :--- |
+| §3 Web UI 自动化    | `agents/execute/web_executor.md`    | 本文档是其执行规则的详细实践扩展 |
+| §4 App UI 自动化    | `agents/execute/mobile_executor.md` | 同上 |
+| §5.1 用例独立性     | `definition_of_done.md` §3          | 本文档给出代码层面的实现方式 |
+| §3.4 / §4.5 截图策略 | `web_executor.md` / `mobile_executor.md` 截图节 | 本文档与 Agent 配置参数对齐 |
+| §6 范例             | `knowledge_base/03_best_practices/`  | 本文档补充了自动化代码视角 |
+
+### 7.4 参考资源
+
+- [Playwright Python API](https://playwright.dev/python/docs/intro)
+- [Appium Python Client](https://github.com/appium/python-client)
+- [Appium UiAutomator2 Driver](https://github.com/appium/appium-uiautomator2-driver)
+- [Appium XCUITest Driver](https://github.com/appium/appium-xcuitest-driver)
+- 本项目: `docs/EXECUTE_SETUP_GUIDE.md` — 执行环境搭建指南
+- 本项目: `knowledge_base/01_standards/test_case_template.md` — 用例编写规范
+- 本项目: `knowledge_base/01_standards/definition_of_done.md` — 完成定义