企业官网建设流程全解析

• 测试
• 质量保障
• 计算机视觉

本指南面向希望将 Android 真机或模拟器接入 Airtest 自动化框架的开发者，完整覆盖从 ADB 设备连通性验证、Android://连接串的编写与解析、模拟器与特殊设备参数调优，到代码级接口调用、自定义多指手势与运行中录屏的实战方法。读完本文，你可以独立完成 Android 设备的接入、调试与复杂手势脚本的编写。

Android 手机连接的基本流程

不借助 AirtestIDE、纯代码/命令行使用 Airtest 连接 Android 手机时，需要依次完成以下三步：

1. 在手机上打开开发者选项，并允许USB 调试（部分机型需连续点击“关于手机”中的版本号数次才能开启开发者选项）。
2. 使用 USB 连接手机后，通过adb devices命令确认设备已被识别（参见下文 使用 ADB 验证手机连接）。
3. 在代码和命令行中，用手机序列号（serialno）连接手机（参见下文 在代码中使用手机）。

如果使用 AirtestIDE 进行连接，界面操作流程可参考官方 IDE 文档，本文不再赘述。

使用 ADB 验证手机连接

adb是 Google 官方的 Android 命令行调试工具，用于与设备进行通信。Airtest 已在仓库的airtest/core/android/static/adb目录下按平台预置了adb可执行文件，无需额外下载即可直接使用。从源码（airtest/core/android/constant.py）可以看到各平台默认路径的映射：

以 Windows 为例，进入airtest\airtest\core\android\static\adb\windows目录（可在资源管理器中shift+右键打开命令行终端），执行adb devices：

E:\airtest\airtest\core\android\static\adb\windows>adb devices List of devices attached c2b1c2a7 device eba17551 device 127.0.0.1:10033 device

macOS 下则进入airtest/core/android/static/adb/mac目录后执行./adb devices；如果提示adb没有执行权限，可以先运行chmod +x adb赋予可执行权限（仓库源码 airtest/utils/snippet.py 中的make_file_executable也实现了同样的自动授权逻辑）。

输出解读与常见处理：

• 上例中当前连接了 3 台 Android 设备，状态均为device，说明设备正常在线；
• 如果设备状态是UNAUTHORIZED，请在手机弹出的“允许 USB 调试”对话框中点击确定；
• 如果完全看不到设备名，可能需要先在 PC 上安装对应手机厂商的官方驱动。

手机连接出现问题时怎么办

不同手机厂商与机型差异较大，连接过程中可能遇到各种问题（如驱动缺失、调试授权、端口占用等），官方整理了一份 Android 连接常见问题（Android connection FAQ）清单，建议优先查阅该文档对照排查。

在代码中使用手机

确认手机连接成功后，可以在adb devices的输出中看到设备的序列号。例如：

> adb devices List of devices attached c2b1c2a7 device

上例中的c2b1c2a7就是手机的设备序列号（serialno）。Airtest 用如下格式字符串定义一个 Android 设备：

Android://<adbhost>:<adbport>/<serialno>

其中各字段含义如下：

从源码（airtest/utils/snippet.py）可以确认该 URI 的解析逻辑：urlparse取出 scheme 作为平台、netloc 中的 host:port 作为host参数、path 部分作为uuid，query 部分则通过parse_qsl转换为连接参数。因此Android://串本质上是把平台、序列号和额外参数编码在了一个 URL 里。

几个典型示例：

# 什么都不填，默认使用当前连接的第一台手机 Android:/// # 使用默认端口连接序列号为 c2b1c2a7 的本机手机 Android://127.0.0.1:5037/c2b1c2a7 # 通过本机 ADB 连接远程设备（注意 10.254.60.1:5555 实际是序列号） Android://127.0.0.1:5037/10.254.60.1:5555

通过Android:///字符串连接手机

在命令行运行脚本时，可以用--device Android:///指定脚本运行的目标设备。注意--device参数支持多次追加（源码 airtest/cli/parser.py 中定义为action="append"），因此可同时指定多台设备：

>airtest run untitled.air --device Android:/// 手机序列号 --log log/

在代码中连接手机则使用connect_device接口：

from airtest.core.api import * connect_device("Android:///手机序列号")

connect_device的内部实现（airtest/core/api.py）是先调用parse_device_uri解析 URI，再通过init_device创建设备实例并注册为当前设备，返回设备对象。命令行与代码两种方式二选一即可满足日常连接需求。

一些特殊参数

部分特殊设备（如某些模拟器）连接后可能出现黑屏，此时可以追加cap_method=JAVACAP参数，强制将截屏方式切换为JAVACAP：

# 连接模拟器并勾选“Use Javacap”模式 Android://127.0.0.1:5037/127.0.0.1:7555?cap_method=JAVACAP

此外还有两个常用参数：

• ori_method=ADBORI：指定设备屏幕的旋转方式；
• touch_method=ADBTOUCH：指定使用 ADB 指令模拟点击。

