Airtest：网易跨平台 UI 自动化框架安装与脚本编写指南

官方信息表

官方演示

下面是官方仓库 README 中给出的演示动图，展示了 Airtest 在真实设备上自动操作游戏界面、完成一整套测试动作的过程：

项目背景

Airtest 是网易开源的跨平台 UI 自动化框架，官方将其定位为“Cross-Platform UI Automation Framework for Games and Apps”，也就是一款既适用于游戏、也适用于普通 App 的跨平台 UI 自动化框架。仓库内同时维护了英文版与中文版两份 README，中文版文件名为 README_zh.md，两者内容一一对应。

传统的 UI 自动化框架大多依赖读取控件树、获取控件坐标来定位界面元素，而游戏界面往往是由引擎整帧渲染出来的，根本不存在可供读取的控件节点。针对这一痛点，Airtest 主打基于图像识别技术来定位界面元素：你只需要截一张按钮的小图，框架就能在屏幕上认出它并执行点击。因此它可以在你无法、也不愿意向被测应用注入任何代码的场景下工作——这也是 README 在开篇就反复强调“without injecting any code”的原因。正是凭借这种无侵入、跨平台的设计，Airtest 从游戏测试场景出发，逐步扩展到了普通移动应用与 Windows 桌面应用的自动化领域。

从使用形态上看，Airtest 实际上是一个“三件套”生态：核心是 Python 命令行与 API 库，面向脚本化和批量执行；上层是 AirtestIDE 图形工具，面向录制、调试与报告生成；再往上则由网易自建 Airlab 设备云平台承接大规模真机集群。README 把这三层能力分别写进了 Features 的第二、三、四条，读者可以根据自己所处的环节（写脚本、录脚本、跑集群）选择对应的入口。

核心特性逐条翻译

README 的 Features 一节完整列出了四大特性，下面逐条翻译并展开说明。

第一，一次编写，到处运行（Write Once, Run Anywhere）。 Airtest 提供跨平台的 API，能力覆盖应用安装、模拟输入、断言等常见自动化操作。由于 Airtest 使用图像识别技术来定位 UI 元素，你无需向被测游戏或应用注入任何代码，即可完成自动化测试或操作。也就是说，同一份用例脚本理论上不需要为每个平台重写一遍，框架在不同宿主上提供的是同一套 API 接口。

第二，完全可扩展（Fully Scalable）。 Airtest 的测试用例可以很容易地在大规模设备集群上运行，调用方式既可以用命令行，也可以用 Python API，这两种方式都被官方列为标准用法。执行结束后，框架会自动生成包含详细步骤信息和屏幕录屏的 HTML 报告，失败时你可以对照每一步的截图和录屏迅速定位失败点，而不是对着一堆日志猜测哪里出了问题。网易在 Airtest 项目之上进一步构建了商用的设备云测平台 Airlab，把这套能力规模化对外提供，这也是 README 把“可扩展”单独写成一条特性的原因。

第三，AirtestIDE。 AirtestIDE 是一个开箱即用的 GUI 图形工具，以对用户友好的方式帮助你创建和运行测试用例。它打通了完整的自动化工作流闭环：创建用例（create）→ 运行用例（run）→ 生成报告（report），全程不需要手写一行 Python。README 特别说明，如果你只是想快速录制、调试一段脚本，可以直接使用 AirtestIDE，而不必先搭建 Python 命令行环境。

第四，Poco。 Poco 是 Airtest 生态中的另一块拼图，它补充了跨主流平台和游戏引擎直接访问对象（即 UI 控件）层级树的能力。借助 Poco，你可以用 Python 指令直接遍历和操作控件层级，按照控件名称、类型来精确定位元素，而不再只靠截图找图，从而实现更高级、更精确的自动化控制。README 将 Airtest 与 Poco 并列为项目的两大核心能力：前者负责图像识别定位，后者负责控件树定位。

README 末尾还指向了一份 跨平台支持清单，列出了框架当前支持的具体设备与平台组合，官方建议大家在开始写脚本之前先对照这份清单确认自己的被测设备在支持范围内。

环境要求与安装步骤

README 的 Installation 一节给出了明确的安装路径，完整翻译如下。

Airtest 本体是一个 Python 库，因此首先需要在你的宿主机上准备好 Python 环境，然后使用 pip 进行安装和升级：

pip install -U airtest

