Yb-QaAutomationHub/docs/EXECUTE_SETUP_GUIDE.md

Execute 战区环境配置指南

适用版本: Agentic QE Fleet v2.1.0+ | 最后更新: 2026-07-09

本文档详细说明如何配置 PC、Android、iOS 三端的自动化测试执行环境，配完后 /qe-fleet execute 即可自动运行测试并产出截图报告。

---

目录

1. 一键配置（Windows 用户优先看这里）
2. 架构概览
3. PC Web 端配置 (Playwright)
4. Android 端配置 (Appium)
5. iOS 端配置 (Appium + XCUITest)
6. 验证环境
7. 运行 Execute 战区
8. 常见问题

---

一键配置（Windows 用户优先看这里）

如果你用的是 Windows，我们提供了一键配置脚本，自动处理 PATH、环境变量、验证所有依赖：

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

在你的项目机器上执行：

# 进入项目目录
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）

# 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 运行环境。

# 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)

方式二：仅安装命令行工具

# 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 设置环境变量

# 添加到 ~/.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 真机

# 1. 手机开启开发者模式
#    设置 → 关于手机 → 连续点击"版本号"7次

# 2. 开启 USB 调试
#    设置 → 开发者选项 → USB 调试 ✅
#    设置 → 开发者选项 → USB 安装 ✅ (部分手机需要)

# 3. USB 连接电脑，手机上点击"允许 USB 调试"

# 4. 验证连接
adb devices
# 输出:
# List of devices attached
# XXXXXXXX    device    ← 看到 device 表示连接成功

选项 B：Android 模拟器

# 使用 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

# 安装 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 信息

# 获取已安装应用的包名和 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

# 从 Mac App Store 安装 Xcode
# https://apps.apple.com/app/xcode/id497799835

# 安装 Command Line Tools
xcode-select --install

# 验证
xcodebuild -version

4.2 安装 iOS 开发工具

# 安装 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 真机

# 1. iPhone 连接 Mac（USB）
#    手机弹出"要信任此电脑吗？" → 点击"信任"

# 2. 验证连接
idevice_id -l
# 输出: <设备 UDID>

# 3. 获取设备信息
ideviceinfo -k DeviceName
ideviceinfo -k ProductVersion

# 4. 开启开发者模式
#    设置 → 隐私与安全性 → 开发者模式 ✅
#    iOS 16+ 需要此步骤

选项 B：iOS 模拟器

# Xcode 自带模拟器，查看可用设备
xcrun simctl list devices

# 启动指定模拟器
xcrun simctl boot "iPhone 15"

# 或通过 Xcode:
# Xcode → Open Developer Tool → Simulator

4.4 配置 WebDriverAgent（仅真机）

iOS 真机需要签名 WebDriverAgent：

# 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 信息

# iOS Bundle ID 通常在 Xcode 项目中查看，或通过以下命令：
ideviceinstaller -l | grep <关键词>

# 如果没有 ideviceinstaller:
brew install ideviceinstaller

---

5. 验证环境

5.1 一键验证脚本

创建并运行以下验证脚本：

# 在项目目录创建验证脚本
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 快速运行

# 确保虚拟环境已激活
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（移动端需要）

# 新开一个终端窗口
appium --allow-insecure "uiautomator2:chromedriver_autodownload"

# 或后台运行
appium --allow-insecure "uiautomator2:chromedriver_autodownload" &

6.3 手动运行生成的脚本

# 查看 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):

# ⚠️ 需要修改的行
BASE_URL = "http://localhost:3000"  # → 改为测试环境地址
# 测试账号 → 填入真实账号
# CSS Selector → 按实际页面元素修改

Appium 脚本 (appium_tests.py):

# ⚠️ 需要修改的行
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 调试"对话框，点击允许。如果没有弹出，执行：

adb kill-server
adb start-server
adb devices

Q2: 模拟器启动后 Appium 找不到元素

解决: 确保 APP 已安装到模拟器：

adb install path/to/app.apk

Q3: iOS 真机 WebDriverAgent 签名失败

解决: 在 Xcode 中为 WebDriverAgentRunner 和 WebDriverAgentLib 两个 target 配置 Team 和修改 Bundle ID。

Q4: Playwright 截图中文乱码

解决: Linux 系统需要安装中文字体：

sudo apt install fonts-noto-cjk

Q5: Appium 报 chrome-driver 相关错误

解决: Android WebView/H5 测试需要匹配的 chromedriver。 注意 Appium v3.x 和 v2.x 的参数格式不同：

# Appium v3.x（当前版本） — 格式: 驱动名:功能名
appium --allow-insecure "uiautomator2:chromedriver_autodownload"

# Appium v2.x — 旧格式
appium --allow-insecure chromedriver_autodownload

也可以用项目自带的脚本一键启动：

scripts\start_appium.bat

Q6: 部分设备连接后 adb 不识别

解决:

# 检查 USB 连接模式（手机通知栏）
# 选择 "传输文件 (MTP)" 或 "PTP" 模式，不要选 "仅充电"

# Windows 可能需要安装 OEM USB 驱动
# 华为/小米/OPPO 各自官网有提供

Q7: 如何检查我的手机是否支持自动化？

# Android: 只要 adb devices 能看到设备就支持
adb devices

# iOS: 需要 iOS 11+ 且开启开发者模式
idevice_id -l

---

附录：最小化配置路径

如果你只想快速跑通 PC Web 端（跳过移动端）：

# 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。