这三类方法在源码中都有明确枚举定义（airtest/core/android/constant.py）：截屏方式包含MINICAP、ADBCAP、JAVACAP，点击方式包含MINITOUCH、MAXTOUCH、ADBTOUCH，旋转方式包含ADBORI、MINICAPORI。默认情况下无需手动指定这些参数；只有当某些特殊 Android 设备（如特定型号的平板）无法用默认参数连接时，才需要追加：

# 勾选所有选项连接设备，用 && 连接多个参数串 Android://127.0.0.1:5037/79d03fa?cap_method=JAVACAP&&ori_method=ADBORI&&touch_method=ADBTOUCH

注意：命令行中若出现^<>|&等特殊字符，可能需要转义才能生效。例如连接串中需要书写&&时，Windows 下要改写成^&^&（用^转义），macOS 下要加\转义：

# Windows 下直接写 --device Android://127.0.0.1:5037/79d03fa?cap_method=JAVACAP&&ori_method=ADBORI 不可用 --device Android://127.0.0.1:5037/79d03fa?cap_method=JAVACAP^&^&ori_method=ADBORI # Windows 命令行加 ^ 转义 --device Android://127.0.0.1:5037/79d03fa?cap_method=JAVACAP\&\&ori_method=ADBORI # MAC 命令行加 \ 转义

Android 接口调用

airtest.core.api中定义的所有跨平台接口都可以在 Android 平台上直接调用，例如：

from airtest.core.api import * touch((100, 200)) # 启动一个应用 start_app("org.cocos2d.blackjack") # 传入一个按键响应 keyevent("BACK")

Android 设备接口

除了airtest.core.api提供的跨平台接口外，Android 设备对象还内置了很多平台专属接口，可以参考airtest.core.android.Android模块的文档。典型的调用方式如下：

dev = device() # 获取当前设备的 Android 对象 print(dev.get_display_info()) # 查看当前设备的显示信息 print(dev.list_app()) # 打印当前已安装的应用列表

device()返回的是当前激活设备（源码 airtest/core/api.py 中直接返回G.DEVICE），配合多设备时还可以用set_current(idx)切换当前设备（支持设备索引或序列号，见 airtest/core/api.py）。

ADB 指令调用

借助 Android 设备接口，可以这样调用 adb 指令：

# 在当前设备上执行指令 adb shell ls print(shell("ls")) # 对特定设备执行 adb 指令 dev = connect_device("Android:///device1") dev.shell("ls") # 切换到某台设备后执行 adb 指令 set_current(0) shell("ls")

Android 常见问题

模拟器连接

模拟器的连接方式与真机类似，需要按以下步骤操作：

• 在模拟器中打开开发者选项并勾选允许 USB 调试（部分模拟器可能需要多次点击“设置 - 关于手机”才能打开开发者选项）；
• 使用 ADB 连接模拟器对应端口，例如执行adb connect 127.0.0.1:62001，其中7555（原文如此，实际以各模拟器厂商端口为准）是模拟器对应的端口号，不同品牌模拟器各不相同；
• 使用代码Android://127.0.0.1:5037/127.0.0.1:62001?cap_method=JAVACAP连接对应模拟器。

需要重点注意：

• 大多数模拟器无法使用默认参数连接，必须指定cap_method=JAVACAP；
• 各品牌模拟器对应的端口号可参考官方 Android 模拟器连接文档。

连续滑动

Airtest 提供了一些滑动接口，便于实现更复杂的操作：

dev = device() # 获取当前设备 dev.pinch() # 双指捏合或分离 dev.swipe_along([(100, 300), (300, 300), (100, 500), (300, 600)]) # 沿一系列坐标连续滑动 dev.two_finger_swipe((100, 100), (200, 200)) # 双指一起滑动

其中swipe_along可以沿一系列坐标点连续滑过，是最常用的接口。这些接口的实现位于 airtest/core/android/touch_methods/base_touch.py：swipe_along会把每段坐标依次拆成若干MoveEvent后统一交给perform执行；two_finger_swipe会根据offset偏移量计算第二根手指的坐标（并夹在屏幕宽高范围内），同时驱动contact=0与contact=1两根手指；pinch则默认以屏幕中心为基准，按percent比例计算双指起始/结束位置实现捏合与张开。

自定义滑动

在airtest.core.android.touch_methods.base_touch（base_touch.py）中定义了四类动作事件：

• DownEvent(坐标, contact=0, pressure=50)：手指按下；
• UpEvent(contact=0)：手指抬起；
• MoveEvent(坐标, contact=0, pressure=50)：滑动到某个坐标；
• SleepEvent：等待（秒）。

在上述四类动作中，contact参数默认是 0，表示第一根手指；传入 1 就可以定义第二根手指的动作，从而实现双指复杂操作。pressure=50定义了按下时的压力，默认值为 50。

