UI 自动化测试验收模块使用手册

1. 概述

1.1 模块定位

UI 自动化测试验收模块是端到端研发自动化系统的最后一个关键环节，负责在 CI/CD 流水线中自动执行 UI 层面的功能验证、回归测试和用户体验测试。

💡 核心价值：实现从代码提交到部署再到 UI 测试验收的全流程自动化，支持人机协同和智能分析。

1.2 核心价值

全流程自动化: 从代码提交到部署再到 UI 测试验收，全程无需人工干预
人机协同: 支持测试人员介入进行复杂场景的手动验证
智能分析: 基于 AI 的测试结果分析和缺陷定位
多环境支持: 支持开发、测试、预发布、生产等多环境测试

1.3 技术栈

├── 测试框架：Playwright / Selenium / Cypress
├── 断言库：Chai / Jest / Assert
├── 报告工具：Allure / HTML Reporter
├── 容器化：Docker + K8S (KubeSphere)
├── CI/CD: Jenkins Pipeline
├── AI 集成：Claude Code for Test Analysis
└── 语言支持：Python / TypeScript / Java

2. 系统架构

2.1 整体架构图

┌─────────────────────────────────────────────────────────────┐ │ CI/CD Pipeline (Jenkins) │ ├─────────────────────────────────────────────────────────────┤ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │ │ Unit Test │→ │Integration │→ │ Docker Build & │ │ │ │ Stage │ │ Test │ │ Push │ │ │ └─────────────┘ └─────────────┘ └─────────────────────┘ │ │ ↓ │ │ ┌─────────────────────────┐ │ │ │ K8S Auto Deployment │ │ │ │ (KubeSphere) │ │ │ └─────────────────────────┘ │ │ ↓ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ UI Automation Test Module │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌──────────────┐ │ │ │ │ │ Test Cases │→ │ Execution │→ │ AI Analysis │ │ │ │ │ │ Engine │ │ Engine │ │ Engine │ │ │ │ │ └─────────────┘ └─────────────┘ └──────────────┘ │ │ │ └──────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘

2.2 模块组件

组件名称	功能描述	技术实现
Test Case Manager	测试用例管理与版本控制	Git + YAML/JSON
Execution Engine	测试执行引擎	Playwright/Selenium Grid
Screenshot Service	截图与视频录制服务	FFmpeg + Canvas
AI Analysis Engine	智能分析与缺陷定位	Claude Code API
Report Generator	测试报告生成	Allure + Custom HTML
Notification Service	通知服务	Slack/Email/Webhook

3. 环境准备

3.1 硬件要求

资源类型	最低配置	推荐配置
CPU	4 核	8 核+
内存	8GB	16GB+
存储	50GB	100GB+ SSD
网络	100Mbps	1Gbps

3.2 软件依赖

基础环境

# Node.js (v18+)
node --version

# Python (v3.10+)
python3 --version

# Docker (v24+)
docker --version

# Kubectl (v1.28+)
kubectl version --client

浏览器驱动

# Playwright 浏览器安装
npx playwright install

# 或 Selenium WebDriver
# ChromeDriver, GeckoDriver, etc.

4. 模块安装与配置

4.1 快速安装

方式一：Docker Compose 安装

version: '3.8'
services:
  ui-test-runner:
    image: openclaw/ui-test-runner:v1.0.0
    container_name: ui-test-runner
    environment:
      - TEST_FRAMEWORK=playwright
      - BROWSER=chromium
      - HEADLESS=true
      - CLAUDE_API_KEY=${CLAUDE_API_KEY}
    volumes:
      - ./test-cases:/app/test-cases
      - ./reports:/app/reports
      - ./screenshots:/app/screenshots
    networks:
      - test-network
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G

  selenium-hub:
    image: selenium/hub:4.15
    container_name: selenium-hub
    ports:
      - "4442:4442"
      - "4443:4443"
      - "4444:4444"
    networks:
      - test-network

  allure-report:
    image: frankescobar/allure-docker-service
    container_name: allure-report
    ports:
      - "5050:5050"
    environment:
      CHECK_RESULTS_EVERY_SECONDS: NONE
    volumes:
      - ./allure-results:/app/allure-results
    networks:
      - test-network

