diff --git a/README.md b/README.md index ac091a8..9bb978d 100644 --- a/README.md +++ b/README.md @@ -168,7 +168,8 @@ QaAutomationHub/ ├── fleet_config.yml # Fleet 全局配置 ├── docs/ # 文档 │ ├── USER_GUIDE.md # 用户指南 -│ └── MAINTENANCE_GUIDE.md # 维护指南 +│ ├── MAINTENANCE_GUIDE.md # 维护指南 +│ └── EXECUTE_SETUP_GUIDE.md # Execute 战区环境配置指南（PC/Android/iOS） └── output/ # 执行产物 ``` @@ -190,6 +191,7 @@ QaAutomationHub/ - **用户指南**: [docs/USER_GUIDE.md](docs/USER_GUIDE.md) — 怎么用 - **维护指南**: [docs/MAINTENANCE_GUIDE.md](docs/MAINTENANCE_GUIDE.md) — 怎么维护 +- **Execute 环境配置**: [docs/EXECUTE_SETUP_GUIDE.md](docs/EXECUTE_SETUP_GUIDE.md) — PC/Android/iOS 环境搭建 - **设计文档**: [docs/superpowers/specs/2026-07-09-agentic-qe-fleet-design.md](docs/superpowers/specs/2026-07-09-agentic-qe-fleet-design.md) — 架构说明 - **Codex CLI 规则**: [AGENTS.md](AGENTS.md) - **Fleet Skill**: [.claude/skills/qe_fleet/SKILL.md](.claude/skills/qe_fleet/SKILL.md) diff --git a/docs/EXECUTE_SETUP_GUIDE.md b/docs/EXECUTE_SETUP_GUIDE.md new file mode 100644 index 0000000..179245a --- /dev/null +++ b/docs/EXECUTE_SETUP_GUIDE.md @@ -0,0 +1,564 @@ +# Execute 战区环境配置指南 + +> 适用版本: Agentic QE Fleet v2.1.0+ | 最后更新: 2026-07-09 + +本文档详细说明如何配置 PC、Android、iOS 三端的自动化测试执行环境，配完后 `/qe-fleet execute` 即可自动运行测试并产出截图报告。 + +--- + +## 目录 + +1. [架构概览](#1-架构概览) +2. [PC Web 端配置 (Playwright)](#2-pc-web-端配置-playwright) +3. [Android 端配置 (Appium)](#3-android-端配置-appium) +4. [iOS 端配置 (Appium + XCUITest)](#4-ios-端配置-appium--xcuitest) +5. [验证环境](#5-验证环境) +6. [运行 Execute 战区](#6-运行-execute-战区) +7. [常见问题](#7-常见问题) + +--- + +## 1. 架构概览 + +``` +┌─────────────────────────────────────────────────────────┐ +│ Execute 战区 │ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌───────────────┐ │ +│ │ web-executor │ │mobile-executor│ │result-reporter│ │ +│ │ Playwright │ │ Appium │ │ AI 视觉对比 │ │ +│ └──────┬───────┘ └──────┬───────┘ └───────┬───────┘ │ +│ │ │ │ │ +│ ┌────▼────┐ ┌─────▼─────┐ ┌────▼─────┐ │ +│ │Chromium │ │ Android │ │ 截图对比 │ │ +│ │Firefox │ │ iOS │ │ 结论报告 │ │ +│ │WebKit │ │ 真机/模拟器│ │ │ │ +│ └─────────┘ └───────────┘ └───────────┘ │ +└─────────────────────────────────────────────────────────┘ +``` + +**PC Web**: Playwright 直接驱动浏览器，本地运行，无需额外设备。 +**移动端**: Appium Server 作为中间层，一端连接测试脚本，一端连接真机/模拟器。 + +--- + +## 2. PC Web 端配置 (Playwright) + +### 2.1 安装 Playwright + +在你的项目机器上执行： + +```bash +# 进入项目目录 +cd QaAutomationHub + +# 激活虚拟环境 +source .venv/bin/activate # macOS/Linux +# 或 +.\.venv\Scripts\activate # Windows PowerShell + +# 安装 Playwright Python 包 +pip install playwright + +# 安装浏览器驱动（Chromium / Firefox / WebKit） +playwright install chromium +playwright install firefox +playwright install webkit + +# 验证安装 +python3 -c "from playwright.sync_api import sync_playwright; print('✅ Playwright 就绪')" +``` + +### 2.2 安装系统依赖（仅 Linux） + +```bash +# Ubuntu/Debian +playwright install-deps + +# 这会自动安装 libgtk-3、libnotify、libnss3 等依赖 +``` + +### 2.3 需要准备的信息 + +执行前你需要知道以下信息，Fleet 生成的脚本会用到： + +| 信息 | 说明 | 示例 | +|------|------|------| +| 测试环境地址 | Web 应用的 URL | `https://test.example.com` | +| 测试账号 | 不同角色的账号/密码 | `admin / test123` | +| 页面关键元素 | 按钮文字、输入框 placeholder | 可以后续从截图调试 | + +这些信息在运行 Fleet 前，建议先补充到： +- `knowledge_base/00_project/project_profile.md` — 项目 URL、环境信息 +- `output/analysis/{需求名}_测试数据.md` — 测试账号数据 + +--- + +## 3. Android 端配置 (Appium) + +### 3.1 安装 Java JDK + +Appium 依赖 Java 运行环境。 + +```bash +# macOS +brew install openjdk@17 + +# Windows +# 下载安装: https://adoptium.net/download/ +# 安装后设置环境变量 JAVA_HOME + +# Linux (Ubuntu) +sudo apt install openjdk-17-jdk + +# 验证 +java -version +# 输出: openjdk version "17.x.x" ... +``` + +### 3.2 安装 Android SDK + +#### 方式一：安装 Android Studio（推荐） + +1. 下载 Android Studio: https://developer.android.com/studio +2. 安装后打开，进入 `SDK Manager` +3. 安装以下组件： + - **Android SDK Platform** (选最新稳定版，如 API 34) + - **Android SDK Platform-Tools** (含 adb) + - **Android SDK Build-Tools** + - **Android Emulator** + 一个系统镜像 (如 Pixel 6 + API 34) + +#### 方式二：仅安装命令行工具 + +```bash +# macOS +brew install android-platform-tools + +# Linux +sudo apt install android-tools-adb android-tools-fastboot + +# Windows +# 下载 SDK Platform Tools: https://developer.android.com/tools/releases/platform-tools +# 解压到 C:\android-sdk\platform-tools，加入 PATH +``` + +### 3.3 设置环境变量 + +```bash +# 添加到 ~/.bashrc 或 ~/.zshrc + +# Android SDK 路径 (macOS 默认) +export ANDROID_HOME=~/Library/Android/sdk + +# Android SDK 路径 (Linux 默认) +export ANDROID_HOME=~/Android/Sdk + +# Android SDK 路径 (Windows 默认) +# $env:ANDROID_HOME = "C:\Users\<用户名>\AppData\Local\Android\Sdk" + +export PATH=$PATH:$ANDROID_HOME/platform-tools +export PATH=$PATH:$ANDROID_HOME/tools +export PATH=$PATH:$ANDROID_HOME/tools/bin +``` + +### 3.4 连接 Android 设备 + +#### 选项 A：USB 真机 + +```bash +# 1. 手机开启开发者模式 +# 设置 → 关于手机 → 连续点击"版本号"7次 + +# 2. 开启 USB 调试 +# 设置 → 开发者选项 → USB 调试 ✅ +# 设置 → 开发者选项 → USB 安装 ✅ (部分手机需要) + +# 3. USB 连接电脑，手机上点击"允许 USB 调试" + +# 4. 验证连接 +adb devices +# 输出: +# List of devices attached +# XXXXXXXX device ← 看到 device 表示连接成功 +``` + +#### 选项 B：Android 模拟器 + +```bash +# 使用 Android Studio 创建模拟器: +# Android Studio → Device Manager → Create Device +# 推荐: Pixel 6, Android 14 (API 34) + +# 或命令行创建（需先安装 system image） +sdkmanager "system-images;android-34;google_apis;x86_64" +avdmanager create avd -n test_device -k "system-images;android-34;google_apis;x86_64" + +# 启动模拟器 +emulator -avd test_device & + +# 验证 +adb devices +# 输出: +# emulator-5554 device +``` + +### 3.5 安装 Appium + +```bash +# 安装 Node.js（如未安装） +# macOS: brew install node +# Windows: https://nodejs.org/ +# Linux: sudo apt install nodejs npm + +# 安装 Appium Server +npm install -g appium + +# 安装 Android 驱动 +appium driver install uiautomator2 + +# 验证 +appium --version +# 输出: 2.x.x + +# 安装 Python 客户端 +pip install Appium-Python-Client +``` + +### 3.6 获取 APP 信息 + +```bash +# 获取已安装应用的包名和 Activity +adb shell pm list packages | grep <关键词> + +# 获取当前前台应用的包名和 Activity +adb shell dumpsys window | grep mCurrentFocus + +# 输出示例: +# mCurrentFocus=Window{... com.example.app/com.example.app.MainActivity} +# 包名: com.example.app +# Activity: .MainActivity +``` + +记下这些信息，后续配置到 Fleet 生成的脚本中。 + +--- + +## 4. iOS 端配置 (Appium + XCUITest) + +> ⚠️ iOS 自动化测试**必须**在 macOS 上运行，且需要 Apple Developer 账号。 + +### 4.1 安装 Xcode + +```bash +# 从 Mac App Store 安装 Xcode +# https://apps.apple.com/app/xcode/id497799835 + +# 安装 Command Line Tools +xcode-select --install + +# 验证 +xcodebuild -version +``` + +### 4.2 安装 iOS 开发工具 + +```bash +# 安装 Carthage（XCUITest 驱动依赖） +brew install carthage + +# 安装 ios-deploy（真机部署） +brew install ios-deploy + +# 安装 libimobiledevice（iOS 设备通信） +brew install libimobiledevice + +# 安装 Appium（与 Android 共用） +npm install -g appium + +# 安装 iOS 驱动 +appium driver install xcuitest +``` + +### 4.3 连接 iOS 设备 + +#### 选项 A：iOS 真机 + +```bash +# 1. iPhone 连接 Mac（USB） +# 手机弹出"要信任此电脑吗？" → 点击"信任" + +# 2. 验证连接 +idevice_id -l +# 输出: <设备 UDID> + +# 3. 获取设备信息 +ideviceinfo -k DeviceName +ideviceinfo -k ProductVersion + +# 4. 开启开发者模式 +# 设置 → 隐私与安全性 → 开发者模式 ✅ +# iOS 16+ 需要此步骤 +``` + +#### 选项 B：iOS 模拟器 + +```bash +# Xcode 自带模拟器，查看可用设备 +xcrun simctl list devices + +# 启动指定模拟器 +xcrun simctl boot "iPhone 15" + +# 或通过 Xcode: +# Xcode → Open Developer Tool → Simulator +``` + +### 4.4 配置 WebDriverAgent（仅真机） + +iOS 真机需要签名 WebDriverAgent： + +```bash +# 1. 找到 WebDriverAgent 项目 +# 路径通常在: ~/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent/ + +# 2. 用 Xcode 打开 +open ~/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj + +# 3. 签名配置（在 Xcode 中操作）: +# - 选择 WebDriverAgentRunner target +# - Signing & Capabilities → Team → 选择你的 Apple ID +# - 修改 Bundle Identifier（如 com.yourteam.WebDriverAgentRunner） +# - 同样配置 WebDriverAgentLib target + +# 4. 构建测试 +# Product → Test (Cmd+U) +``` + +### 4.5 获取 iOS APP 信息 + +```bash +# iOS Bundle ID 通常在 Xcode 项目中查看，或通过以下命令： +ideviceinstaller -l | grep <关键词> + +# 如果没有 ideviceinstaller: +brew install ideviceinstaller +``` + +--- + +## 5. 验证环境 + +### 5.1 一键验证脚本 + +创建并运行以下验证脚本： + +```bash +# 在项目目录创建验证脚本 +cat > /tmp/verify_execute_env.sh << 'EOF' +#!/bin/bash +echo "========================================" +echo " Execute 战区环境验证" +echo "========================================" + +# PC Web +echo "" +echo "── PC Web (Playwright) ──" +python3 -c "from playwright.sync_api import sync_playwright; print('✅ Playwright Python 包')" 2>/dev/null || echo "❌ Playwright 未安装" +which chromium 2>/dev/null && echo "✅ Chromium" || echo "⚠️ Chromium 浏览器未找到（playwright install chromium）" + +# Android +echo "" +echo "── Android (Appium) ──" +java -version 2>&1 | head -1 && echo "✅ Java" || echo "❌ Java 未安装" +adb devices 2>/dev/null | grep -q "device" && echo "✅ Android 设备已连接" || echo "⚠️ 无 Android 设备连接" +appium --version 2>/dev/null && echo "✅ Appium Server" || echo "❌ Appium 未安装" + +# iOS (仅 macOS) +echo "" +echo "── iOS (Appium + XCUITest) ──" +if [[ "$OSTYPE" == "darwin"* ]]; then + xcodebuild -version 2>/dev/null && echo "✅ Xcode" || echo "❌ Xcode 未安装" + idevice_id -l 2>/dev/null | grep -q . && echo "✅ iOS 设备已连接" || echo "⚠️ 无 iOS 设备连接" +else + echo "⏭️ 跳过（iOS 测试仅支持 macOS）" +fi + +# Fleet Agent +echo "" +echo "── Fleet Agent ──" +python3 scripts/fleet_runner.py validate 2>/dev/null && echo "✅ Agent 就绪" || echo "❌ Agent 验证失败" + +echo "" +echo "========================================" +echo " 验证完成" +echo "========================================" +EOF + +chmod +x /tmp/verify_execute_env.sh +bash /tmp/verify_execute_env.sh +``` + +### 5.2 手动逐项验证 + +| 检查项 | 命令 | 预期输出 | +|--------|------|----------| +| Playwright | `python3 -c "from playwright.sync_api import sync_playwright; print('OK')"` | `OK` | +| Chromium | `python3 -c "from playwright.sync_api import sync_playwright; p=sync_playwright().start(); b=p.chromium.launch(); b.close(); print('OK')"` | `OK` | +| adb | `adb devices` | 列出设备 | +| Appium | `appium --version` | `2.x.x` | +| Agent | `python3 scripts/fleet_runner.py validate` | `✅ 所有 Agent prompt 就绪` | + +--- + +## 6. 运行 Execute 战区 + +### 6.1 快速运行 + +```bash +# 确保虚拟环境已激活 +source .venv/bin/activate + +# 方式一：全流程（会自动走到 Execute 战区） +/qe-fleet run source_docs/requirements_raw/你的需求.docx + +# 方式二：只跑 Execute 战区（需要前面战区已完成） +/qe-fleet execute source_docs/requirements_raw/你的需求.docx +``` + +### 6.2 启动 Appium Server（移动端需要） + +```bash +# 新开一个终端窗口 +appium --allow-insecure chromedriver_autodownload + +# 或后台运行 +appium --allow-insecure chromedriver_autodownload & +``` + +### 6.3 手动运行生成的脚本 + +```bash +# 查看 Fleet 生成的脚本 +ls output/execution/<需求名>/ + +# 运行 PC Web 测试 +python3 output/execution/<需求名>/playwright_tests.py + +# 运行移动端测试（需先启动 Appium Server） +python3 output/execution/<需求名>/appium_tests.py + +# 查看截图 +ls output/screenshots/<需求名>/ + +# 查看执行报告 +cat output/execution/<需求名>_执行报告.md +``` + +### 6.4 修改脚本配置 + +Fleet 生成的脚本包含占位符，运行前需要修改： + +**Playwright 脚本** (`playwright_tests.py`): +```python +# ⚠️ 需要修改的行 +BASE_URL = "http://localhost:3000" # → 改为测试环境地址 +# 测试账号 → 填入真实账号 +# CSS Selector → 按实际页面元素修改 +``` + +**Appium 脚本** (`appium_tests.py`): +```python +# ⚠️ 需要修改的行 +APPIUM_HOST = "http://localhost:4723" # Appium Server 地址 + +ANDROID_CAPS = { + "deviceName": "Android Emulator", # → 改为你的设备名 + "appPackage": "com.example.app", # → 改为实际包名 + "appActivity": ".MainActivity", # → 改为实际 Activity +} + +IOS_CAPS = { + "deviceName": "iPhone 15", # → 改为你的设备 + "bundleId": "com.example.app", # → 改为实际 Bundle ID +} +``` + +--- + +## 7. 常见问题 + +### Q1: `adb devices` 显示 `unauthorized` + +**解决**: 手机上会弹出"允许 USB 调试"对话框，点击允许。如果没有弹出，执行： +```bash +adb kill-server +adb start-server +adb devices +``` + +### Q2: 模拟器启动后 Appium 找不到元素 + +**解决**: 确保 APP 已安装到模拟器： +```bash +adb install path/to/app.apk +``` + +### Q3: iOS 真机 WebDriverAgent 签名失败 + +**解决**: 在 Xcode 中为 WebDriverAgentRunner 和 WebDriverAgentLib 两个 target 配置 Team 和修改 Bundle ID。 + +### Q4: Playwright 截图中文乱码 + +**解决**: Linux 系统需要安装中文字体： +```bash +sudo apt install fonts-noto-cjk +``` + +### Q5: Appium 报 `chrome-driver` 相关错误 + +**解决**: Android WebView/H5 测试需要匹配的 chromedriver： +```bash +appium --allow-insecure chromedriver_autodownload +``` + +### Q6: 部分设备连接后 `adb` 不识别 + +**解决**: +```bash +# 检查 USB 连接模式（手机通知栏） +# 选择 "传输文件 (MTP)" 或 "PTP" 模式，不要选 "仅充电" + +# Windows 可能需要安装 OEM USB 驱动 +# 华为/小米/OPPO 各自官网有提供 +``` + +### Q7: 如何检查我的手机是否支持自动化？ + +```bash +# Android: 只要 adb devices 能看到设备就支持 +adb devices + +# iOS: 需要 iOS 11+ 且开启开发者模式 +idevice_id -l +``` + +--- + +## 附录：最小化配置路径 + +如果你只想快速跑通 PC Web 端（跳过移动端）： + +```bash +# 1. 安装 Playwright +pip install playwright +playwright install chromium + +# 2. 关闭移动端战区 +# 编辑 fleet_config.yml +# battle_zones.execute.mobile_platforms: [] + +# 3. 运行 +/qe-fleet run source_docs/requirements_raw/需求.docx +``` + +这是最快的验证路径，不需要配置 Java、Android SDK、Appium。