安装完成后，如果你使用的是 MacOS 或 Linux 平台，还需要手动给内置的 adb（Android Debug Bridge）二进制文件授予可执行权限，否则后续连接安卓设备时会直接失败。README 给出的操作如下：

# for mac
cd {your_python_path}/site-packages/airtest/core/android/static/adb/mac
# for linux
# cd {your_python_path}/site-packages/airtest/core/android/static/adb/linux
chmod +x adb

其中 {your_python_path} 需要替换成你本机实际的 Python 安装路径。Mac 系统进入 adb/mac 目录，Linux 系统进入 adb/linux 目录，然后执行 chmod +x adb 即可。README 没有单独说明 Windows 宿主机的权限问题，因为 Windows 下这一内置 adb 默认可执行。

如果你需要使用图形化的录制与调试工具，README 提示可以直接从官方网站下载 AirtestIDE，它和 pip 安装的命令行库是两套独立的分发物，二选一即可。

把安装路径汇总一下：走命令行路线，就是 pip install -U airtest 一条命令，再补上 macOS/Linux 的 adb 权限修复；走图形界面路线，则直接去官网下载 AirtestIDE 安装包。两条路线最终都能产出可以互相通用的 .air 用例目录，README 认为二者之间没有功能上的取舍，只是操作方式不同。

官方文档

README 的 Documentation 一节明确说明：完整的 Airtest 文档托管在 readthedocs 上，地址是 airtest.readthedocs.io。README 在 Examples 和 CLI 两节里反复引用了文档中的四个章节，分别是 connect_device（连接设备）、simulate-input（模拟输入）、make-assertion（断言）以及 Running .air from CLI（命令行用法），此外还有完整的 Python API 参考手册。第一次写用例时，建议按官方文档的顺序依次读完这四节再动手。

使用方法：一个最小可用脚本

README 的 Examples 一节强调，Airtest 的目标是提供平台无关的 API，让你编写的自动化用例只写一次，就能运行在多种设备和平台上。官方给出的标准使用流程分三步：

1. 使用 connect_device API，连接到任意 Android 设备、iOS 设备，或者一个 Windows 应用窗口；
2. 然后执行模拟输入（simulate input）类 API，去自动化操作你的游戏或 App；
3. 不要忘记对预期结果做断言（make assertion），否则用例跑完了也无法判断自己到底是成功还是失败。

README 给出的完整示例代码如下（原样保留）：

from airtest.core.api import *

# connect an android phone with adb
init_device("Android")
# or use connect_device api
# connect_device("Android:///")

install("path/to/your/apk")
start_app("package_name_of_your_apk")
touch(Template("image_of_a_button.png"))
swipe(Template("slide_start.png"), Template("slide_end.png"))
assert_exists(Template("success.png"))
keyevent("BACK")
home()
uninstall("package_name_of_your_apk")

对照中文 README，这段代码的逐行含义是：首先从 airtest.core.api 导入全部 API；然后通过 ADB 连接本地 Android 手机，init_device("Android") 是最常用的写法，README 同时提示你也可以显式调用 connect_device("Android:///")，二者等价；接着用 install 安装指定路径的 APK 包；用 start_app 通过包名启动被测应用；touch(Template(...)) 表示在屏幕上找到“按钮截图”并点击它，这就是图像识别定位的核心用法；swipe 表示从“起点截图”滑动到“终点截图”，用于模拟滑动、翻页等手势；assert_exists(Template("success.png")) 断言“成功界面截图”出现在屏幕上，用来验证业务结果是否符合预期；keyevent("BACK") 模拟系统返回键；home() 回到手机桌面；最后 uninstall 卸载被测应用，完成一个完整闭环。整个流程从安装、启动、操作、断言到清理，覆盖了一条自动化用例应当具备的全部环节。

如果你想了解更详细的 API 说明，README 指引大家阅读 Airtest Python API 参考文档，或者直接去仓库里看 API 源码文件 api.py，两个入口都在 README 中给出了链接。

使用方法：命令行运行 .air 用例

README 专门用一节说明如何在脱离 AirtestIDE 的情况下跑用例。使用 AirtestIDE 时，你可以非常轻松地把一条自动化脚本录制并保存为一个 .air 目录结构；而 Airtest 的命令行工具（CLI）则让你能够在不同的宿主机器、不同的被测设备平台上直接执行这些 .air 用例，无需打开 IDE。README 给出的命令示例如下：