networks:
  test-network:
    driver: bridge

✅ 启动命令: docker-compose up -d

方式二：Kubernetes 部署

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ui-automation-test
  namespace: ci-cd
spec:
  replicas: 3
  selector:
    matchLabels:
      app: ui-test
  template:
    metadata:
      labels:
        app: ui-test
    spec:
      containers:
      - name: test-runner
        image: openclaw/ui-test-runner:v1.0.0
        env:
        - name: TEST_ENV
          value: "staging"
        - name: PARALLEL_WORKERS
          value: "5"
        resources:
          requests:
            memory: "2Gi"
            cpu: "1"
          limits:
            memory: "4Gi"
            cpu: "2"
---
apiVersion: v1
kind: Service
metadata:
  name: ui-test-service
  namespace: ci-cd
spec:
  selector:
    app: ui-test
  ports:
  - port: 80
    targetPort: 3000
  type: ClusterIP

✅ 部署命令: kubectl apply -f k8s-deployment.yaml

5. 核心功能说明

5.1 测试用例管理

测试用例按照以下结构组织：

test-cases/
├── smoke/              # 冒烟测试
│   ├── login.spec.ts
│   ├── navigation.spec.ts
│   └── search.spec.ts
├── regression/         # 回归测试
│   ├── checkout-flow.spec.ts
│   ├── user-management.spec.ts
│   └── order-processing.spec.ts
├── integration/        # 集成测试
│   ├── api-ui-integration.spec.ts
│   └── third-party-services.spec.ts
├── visual/             # 视觉回归测试
│   ├── homepage-comparison.spec.ts
│   └── responsive-design.spec.ts
└── accessibility/      # 无障碍测试
    ├── wcag-compliance.spec.ts
    └── screen-reader.spec.ts

5.2 智能执行引擎

⚡ 并行执行：支持多浏览器、多设备、多环境的并行测试执行，大幅提升测试效率。

5.3 AI 智能分析

基于 Claude Code 的缺陷自动分类和根因分析：

自动识别失败原因（定位器问题、时序问题、数据问题、环境问题、真实缺陷）
提供修复建议和代码片段
置信度评分
自动创建 JIRA 缺陷单

5.4 视觉回归测试

检测 UI 变化，确保视觉一致性：

全页面截图对比
组件级视觉验证
响应式设计检查
可配置的差异阈值

5.5 无障碍测试

确保应用符合 WCAG 标准：

WCAG 2.1 A/AA 合规性检查
键盘导航测试
屏幕阅读器兼容性
颜色对比度验证

6. 使用流程详解

6.1 完整执行流程

Step 1: 触发测试
Code Commit → Jenkins Pipeline
Manual Trigger via UI
Scheduled Execution (Cron)

⬇

Step 2: 环境准备
Pull Docker Image
Start Test Containers
Configure Test Environment

⬇

Step 3: 执行测试用例
Load Test Cases
Parallel Execution
Capture Screenshots/Videos

⬇

Step 4: AI 分析
Analyze Failures
Classify Defects
Generate Recommendations

⬇

Step 5: 生成报告
HTML Report
Allure Dashboard
JUnit XML

⬇

Step 6: 通知与集成
Send Notifications
Update JIRA Tickets
Block/Allow Deployment

6.2 命令行操作

# 运行所有测试
npm run test:e2e

# 运行特定测试套件
npm run test:smoke
npm run test:regression
npm run test:visual

# 运行单个测试文件
npx playwright test test-cases/smoke/login.spec.ts

# 运行特定测试用例
npx playwright test --grep "TC001"

# 调试模式
npx playwright test --debug

# 生成报告
npx playwright show-report

