Android 设备接入

手机设置

1. 设置 → 关于手机 → 连续点"版本号"7 次，打开开发者选项。
2. 开发者选项 → 打开 USB 调试。三星手机还要关掉"USB 调试授权超时"或者保持屏幕常亮。
3. USB 线连电脑，手机上弹出"允许 USB 调试"选始终允许。

确认连接

adb devices

看到类似下面的输出就连上了：

List of devices attached
R5CX12345AB    device

• 显示 unauthorized：手机上没点允许，重新插拔再看。
• 显示 offline：adb kill-server && adb start-server 后重试。
• 什么都没有：换线、换 USB 口，Windows 可能要装厂商驱动。

多台设备时在 .env 里指定：

ANDROID_DEVICE_ID=R5CX12345AB

跑冒烟

pnpm test:android

cases/android/00-smoke.yaml 不调模型，只验证拉起系统设置、回桌面、杀进程。它通过说明 adb 链路没问题。

写 Android 用例

和 Web 的差别只在确定性节点：

beforeEach:
  - terminate: com.example.shop      # 先杀掉保证干净
  - launch: com.example.shop

cases:
  - name: App 内搜索商品
    tags: [smoke, search]
    steps:
      - aiAct: 点击首页顶部搜索框
      - aiInput:
          prompt: 搜索输入框
          value: 蓝牙耳机
      - aiKeyboardPress: Enter
      - aiAssert: 搜索结果列表出现至少一个商品

afterEach:
  - home: {}

查包名：

adb shell pm list packages | grep -i <关键词>

注意

• 一台手机同一时刻只能跑一个用例文件，配置里 maxConcurrentFiles: 1 已限制。
• 跑的时候别碰手机，屏幕要亮着。
• 手机的弹窗（系统更新、权限申请）会干扰，提前处理掉或在 setAIContext 里说明。
• 测试包和线上包包名不同时，用例里写测试包的包名。