设备操控

Tapilot 对 Android / iOS / Web 三端提供统一 API(DSL / MCP / HTTP),但底层实现各不相同。这里讲每一端的具体机制、前置条件和差异。

Android

机制

基于 adb(Android Debug Bridge)shell 命令:

• 输入:adb shell input tap / swipe / text / keyevent
• 观察:adb shell uiautomator dump → XML UI 树 + screencap 截图
• App:adb install / uninstall / pm clear / am start
• 日志:adb logcat 拉主/crash buffer

前置

• 装 Android SDK Platform Tools:brew install android-platform-tools
• 设备开 USB 调试(开发者选项),USB 连接电脑
• 首次连接手机会弹授权提示 → 允许
• 或者跑 Android Emulator(Tapilot 可直接接管)

支持的动作

全部 36 个 DSL actions 双端通用。Android 独有能力:

• setLocale — 切换系统语言(iOS 侧不支持)
• IME 切换 / ADBKeyboard 中文输入
• Gesture 录制生成 DSL(record-session)

常见坑

问题	解决
adb: device unauthorized	手机上重新允许 USB 调试
中文输入乱码	用 setup_chinese_input 装 ADBKeyboard
uiautomator dump 空	App 可能禁用 accessibility,改用 analyze_screen 视觉识别
连续 tap 没反应	加 wait: 500 给 UI 动画时间,或用 waitStable

iOS

机制

iOS 没有 adb 这种官方通用协议,Tapilot 用两套:

• 基础能力:xcrun simctl(模拟器) — io screenshot / launch / install / uninstall / spawn log
• UI 操作:WebDriverAgent (WDA) — HTTP API localhost:8100,点击/滑动/输入/dump UI 走 WDA

前置

• macOS(Windows / Linux 无法自动化 iOS)
• Xcode 已安装
• iOS Simulator 已 boot:

  xcrun simctl list devices available  # 列可用设备
  xcrun simctl boot <UDID>
  open -a Simulator

• WebDriverAgent 在跑:

  git clone https://github.com/appium/WebDriverAgent.git
  cd WebDriverAgent
  xcodebuild build-for-testing \
    -project WebDriverAgent.xcodeproj \
    -scheme WebDriverAgentRunner \
    -destination 'id=<UDID>' \
    CODE_SIGNING_ALLOWED=NO
  xcodebuild test-without-building \
    -project WebDriverAgent.xcodeproj \
    -scheme WebDriverAgentRunner \
    -destination 'id=<UDID>' \
    CODE_SIGNING_ALLOWED=NO
  # 新终端验证
  curl http://localhost:8100/status

• 重点:Simulator 场景可以用 CODE_SIGNING_ALLOWED=NO 跳过 Apple ID 签名,10 分钟就能启 WDA。真机需要有效签名。

iOS ≠ Android 的差异

维度	Android	iOS
坐标单位	物理像素(1080×2400)	logical points(390×844)
Back 手势	KEYCODE_BACK	无全局 back → 用左边缘 swipe 代替
Home	KEYCODE_HOME	WDA /wda/homescreen
中文输入	需 ADBKeyboard	wdaInput 原生支持 Unicode
Keycode	KEYCODE_* 完整	仅 ENTER / RETURN 映射到 \n
清除 app 数据	pm clear	simctl privacy reset all + terminate(弱化)或 uninstall
UI 节点属性	text / content-desc / clickable / focused	name / label / value / enabled / hasKeyboardFocus
局限	无	setLocale 不支持(需私有 API)

常见坑

问题	解决
WDA not running	启动 xcodebuild test-without-building,curl localhost:8100/status
Device not found	确认 Simulator booted(xcrun simctl list devices booted)
assert_focused iOS 上永远 false	iOS 只在 TextField 等特定控件暴露 hasKeyboardFocus,其他控件无 focused 属性
中文文字找不到节点	中文 UI 下 name 属性常包含中文;用 dump_ui 看实际 XML 确认

Web

机制

Chrome DevTools Protocol(CDP)on localhost:9222。Tapilot 启动 Chrome 时加 --remote-debugging-port=9222,之后所有操作走 WebSocket/HTTP 到 Chrome。

见专门的 Web 自动化 指南。

前置

• Chrome / Chromium 在 PATH(chrome / google-chrome / chromium)
• 首次调 openBrowser 自动启动

三端选型建议

场景	选哪端
App 功能回归测试	Android 或 iOS(看用户群)
SPA / 后台管理 / 表单测试	Web
跨平台一致性测试(同一个 flow 三端都跑)	三端都跑,DSL 一份 platform: both
性能基线(CPU / 内存 / FPS)	Android 或 iOS
需要视觉识别(Canvas / 游戏 UI)	全端(用 analyze_screen / assertVisual)

统一接口对应关系

任务	Android	iOS	Web
截图	adb screencap	simctl io screenshot	CDP Page.captureScreenshot
点击	input tap x y	wdaTap(x, y)	element.click()
输入	input text "..." 或 broadcast	wdaInput(text)	element.value = "..." + dispatch
UI 树	uiautomator dump	wdaSource	document.documentElement.outerHTML
启动 app	am start	simctl launch	chrome 加 URL 启动

DSL / MCP 层屏蔽这些差异,你只需要写 tap: 登录 就能三端通吃。