5分钟上手Arbigent:从安装到跑通第一个AI Agent测试的完整教程
5分钟上手Arbigent:从安装到跑通第一个AI Agent测试的完整教程
Arbigent 是一款用于测试 Android、iOS 和 Web 应用的 AI Agent 测试框架,让你用自然语言描述测试目标,就能让 AI 自动操作 App 完成 UI 自动化测试。本文将带你从安装 Arbigent 开始,在 5 分钟内连接设备、创建场景并跑通第一个 AI Agent 测试,是面向新手和普通用户的完整教程。
🧩 什么是 Arbigent:AI Agent 测试框架解决什么问题
传统的 UI 自动化测试(如固定脚本)非常"脆弱":A/B 实验、新手引导、弹窗广告或动态内容稍有变化,测试就可能失败。Arbigent 的解法是让 AI Agent 理解屏幕内容并自主决策,因此它对 UI 小改动天然具备抗干扰能力。
它的核心优势可以概括为三点:
- 场景拆分与依赖管理:把复杂目标拆成相互依赖的小场景(例如"登录 → 搜索 → 收藏文章"),执行更可控、更可复用
- UI 与代码双入口:QA 可以在图形界面创建场景,工程师可以通过 CLI / YAML 文件在 CI 中运行同一套测试
- 多平台 + 多 AI 提供商:支持 Android、iOS、Web(Chrome),并适配 OpenAI、Gemini、Anthropic 及 OpenAI 兼容接口(如 Ollama)
项目由几个模块组成,了解结构有助于后续查阅源码:
| 模块 | 作用 |
|---|---|
| arbigent-core/ | 核心引擎:场景执行、AI 决策编排、设备驱动 |
| arbigent-ui/ | 桌面图形界面,可视化创建与管理测试场景 |
| arbigent-cli/ | 命令行工具,用于 CI 与本地运行 |
| arbigent-ai-openai/ / arbigent-ai-anthropic/ | 各 AI 提供商的适配实现 |
更完整的设计说明可以参考项目根目录的 README.md。
🚀 一键安装 Arbigent:3 步完成环境准备
安装 Arbigent UI 桌面端
- 从 Arbigent 官方 Release 页面下载对应系统(macOS / Windows / Linux)的 UI 安装包
- 安装并启动应用,即可获得可视化操作界面
- macOS 用户若遇到"无法打开未验证应用"的安全提示,请在"系统设置 → 隐私与安全性"中点击"仍要打开"(该按钮在首次尝试打开后约一小时内有效)
安装 Arbigent CLI(macOS 用 Homebrew 最快)
CLI 适合脚本化执行和 CI 集成,macOS 上两条命令即可安装:
brew tap takahirom/homebrew-repo
brew install takahirom/repo/arbigent
安装完成后,可以用 arbigent --help 验证。帮助信息末尾还列出了内置指南主题,这些指南也可以直接打印出来,非常适合边查边做:
arbigent guide writing-yaml
🔌 连接设备并配置 AI API Key:跑通测试前的准备
运行测试只需两件事:一台连接的设备 + 一个 AI 提供商的 API Key。
- 启动 Android 模拟器(或通过 USB 连接真机);iOS 用户启动模拟器或连接 iPhone
- 在 Arbigent UI 中,从设备列表选择已连接的设备,建立连接
- 在界面指定的输入框中填入 AI 提供商(如 OpenAI)的 API Key
如果用 CLI 运行,也可以把这些配置写入项目根目录的 .arbigent 目录下的设置文件(如 settings.local.yml),避免每次重复输入参数。一个最小配置示例:
ai-type: openai
openai-api-key: sk-xxxxxxxxxxxxxxxxxx
openai-model-name: gpt-4.1
os: android
配好之后,执行命令时就不需要再写这些选项了。完整的 CLI 参数说明见 arbigent-cli-reference.md。
📝 创建第一个测试场景:用自然语言描述测试目标
Arbigent 最大的特点是:测试用例就是一句自然语言,例如"打开 App 并确认首页展示"。
方式一:在 UI 中创建(推荐新手)
- 打开 Arbigent UI,点击新建场景
- 在目标(goal)输入框用自然语言描述要验证的内容
- 可选:添加初始化方法,如
CleanupData(清理应用数据)、LaunchApp(启动指定包名的应用) - 保存后,项目会以 YAML 文件落盘,可直接提交到代码仓库
方式二:零配置跑一次性任务
如果只想快速验证环境是否可用,可以不用项目文件,直接下达一个一次性任务:
arbigent run task "Open the Settings app and turn on dark theme" --max-step=15
看到 AI 一步步操作设备、最终达成目标,就说明环境完全跑通了 ✅
▶️ 运行第一个 AI Agent 测试:arbigent run 命令详解
有了 UI 创建并保存的项目 YAML 文件后,最常用的运行命令是:
arbigent run --project-file=arbigent-project.yaml --os=android
常用参数速查:
| 参数 | 说明 |
|---|---|
--project-file |
项目 YAML 文件路径 |
--os |
目标系统:android / ios / web |
--scenario-ids |
只运行指定 ID 的场景,多个用逗号分隔 |
--tags |
按标签筛选场景,如 --tags="smoke,regression" |
--dry-run |
预演:只展示将运行哪些场景,不实际操作设备 |
--device-id |
多台设备时指定要使用的设备 |
多设备场景下,用 --device-id 明确指定设备即可,例如 arbigent run --device-id=emulator-5554。
📊 查看测试结果报告
每次运行结束后,Arbigent 会在工作目录下生成结果目录 arbigent-result/,其中包含:
- HTML 报告:逐步展示 AI 的截图、决策与动作,方便人工复核
result.yml:机器可读的测试结果,便于 CI 断言或让 AI 编码助手自动排查- 截图文件:每个步骤的现场留证
当测试失败时,重点查看失败步骤前后的截图和日志;arbigent guide debugging-failures 会打印一份系统性的排查指南。
⚙️ 进阶玩法:场景依赖、Tags 与并行分片
用依赖关系编排复杂流程
在 YAML 中,场景之间可以用 dependency 声明依赖,AI 会按依赖顺序执行。项目文件的所有字段(类型、默认值、含义)都可以在 arbigent-yaml-reference.md 中逐字段查到。
scenarios:
- id: "launch-app"
goal: "Launch the app and confirm the home screen is shown"
- id: "open-search"
dependency: "launch-app"
goal: "Open the search page"
可复用场景:一次定义,处处调用
类似 GitHub Actions 的 reusable workflows,Arbigent 支持 reusableScenarios:把"登录"这样的公共步骤定义一次,其他场景用 uses + with 传参调用,大幅减少重复编写。完整规范见 arbigent-reusable-scenarios-specification.md。
并行分片提速
场景较多时,用 --shard 把测试套件切分到多台设备并行执行:
arbigent run --shard=1/4
❓ 新手常见问题 FAQ
Q:必须用真实设备吗? A:不需要。Android 模拟器、iOS 模拟器都可以,真机同样支持(iOS 真机需 Xcode 环境,详见 README.md 的 iOS real devices 章节)。
Q:AI 调用有费用吗?
A:使用 GPT-4o 级别模型时,成本大约在每步 $0.005、每任务 $0.02 量级。可以用更便宜的模型(如 gpt-4o-mini)或在项目设置中启用 AI 结果缓存来降本。
Q:已有 Maestro 脚本怎么办? A:Arbigent 支持把 Maestro YAML 作为初始化方法,在 AI 接管前先完成登录等确定性步骤,复用现有自动化资产。
Q:想直接看代码示例? A:仓库内有一个端到端测试示例 RealArbigentTest.kt,展示了如何用代码接口执行项目文件。
🎯 总结:从 5 分钟到完整的 AI Agent 测试体系
回顾一下本文的上手路径:
- 安装 Arbigent UI / CLI(Homebrew 两条命令)
- 连接设备、填入 AI API Key
- 用自然语言创建第一个场景
arbigent run跑通测试,查看 HTML 报告- 用场景依赖、Tags、分片把零散测试扩展成完整体系
Arbigent 把 AI Agent 测试从"高门槛"变成了"会写一句话就会用",并且完全开源免费。接下来推荐阅读 README.md 中的 Key Features 章节,深入了解场景拆分、图像断言和 MCP 集成等能力,让你的 AI Agent 测试体系更加健壮。