7. 各研发角色操作指南

📊 产品经理 (Product Manager)

职责：验收功能是否符合 PRD 需求，查看测试报告确认功能完整性

操作流程：

访问 Jenkins 查看最新测试报告
检查 Smoke Tests 通过率 (目标：100%)
审查关键业务流程测试结果
在 JIRA 中标记验收状态

🎨 UI/UX设计师

职责：视觉回归测试基准确认，响应式设计验证

操作流程：

访问 Allure Dashboard 查看视觉对比
审核设计变更影响
更新视觉基准图：npx playwright test --update-snapshots
运行无障碍测试：npm run test:a11y

💻 前端开发工程师

职责：编写组件级测试用例，修复 UI 测试发现的缺陷

操作流程：

本地运行相关测试：npx playwright test --grep "component-name" --debug
维护 Page Object 模型
修复缺陷后验证：npx playwright test --last-failed

🔧 测试工程师 (QA Engineer)

职责：编写和维护测试用例，分析测试失败原因，管理测试环境

操作流程：

创建新测试用例：npm run generate:test -- --name="feature-name"
执行完整测试套件：npm run test:full
查看 AI 分析报告：npm run ai:report
自动生成 JIRA 缺陷单

🚀 DevOps 工程师

职责：维护 CI/CD 流水线，管理测试基础设施

操作流程：

配置 Jenkins Pipeline
设置监控告警规则
优化测试执行性能
管理系统健康度

8. API 接口文档

8.1 测试执行 API

触发测试执行

POST /api/v1/tests/execute
Content-Type: application/json
Authorization: Bearer {token}

{
  "testSuite": "regression",
  "environment": "staging",
  "browsers": ["chromium", "firefox"],
  "parallelWorkers": 5,
  "tags": ["@critical", "@checkout"],
  "notifyOnComplete": true
}

查询执行状态

GET /api/v1/tests/execute/{executionId}/status
Authorization: Bearer {token}

8.2 测试报告 API

GET /api/v1/reports/{executionId}
Authorization: Bearer {token}
Accept: application/json

8.3 AI 分析 API

POST /api/v1/ai/analyze
Content-Type: application/json
Authorization: Bearer {token}

{
  "testCaseId": "TC045",
  "errorMessage": "Timeout 30000ms exceeded",
  "stackTrace": "...",
  "screenshot": "base64_encoded_image",
  "context": {...}
}

9. 常见问题与故障排查

9.1 测试执行问题

⚠️ 问题 1: 测试超时失败

现象: Error: Timeout 30000ms exceeded while waiting for element

解决方案:

增加全局超时配置
针对特定步骤增加超时
使用轮询等待机制

⚠️ 问题 2: 元素定位失败

现象: Error: ElementHandle.textContent: Error: Could not find element

解决方案:

使用更稳定的定位器 (getByRole, getByTestId)
添加适当的等待逻辑
使用 Frame Locator 处理 iframe

9.2 环境问题

⚠️ 问题 3: 浏览器启动失败

解决方案:

# 重新安装浏览器
npx playwright install --force

# 安装系统依赖
npx playwright install-deps

10. 最佳实践

10.1 测试用例设计原则

FIRST 原则：

Fast: 测试应该快速执行 (< 10s per test)
Independent: 测试之间相互独立
Repeatable: 在任何环境下结果一致
Self-validating: 自动判断通过/失败
Timely: 与功能开发同步进行

10.2 Page Object 模式

✨ 推荐使用 Page Object 模式封装页面交互逻辑，提高测试可维护性和复用性。

10.3 测试数据管理

使用 Factory 模式创建测试数据，确保测试独立性和可重复性。

10.4 人机协同最佳实践

对于关键路径测试、视觉回归测试和无障碍测试，设置人工审核节点，确保质量。

10.5 持续改进

测试健康度指标 95%

每周分析 top 10 失败测试
每月优化测试套件结构
每季度评估新技术和工具