# go-mobile-uiautomator

一个用 Go 语言实现的 Android 移动设备 UI 自动化工具，通过 ADB 协议与 Android 设备通信，实现应用安装、文件传输和 UI 自动化测试功能。

## 特性

- ✅ **纯 Go 实现** - 不依赖外部 ADB 命令行工具
- ✅ **跨平台** - 支持 Windows/Linux/macOS
- ✅ **轻量级** - 无需安装 Android SDK
- ✅ **低延迟** - 直接 TCP 连接，无中间层
- ✅ **功能完整** - 支持设备发现、文件传输、APK 安装、Shell 执行
- ✅ **UIAutomator2** - 内置 UIAutomator2 服务支持

## 环境要求

- Go 1.25.1+
- 已启动的 ADB 服务器（Android SDK 自带）
- Android 设备已开启 USB 调试

## 安装

```bash
git clone https://github.com/zhuy1228/go-mobile-uiautomator.git
cd go-mobile-uiautomator
go mod download
```

## 快速开始

### 1. 基础设置

确保 ADB 服务器正在运行：

```bash
adb devices
```

### 2. 运行示例

修改 `cmd/main.go` 中的设备配置：

```go
const serial = "your-device-serial"  // 你的设备序列号
const addr = "127.0.0.1:5037"        // ADB 服务器地址
```

运行程序：

```bash
go run cmd/main.go
```

### 3. 启动 UIAutomator2 服务

程序会自动：
1. 列出已连接的设备
2. 推送 `u2.jar` 到设备
3. 启动 UIAutomator2 服务
4. 输出服务日志

## 核心功能

### 设备管理

```go
// 列出所有设备
payload, _ := adb.ListDevicesRaw(addr, 15*time.Second)
devices := adb.ParseDevicesPayload(payload)

// 通过 Product 名称查找设备
serial, err := adb.FindSerialByProduct(addr, "23113RKC6C")

// 建立设备连接
conn, err := adb.DialADB(addr, 15*time.Second)
defer conn.Close()
adb.TransportTo(conn, serial)
```

### Shell 命令执行

```go
// 执行 Shell 命令
conn, _ := adb.DialADB(addr, 15*time.Second)
adb.TransportTo(conn, serial)
output, err := adb.ExecShell(conn, "getprop")
fmt.Println(string(output))
```

### 文件传输

```go
// 推送文件到设备
sync := adb.InitSync(conn)
n, err := sync.SyncPushFile(
    "local/path/file.png",     // 本地文件路径
    "/sdcard/remote.png",       // 设备目标路径
    0644,                       // 文件权限
    true,                       // 调试模式
)
```

### APK 安装

```go
// 安装 APK
services.InstallServiceApk(addr, serial)

// 或手动安装
remotePath := "/data/local/tmp/app.apk"
output, err := adb.InstallApkOnDevice(addr, serial, remotePath, "-r", true)
```

### UI 选择器

```go
// 创建选择器
selector := libs.MustNew(map[string]interface{}{
    "className": "android.widget.TextView",
    "text": "登录",
})

// 添加子元素选择
selector.Child(map[string]interface{}{
    "resourceId": "com.example:id/button",
    "instance": 0,
})

// 序列化为 JSON
jsonData, _ := selector.ToJSON()
```

## 项目结构

```
go-mobile-uiautomator/
├── adb/                    # ADB 协议实现
│   ├── connect.go         # 连接管理、命令发送/接收
│   ├── device.go          # 设备发现、APK 安装
│   └── sync.go            # 文件同步协议
├── assets/                 # 资源文件
│   ├── u2.jar             # UIAutomator2 服务端
│   ├── app-uiautomator.apk
│   └── sync.sh
├── cmd/                    # 主程序
│   └── main.go
├── config/                 # 配置管理
│   └── index.go
├── libs/                   # 工具库
│   ├── repuest.go         # HTTP over ADB
│   └── selector.go        # UI 选择器
├── services/               # 服务模块
│   └── install_service.go # UIAutomator2 安装
├── test/
│   └── test.py
├── config.yaml             # 配置文件
├── go.mod
└── README.md
```

## ADB 协议实现

本项目实现了以下 ADB 协议功能：

| 功能 | 命令 | 说明 |
|------|------|------|
| 设备列表 | `host:devices-l` | 列出所有连接的设备 |
| 设备路由 | `host:transport:<serial>` | 切换到指定设备 |
| Shell 执行 | `shell:<command>` | 执行 Shell 命令 |
| 文件同步 | `sync:` | 启动文件传输协议 |
| 文件推送 | `SEND/DATA/DONE` | Sync 协议传输文件 |

## 配置说明

`config.yaml` 配置文件：

```yaml
appName: "Go Desk"
port: 6997                              # 本地监听端口
wsUrl: "106.12.33.188:6996"            # WebSocket 地址
stunUrl: "stun:106.12.33.188:3478"     # STUN 服务器
apiUrl: "http://106.12.33.188:6996"    # API 地址
siteFileDir: "www"                      # 网页文件目录
```

加载配置：

```go
cfg, err := config.LoadConfig()
if err != nil {
    log.Fatal(err)
}
fmt.Println(cfg.Port, cfg.WsUrl)
```

## 常见问题

### Q: 如何获取设备序列号？

A: 运行 `adb devices` 或使用代码：

```go
payload, _ := adb.ListDevicesRaw("127.0.0.1:5037", 15*time.Second)
devices := adb.ParseDevicesPayload(payload)
for _, dev := range devices {
    fmt.Println("Serial:", dev.Serial)
}
```

### Q: 文件推送失败怎么办？

A: 检查以下几点：
1. 设备已正确连接且授权
2. 目标路径有写入权限（如 `/sdcard/` 需要存储权限）
3. 文件路径使用绝对路径
4. 启用调试模式查看详细日志

### Q: UIAutomator2 服务启动失败？

A: 确保：
1. `assets/u2.jar` 文件存在
2. 设备已获取 root 权限或使用 `/data/local/tmp/` 路径
3. CLASSPATH 环境变量正确设置

## 开发计划

- [ ] 添加完整的错误处理和重连机制
- [ ] 实现 WebSocket 远程控制
- [ ] 支持批量设备管理
- [ ] 添加 UI 自动化测试框架
- [ ] 完善 HTTP over ADB 功能集成
- [ ] 添加设备截图和录屏功能
- [ ] 实现日志记录系统

## 依赖

```go
require (
    gopkg.in/yaml.v3 v3.0.1
)
```

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

## 作者

zhuy1228

## 致谢

本项目参考了以下开源项目：
- [UIAutomator2](https://github.com/openatx/uiautomator2)
- [Android ADB Protocol](https://android.googlesource.com/platform/packages/modules/adb/)