mirror of
https://github.com/httprunner/httprunner.git
synced 2026-05-12 02:21:29 +08:00
329 lines
12 KiB
Markdown
329 lines
12 KiB
Markdown
# HttpRunner UIXT 模块
|
||
|
||
## 🚀 概述
|
||
|
||
HttpRunner UIXT（UI eXtended Testing）是 HttpRunner v4.3.0+ 引入的跨平台 UI 自动化测试模块，提供统一的 API 接口支持多种平台的 UI 自动化测试，并集成了先进的 AI 能力，实现真正的智能化 UI 自动化测试。
|
||
|
||
### 核心特性
|
||
|
||
- **🎯 跨平台支持**: Android、iOS、HarmonyOS、Web 浏览器统一接口
|
||
- **🤖 AI 智能化**: 集成大语言模型和计算机视觉，支持自然语言驱动的 UI 操作
|
||
- **🔧 MCP 协议**: 基于 Model Context Protocol 的标准化工具接口
|
||
- **📱 多设备管理**: 支持真机、模拟器、浏览器的统一管理
|
||
- **🎨 丰富操作**: 触摸、滑动、输入、应用管理等完整操作集
|
||
- **📊 智能识别**: OCR 文本识别、UI 元素检测、弹窗识别
|
||
|
||
## 🏗️ 核心架构
|
||
|
||
### 整体架构图
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ HttpRunner UIXT │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ XTDriver (扩展驱动) │
|
||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||
│ │ IDriver │ │ AI Services │ │ MCP Server │ │
|
||
│ │ (核心驱动) │ │ (AI 能力) │ │ (工具协议) │ │
|
||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ 设备驱动层 │
|
||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||
│ │ Android Driver │ │ iOS Driver │ │ Browser Driver │ │
|
||
│ │ (ADB/UIA2) │ │ (WDA) │ │ (WebDriver) │ │
|
||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ 设备层 │
|
||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||
│ │ Android Device │ │ iOS Device │ │ Browser Device │ │
|
||
│ │ (真机/模拟器) │ │ (真机/模拟器) │ │ (浏览器) │ │
|
||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 核心设计思路
|
||
|
||
#### 1. 分层架构设计
|
||
- **设备层**: 抽象不同平台的设备管理
|
||
- **驱动层**: 统一不同平台的操作接口
|
||
- **扩展层**: 提供 AI 和高级功能
|
||
- **协议层**: 标准化的工具调用接口
|
||
|
||
#### 2. 接口统一化
|
||
所有平台都实现相同的 `IDriver` 接口，确保操作的一致性：
|
||
|
||
```go
|
||
type IDriver interface {
|
||
// 设备信息和状态
|
||
Status() (types.DeviceStatus, error)
|
||
DeviceInfo() (types.DeviceInfo, error)
|
||
WindowSize() (types.Size, error)
|
||
ScreenShot(opts ...option.ActionOption) (*bytes.Buffer, error)
|
||
|
||
// 基础操作
|
||
TapXY(x, y float64, opts ...option.ActionOption) error
|
||
Swipe(fromX, fromY, toX, toY float64, opts ...option.ActionOption) error
|
||
Input(text string, opts ...option.ActionOption) error
|
||
|
||
// 应用管理
|
||
AppLaunch(packageName string) error
|
||
AppTerminate(packageName string) (bool, error)
|
||
|
||
// ... 更多操作
|
||
}
|
||
```
|
||
|
||
#### 3. AI 能力集成
|
||
通过 `XTDriver` 扩展驱动集成 AI 服务：
|
||
|
||
```go
|
||
type XTDriver struct {
|
||
IDriver // 基础驱动能力
|
||
CVService ai.ICVService // 计算机视觉服务
|
||
LLMService ai.ILLMService // 大语言模型服务
|
||
}
|
||
```
|
||
|
||
#### 4. MCP 工具化
|
||
将所有操作封装为 MCP 工具，支持 AI 模型直接调用：
|
||
|
||
```go
|
||
type ActionTool interface {
|
||
Name() option.ActionName
|
||
Description() string
|
||
Options() []mcp.ToolOption
|
||
Implement() server.ToolHandlerFunc
|
||
}
|
||
```
|
||
|
||
## 📖 支持平台
|
||
|
||
### Android 平台
|
||
- **驱动方式**: ADB + UiAutomator2
|
||
- **支持设备**: 真机、模拟器
|
||
- **最低版本**: Android 5.0+
|
||
- **特色功能**: 应用管理、文件传输、日志捕获
|
||
|
||
### iOS 平台
|
||
- **驱动方式**: WebDriverAgent (WDA)
|
||
- **支持设备**: 真机、模拟器
|
||
- **最低版本**: iOS 10.0+
|
||
- **特色功能**: 应用管理、图片传输、性能监控
|
||
|
||
### HarmonyOS 平台
|
||
- **驱动方式**: HDC (HarmonyOS Device Connector)
|
||
- **支持设备**: 真机、模拟器
|
||
- **最低版本**: HarmonyOS 2.0+
|
||
- **特色功能**: 原生鸿蒙应用支持
|
||
|
||
### Web 浏览器
|
||
- **驱动方式**: WebDriver 协议
|
||
- **支持浏览器**: Chrome、Firefox、Safari、Edge
|
||
- **特色功能**: 多标签页管理、JavaScript 执行
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 环境准备
|
||
|
||
#### Android 环境
|
||
```bash
|
||
# 安装 Android SDK
|
||
export ANDROID_HOME=/path/to/android-sdk
|
||
export PATH=$PATH:$ANDROID_HOME/platform-tools
|
||
|
||
# 启用 USB 调试
|
||
adb devices
|
||
```
|
||
|
||
#### iOS 环境
|
||
```bash
|
||
# 安装 Xcode 和 WebDriverAgent
|
||
# 配置开发者证书
|
||
# 启动 WDA 服务
|
||
```
|
||
|
||
#### AI 服务配置
|
||
```bash
|
||
# 配置大语言模型服务
|
||
export OPENAI_BASE_URL=https://api.openai.com/v1
|
||
export OPENAI_API_KEY=your_api_key
|
||
|
||
# 配置计算机视觉服务
|
||
export VEDEM_IMAGE_URL=https://visual.volcengineapi.com
|
||
export VEDEM_IMAGE_AK=your_access_key
|
||
export VEDEM_IMAGE_SK=your_secret_key
|
||
```
|
||
|
||
### 2. 基础使用
|
||
|
||
#### 创建设备和驱动
|
||
```go
|
||
package main
|
||
|
||
import (
|
||
"github.com/httprunner/httprunner/v5/uixt"
|
||
"github.com/httprunner/httprunner/v5/uixt/option"
|
||
)
|
||
|
||
func main() {
|
||
// 创建 Android 设备
|
||
device, err := uixt.NewAndroidDevice(
|
||
option.WithSerialNumber("your_device_serial"),
|
||
)
|
||
if err != nil {
|
||
panic(err)
|
||
}
|
||
|
||
// 创建基础驱动
|
||
driver, err := uixt.NewUIA2Driver(device)
|
||
if err != nil {
|
||
panic(err)
|
||
}
|
||
|
||
// 创建扩展驱动（集成 AI 能力）
|
||
xtDriver, err := uixt.NewXTDriver(driver,
|
||
option.WithCVService(option.CVServiceTypeVEDEM),
|
||
option.WithLLMService(option.OPENAI_GPT_4O),
|
||
)
|
||
if err != nil {
|
||
panic(err)
|
||
}
|
||
|
||
// 初始化会话
|
||
err = xtDriver.Setup()
|
||
if err != nil {
|
||
panic(err)
|
||
}
|
||
defer xtDriver.TearDown()
|
||
}
|
||
```
|
||
|
||
#### 基础操作示例
|
||
```go
|
||
// 获取屏幕截图
|
||
screenshot, err := xtDriver.ScreenShot()
|
||
|
||
// 点击操作
|
||
err = xtDriver.TapXY(0.5, 0.5) // 相对坐标 (50%, 50%)
|
||
|
||
// 滑动操作
|
||
err = xtDriver.Swipe(0.5, 0.8, 0.5, 0.2) // 从下往上滑动
|
||
|
||
// 输入文本
|
||
err = xtDriver.Input("Hello World")
|
||
|
||
// 启动应用
|
||
err = xtDriver.AppLaunch("com.example.app")
|
||
```
|
||
|
||
#### AI 智能操作
|
||
```go
|
||
import "context"
|
||
|
||
// 使用自然语言执行操作
|
||
result, err := xtDriver.LLMService.Plan(context.Background(), &ai.PlanningOptions{
|
||
UserInstruction: "点击登录按钮",
|
||
Message: message,
|
||
Size: screenSize,
|
||
})
|
||
|
||
// 智能断言
|
||
assertResult, err := xtDriver.LLMService.Assert(context.Background(), &ai.AssertOptions{
|
||
Assertion: "登录按钮应该可见",
|
||
Screenshot: screenshot,
|
||
Size: screenSize,
|
||
})
|
||
|
||
// 智能查询
|
||
queryResult, err := xtDriver.LLMService.Query(context.Background(), &ai.QueryOptions{
|
||
Query: "提取页面中的所有文本内容",
|
||
Screenshot: screenshot,
|
||
Size: screenSize,
|
||
})
|
||
```
|
||
|
||
### 3. 高级配置
|
||
|
||
#### 混合模型配置
|
||
```go
|
||
// 为不同组件配置不同的最优模型
|
||
config := option.NewLLMServiceConfig(option.DOUBAO_1_5_THINKING_VISION_PRO_250428).
|
||
WithPlannerModel(option.DOUBAO_1_5_UI_TARS_250328). // UI理解用UI-TARS
|
||
WithAsserterModel(option.OPENAI_GPT_4O). // 推理用GPT-4O
|
||
WithQuerierModel(option.DEEPSEEK_R1_250528) // 查询用DeepSeek
|
||
|
||
xtDriver, err := uixt.NewXTDriver(driver,
|
||
option.WithLLMConfig(config),
|
||
)
|
||
```
|
||
|
||
#### 使用推荐配置
|
||
```go
|
||
configs := option.RecommendedConfigurations()
|
||
xtDriver, err := uixt.NewXTDriver(driver,
|
||
option.WithLLMConfig(configs["mixed_optimal"]),
|
||
)
|
||
```
|
||
|
||
## 📚 详细文档
|
||
|
||
### 核心文档
|
||
|
||
- **[设备管理](devices.md)** - 设备发现、连接、配置和管理
|
||
- **[驱动接口](drivers.md)** - 各平台驱动的功能和使用方法
|
||
- **[操作指南](operations.md)** - 详细的 UI 操作使用指南
|
||
- **[配置选项](options.md)** - 完整的配置参数说明
|
||
|
||
### AI 和工具
|
||
|
||
- **[AI 模块](ai.md)** - LLM 和 CV 服务的集成使用、智能规划、断言、查询
|
||
- **[MCP 工具](mcp-tools.md)** - MCP 协议和工具系统详解
|
||
|
||
### 快速导航
|
||
|
||
| 文档 | 内容概述 |
|
||
|------|----------|
|
||
| [设备管理](devices.md) | 设备发现、连接、多设备管理、故障排除、平台特有功能 |
|
||
| [驱动接口](drivers.md) | IDriver 接口、平台驱动、XTDriver 扩展、选择器类型 |
|
||
| [操作指南](operations.md) | 点击、滑动、输入、应用管理、屏幕操作 |
|
||
| [AI 模块](ai.md) | 智能规划、智能断言、智能查询、CV 识别、多模型配置 |
|
||
| [MCP 工具](mcp-tools.md) | 工具分类、实现方式、扩展开发 |
|
||
| [配置选项](options.md) | 设备配置、AI 配置、环境变量、最佳实践 |
|
||
|
||
## 🔧 依赖项目
|
||
|
||
### 核心依赖
|
||
- [electricbubble/gwda](https://github.com/electricbubble/gwda) - iOS WebDriverAgent 客户端
|
||
- [electricbubble/guia2](https://github.com/electricbubble/guia2) - Android UiAutomator2 客户端
|
||
- [mark3labs/mcp-go](https://github.com/mark3labs/mcp-go) - MCP 协议 Go 实现
|
||
|
||
### AI 服务依赖
|
||
- [cloudwego/eino](https://github.com/cloudwego/eino) - 统一的 LLM 接口
|
||
- 火山引擎 VEDEM - 计算机视觉服务
|
||
- OpenAI GPT-4O - 大语言模型服务
|
||
- 豆包系列模型 - 专业 UI 自动化模型
|
||
|
||
## 🤝 贡献指南
|
||
|
||
我们欢迎社区贡献！请查看以下资源：
|
||
|
||
- [贡献指南](CONTRIBUTING.md) - 如何参与项目贡献
|
||
- [开发环境搭建](development.md) - 开发环境配置
|
||
- [代码规范](coding-standards.md) - 代码风格和规范
|
||
- [测试指南](testing.md) - 测试编写和执行
|
||
|
||
## 📄 许可证
|
||
|
||
本项目采用 Apache 2.0 许可证，详情请查看 [LICENSE](LICENSE) 文件。
|
||
|
||
## 🙏 致谢
|
||
|
||
感谢以下开源项目的贡献：
|
||
- [appium-uiautomator2-server](https://github.com/appium/appium-uiautomator2-server) - Android 自动化基础
|
||
- [appium/WebDriverAgent](https://github.com/appium/WebDriverAgent) - iOS 自动化基础
|
||
- [danielpaulus/go-ios](https://github.com/danielpaulus/go-ios) - iOS 客户端库
|
||
|
||
---
|
||
|
||
**HttpRunner UIXT** - 让 UI 自动化测试更智能、更简单！
|