以touch接口为例，它实际上就是由[DownEvent, SleepEvent, UpEvent]组合而成的（源码见 base_touch.py），理论上你可以自由组合这些事件，定制出非常复杂的点击与滑动操作。

例如，一个双指点击屏幕的示例：

from airtest.core.android.touch_methods.base_touch import * # 双指点击 multitouch_event = [ DownEvent((100, 100), 0), DownEvent((200, 200), 1), # 第二根手指 SleepEvent(1), UpEvent(0), UpEvent(1)] device().touch_proxy.perform(multitouch_event)

上面的示例中，先在 (100, 100) 处按下第一根手指，在 (200, 200) 处按下第二根手指，等待 1 秒后分别抬起。

再加入MoveEvent可以实现更多样的操作，例如一个普通的swipe：

swipe_event = [DownEvent((500, 500)), SleepEvent(0.1)] for i in range(5): swipe_event.append(MoveEvent((500 + 100*i, 500 + 100*i))) swipe_event.append(SleepEvent(0.2)) swipe_event.append(UpEvent()) dev.touch_proxy.perform(swipe_event)

基于此还可以进一步实现更复杂的操作，比如“长按 2 秒 - 滑动到某个位置”：

from airtest.core.android.touch_methods.base_touch import * dev = device() # 长按删除应用 longtouch_event = [ DownEvent([908, 892]), # 要删除应用的坐标 SleepEvent(2), MoveEvent([165, 285]), # 删除应用的垃圾桶坐标 UpEvent(0)] dev.touch_proxy.perform(longtouch_event)

perform的执行逻辑（base_touch.py）会遍历事件列表：SleepEvent直接time.sleep，其余事件则通过getcmd()生成 minitouch/maxtouch 协议命令字符串（如d 0 x y 50、m 0 x y 50、u 0），再经transform_xy做坐标变换后发送给设备端。这也解释了为什么自定义手势仅在 minitouch / maxtouch 模式下有效。

更多示例可以参考仓库中的 playground/android_motionevents.py，其中包含双指点击、双指滑动、横屏坐标转换（通过dev.touch_proxy.ori_transformer转换坐标）以及长按拖动删除应用等完整可运行样例。

调试小技巧

可以打开手机的设置 - 开发者选项 - 显示触摸位置，用来调试模拟输入是否按预期落点。

运行脚本的同时录屏

Android 手机支持在运行脚本的同时录制屏幕。在运行脚本的命令行中加上--recording参数即可：

airtest run "D:\test\Airtest_example.air" --device android:/// --log logs/ --recording

运行结束后，在指定的 log 目录中即可找到录制的 mp4 文件。录屏文件的命名规则（源码见 airtest/cli/runner.py）：

• 只传--recording参数时，默认使用recording_手机序列号.mp4命名录屏文件；
• 指定文件名--recording test.mp4且连接了不止一台手机时，命名为手机序列号_test.mp4；
• 指定文件名--recording test.mp4且只有一台手机时，命名为test.mp4；
• 注意传入的文件名必须以 mp4 结尾；
• 默认录屏文件最长 1800 秒，如果需要录更长时间，需要在代码中手动调用录屏接口。

在代码中调用录屏接口，可以控制录屏的清晰度和时长。接口文档参见airtest.core.android.Android.start_recording。例如录制一段 30 秒、最低清晰度并导出到当前目录test.mp4的视频：

from airtest.core.api import connect_device, sleep dev = connect_device("Android:///") # 以最低画质录制屏幕 dev.start_recording(bit_rate_level=1) sleep(30) dev.stop_recording(output="test.mp4")

bit_rate_level用于控制录屏分辨率，取值范围是 1-5，bit_rate_level=5分辨率最高，但会占用更多硬盘空间。其底层实现（airtest/core/android/android.py）在 yosemite 模式下会把bit_rate_level换算为屏幕宽 × 屏幕高 × level的码率（超过 5 会自动截断为 5），并通过设备端 Yosemite 服务录制。

也可以设置参数max_time=30，让录屏在 30 秒后自动停止：

dev = device() dev.start_recording(max_time=30, bit_rate_level=5) dev.stop_recording(output="test_30s.mp4")

max_time的默认值是 1800 秒，即最长录屏半小时，可以修改该值获得更长的录屏：

dev = device() dev.start_recording(max_time=3600, bit_rate_level=5) dev.stop_recording(output="test_hour.mp4")

此外，start_recording还支持mode="ffmpeg"（画质略低但文件更小、兼容性更好）、fps（建议 1-10）、orientation（1 竖屏 / 2 横屏 / 0 自动旋转）与max_size（ffmpeg 模式下限制视频最大宽高以降低系统负载）等参数，可按需查阅 airtest/core/android/android.py 中的完整签名与示例。

更多参考

• Android 手机自动化测试教程（官方教程第一部分）；
• Android 连接常见问题（Android connection FAQ）。

• 测试
• 质量保障
• 计算机视觉