测试Android TV应用:Arbigent D-Pad遥控器导航与焦点选择机制指南
测试Android TV应用:Arbigent D-Pad遥控器导航与焦点选择机制指南
Arbigent 是一个面向 Android、iOS 与 Web 应用的 AI Agent 测试框架,它原生支持 Android TV 这类"无触屏"设备:内置 D-Pad 遥控器动作集、焦点自动移动算法与 FOCUSED_TREE 焦点树感知,让 AI 像真人握着遥控器一样操作 TV 应用。本文带你完整理解 Arbigent 的 D-Pad 导航与焦点选择机制,并学会编写 TV 场景。
为什么 Android TV 测试需要专门的 D-Pad 机制
手机上的测试靠"点击坐标/点击文本"就够了,但 TV 应用的交互模型完全不同:
- 没有触屏:用户通过遥控器移动焦点、按中心键确认;
- 焦点驱动 UI:同一个页面,焦点在不同按钮上,可点的对象完全不同;
- 直接点击坐标会"跳过"应用逻辑:很多 TV 应用(尤其 Leanback/TV 平台)只响应遥控按键事件,坐标 tap 并不总能触发预期行为。
因此 Arbigent 为 TV 形态提供了两套能力:逐键模拟(上下左右 + 中心键)和智能焦点寻路(自动把焦点移动到目标元素)。
第一步:把场景标记为 Tv 类型
在场景 YAML 中用 type 字段声明设备形态,Arbigent 会自动切换为 TV 专用系统提示词。支持的取值为 Mobile、Tv、Unspecified(默认),详见 arbigent-yaml-reference.md。
scenarios:
- id: "tv-home-navigation"
type: Tv
goal: "在首页用遥控器导航到'我的频道'并打开它"
标记为 Tv 后,AI 收到的系统提示词会追加遥控器导航策略(定义在 ArbigentPrompts.kt):
Tips for D-pad navigation: If you know where to move, please use DpadAutoFocus. If you can't move the focus with the D-pad, try pressing the D-pad twice or different direction. To select an item, focus on it and press the center button.
翻译成实践原则就是:知道去哪 → 用自动焦点动作;按不动 → 换方向或连按两次;选中物品 → 先聚焦再按中心键。
核心动作一览:Arbigent 的 D-Pad 动作集
所有 D-Pad 动作定义在 AgentCommands.kt 中,AI 会按目标自主选择:
| 动作名 | 参数 | 作用 |
|---|---|---|
DpadUpArrow / DpadDownArrow |
count |
连按上/下方向键 N 次 |
DpadLeftArrow / DpadRightArrow |
count |
连按左/右方向键 N 次 |
DpadCenter |
count |
连按中心(确认)键 N 次,按下前先查 FOCUSED_TREE 确认焦点位置 |
DpadTryAutoFocusByText |
text |
自动把焦点移动到指定文本的元素(支持正则与 text[1] 索引) |
DpadTryAutoFocusById |
text |
自动把焦点移动到指定 ID 的元素 |
DpadTryAutoFocusByIndex |
text |
自动把焦点移动到 ELEMENTS 列表中某索引的元素 |
几个设计细节值得新手注意:
- 方向键带
count参数:AI 可以说"向下按 3 次",一次动作完成多步移动,减少 AI 往返开销(实现见 AgentCommands.kt)。 - 自动焦点动作仅限 TV 设备:
DpadTryAutoFocusBy*要求设备实现ArbigentTvCompatDevice接口,否则会抛出NotImplementedException,提示"This action is only available for TV device"。 - 通用
KeyPress兜底:AI 还能按下任意按键,并且内置了 AndroidKeyEvent风格的别名解析,例如DPAD_UP、KEYCODE_DPAD_UP、MENU、ESC、DEL都会被正确映射(别名表见 AgentCommands.kt,解析逻辑的单元测试见 KeyPressAgentActionTest.kt)。
焦点自动寻路:moveFocusToElement 算法解析
DpadTryAutoFocusBy* 背后是 ArbigentDevice.kt 中的 moveFocusToElement,它模拟真人"看焦点在哪、目标在哪,一步步按过去"的过程:
- 同帧读取:从一次 UI 层级抓取中同时拿到"当前焦点节点"和"目标元素 bounds",保证两者在同一帧、不受滚动干扰;
- 重叠判断:若当前焦点与目标 bounds 重叠 → 已经聚焦,结束;
- 方向候选:
- X 范围重叠 → 优先垂直移动(上/下);
- Y 范围重叠 → 优先水平移动(左/右);
- 都不重叠 → 组合出两个候选方向并随机选择,模拟真实操作的不确定性;
- 按键 + 等待稳定:发出方向键后调用
waitForAppToSettle,等焦点动画、页面滚动完全静止后,再重新读取层级进入下一轮; - 最多 15 轮:防止陷入死循环。
这套"读一帧 → 按一次 → 等稳定 → 再读"的循环,让焦点移动在焦点动画较慢的 TV 应用上依然稳定。
FOCUSED_TREE:AI 如何知道中心键会点中什么
TV 界面最大的坑是"焦点不可见地漂移"。Arbigent 的解法是把当前焦点节点子树作为独立区块注入 AI 提示词模板:
<UI_STATE>
<ELEMENTS>index:element ...</ELEMENTS>
<FOCUSED_TREE>
当前焦点节点的优化子树
</FOCUSED_TREE>
</UI_STATE>
- 模板定义在 UserPromptTemplate.kt;
- 焦点子树由设备端从完整 UI 层级中提取(而非精简后的元素列表,因为焦点常落在容器节点上),见 ArbigentDevice.kt;
- 正因如此,
DpadCenter的动作描述才会写着 "Please refer to FOCUSED_TREE to know what will be clicked" —— AI 按下中心键之前,能明确知道焦点正停在哪个元素上。
另外,元素列表本身也会把 focused == true 的节点纳入(见 ArbigentDevice.kt),让 AI 双通道感知焦点。
实用技巧与故障排查
- AI 按不动焦点时:TV 提示词已内置策略——尝试按两次或换方向。这是 TV 焦点动画与焦点策略(focus search)常见的"吞掉第一次按键"现象,Arbigent 通过"等稳定后再决策"天然缓解它。
- 回放(Replay)依赖焦点位置:回放模式会调用
focusedElement()等待设备焦点真正移动到录制时所在位置,焦点匹配才继续,保证回放节奏与录制时一致。 - 元素定位写不中:
DpadTryAutoFocusByText/ById支持正则与text[1]索引语法,多个同名按钮时换索引即可。 - 自定义系统提示词:项目级可通过
systemPromptsForTv字段覆盖默认 TV 提示(默认值见 ArbigentProjectSerializer.kt),适合为自家应用补充"我们的频道页焦点规则"等领域知识。
小结
Arbigent 把 Android TV 测试中"遥控器 + 焦点"的复杂性收敛为三个层次:
- 基础层:方向键/中心键动作 + 通用 KeyPress,覆盖一切按键场景;
- 智能层:
DpadTryAutoFocusBy*自动寻路,AI 只需说"把焦点移到 X"; - 感知层:FOCUSED_TREE 让 AI 始终知道"焦点现在在哪、中心键会点中谁"。
只需把场景标记为 type: Tv,Arbigent 的 AI Agent 就能像真人一样握着遥控器完成 TV 应用的端到端测试。