# run cases targeting on Android phone connected to your host machine via ADB
airtest run "path to your .air dir" --device Android:///

# run cases targeting on Windows application whose title matches Unity.*
airtest run "path to your .air dir" --device "Windows:///?title_re=Unity.*"

# generate HTML report after running cases
airtest report "path to your .air dir"

# or use as a python module
python -m airtest run "path to your .air dir" --device Android:///

逐条说明：第一条命令把 .air 用例跑在通过 ADB 连接到宿主机的安卓手机上，--device 参数用 URI 形式描述目标设备；第二条命令把用例跑在标题匹配 Unity.* 的 Windows 应用上，说明 Airtest 也能自动化 PC 端的 Unity 游戏窗口，设备 URI 支持正则过滤窗口标题；第三条命令在运行结束后生成 HTML 测试报告，这是查看执行详情的入口；第四条演示了等价的 python -m airtest 模块调用方式，在不方便写全局命令、或者需要把 Airtest 嵌进其他 Python 脚本时很有用。

README 还建议你亲自跑一下官方提供的示例用例：仓库里的 airtest/playground/test_blackjack.air 就是一个开箱即用的演示脚本，它以一个 Blackjack 小游戏为被测对象，演示了从连接设备、图像点击到断言的完整流程；完整的 CLI 用法说明见官方文档的 Running .air from CLI 一节。如果你需要多设备并行跑用例，官方另外提供了一个 multi-device-runner 多设备运行器示例，可以作为自建设备集群调度方案的参考——这也呼应了 README 在 Features 第二条强调的“用例可以很容易地在大规模设备集群上运行”。

常见问题（FAQ）

问：pip 安装完成后，连接 Android 设备时报 adb 不可执行怎么办？ 这是 MacOS 和 Linux 平台上的已知问题，README 明确要求你进入 site-packages/airtest/core/android/static/adb/ 下对应系统的目录，执行 chmod +x adb 赋予可执行权限后再试。

问：我该用 AirtestIDE，还是直接用 pip 安装的 Python 库？ 两者面向不同场景：README 介绍 AirtestIDE 是开箱即用的 GUI 工具，适合录制和调试脚本、走“创建→运行→报告”的完整流程；而 pip 安装的命令行与 Python API 适合在大规模设备集群、持续集成环境中长期批量跑用例。二者的产物（.air 用例目录）是互通的，在 IDE 里录好的脚本可以直接拿到命令行里执行。

问：游戏类应用没有控件树，怎么做自动化？ 这正是 Airtest 的设计初衷——README 强调它基于图像识别定位 UI 元素，无需向应用注入任何代码；如果你还想直接按名称操作控件层级，可以配合 Poco 一起使用。

问：跑完用例之后在哪里看结果？ README 说明用例执行结束后会自动生成包含详细步骤和屏幕录屏的 HTML 报告，命令行方式下使用 airtest report 命令生成报告即可，失败步骤会随截图和录屏一并呈现。

问：除了 Android 手机，还能测什么目标？ README 的示例代码和 CLI 章节显示，Airtest 支持连接 Android 设备、iOS 设备，以及 Windows 应用窗口（例如标题匹配 Unity.* 的游戏窗口）；完整的支持清单以官方文档中的 Supported Platforms 页面为准。

问：写用例时第一步该做什么？ 按 README 的建议顺序，第一步永远是连接设备：先用 init_device 或 connect_device 把目标设备连上；第二步才是模拟输入操作界面；第三步不要忘记写断言，让用例自己知道执行结果是对是错。这三步就是 README Examples 一节给出的标准骨架。

贡献与致谢

README 的 Contribution 一节表示：非常欢迎大家提交 Pull Request。Thanks 一节则感谢了三个让本项目变得更好的开源项目：stf（远程设备管理框架）、atx（网易早期的 UI 自动化项目）、pywinauto（Windows 桌面自动化库），Airtest 的设备管理、ADB 操作与 Windows 自动化能力都站在了这些项目的肩膀上。

跳转链接

• 官方代码仓库：AirtestProject/Airtest
• 官方网站：airtest.netease.com
• 完整文档：airtest.readthedocs.io
• Python API 参考：airtest.core.api 模块文档
• 支持平台一览：Supported Platforms
• 配套控件框架：AirtestProject/Poco
• 商业云测平台：Airlab
• 多设备运行示例：multi-device-runner
• 内置演示用例：test_blackjack.air