xst
b958b75899
- scripts/setup_execute_env.bat: auto-detect Android SDK, set PATH permanently, validate all deps - scripts/start_appium.bat: one-click Appium Server startup with v3-compatible params - Fix all 'appium --allow-insecure' commands for Appium v3 (driver:feature format) - Add Windows quick-start section to EXECUTE_SETUP_GUIDE.md
603 lines
16 KiB
Markdown
603 lines
16 KiB
Markdown
# Execute 战区环境配置指南
|
||
|
||
> 适用版本: Agentic QE Fleet v2.1.0+ | 最后更新: 2026-07-09
|
||
|
||
本文档详细说明如何配置 PC、Android、iOS 三端的自动化测试执行环境，配完后 `/qe-fleet execute` 即可自动运行测试并产出截图报告。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [一键配置（Windows 用户优先看这里）](#一键配置windows-用户优先看这里)
|
||
2. [架构概览](#1-架构概览)
|
||
3. [PC Web 端配置 (Playwright)](#2-pc-web-端配置-playwright)
|
||
4. [Android 端配置 (Appium)](#3-android-端配置-appium)
|
||
5. [iOS 端配置 (Appium + XCUITest)](#4-ios-端配置-appium--xcuitest)
|
||
6. [验证环境](#5-验证环境)
|
||
7. [运行 Execute 战区](#6-运行-execute-战区)
|
||
8. [常见问题](#7-常见问题)
|
||
|
||
---
|
||
|
||
## 一键配置（Windows 用户优先看这里）
|
||
|
||
如果你用的是 Windows，我们提供了一键配置脚本，自动处理 PATH、环境变量、验证所有依赖：
|
||
|
||
```batch
|
||
cd QaAutomationHub
|
||
scripts\setup_execute_env.bat
|
||
```
|
||
|
||
这个脚本会：
|
||
- 自动检测 Android SDK 路径
|
||
- 设置 `ANDROID_HOME`、`sdkmanager`、`emulator`、`adb` 到 PATH
|
||
- 永久写入系统 PATH（以后开新窗口也生效）
|
||
- 逐项验证 Python / Playwright / Java / adb / Appium / Agent
|
||
- 打印常用命令速查卡片
|
||
|
||
**你要手动做的只剩下**：
|
||
|
||
1. 装 Playwright 浏览器（如果脚本提示未安装）
|
||
2. 创建 Android 模拟器（只需一次）
|
||
3. 启动 Appium Server
|
||
|
||
下面手动步骤为 macOS / Linux 用户和需要精细控制的场景准备。
|
||
|
||
---
|
||
|
||
## 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 "uiautomator2:chromedriver_autodownload"
|
||
|
||
# 或后台运行
|
||
appium --allow-insecure "uiautomator2: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。
|
||
注意 Appium v3.x 和 v2.x 的参数格式不同：
|
||
|
||
```bash
|
||
# Appium v3.x（当前版本） — 格式: 驱动名:功能名
|
||
appium --allow-insecure "uiautomator2:chromedriver_autodownload"
|
||
|
||
# Appium v2.x — 旧格式
|
||
appium --allow-insecure chromedriver_autodownload
|
||
```
|
||
|
||
也可以用项目自带的脚本一键启动：
|
||
```batch
|
||
scripts\start_appium.bat
|
||
```
|
||
|
||
### 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。
|