测试Android TV应用:Arbigent D-Pad遥控器导航与焦点选择机制指南

原创2026-11-07 18:31:401,741 阅读

测试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 还能按下任意按键,并且内置了 Android KeyEvent 风格的别名解析,例如 DPAD_UP、KEYCODE_DPAD_UP、MENU、ESC、DEL 都会被正确映射(别名表见 AgentCommands.kt,解析逻辑的单元测试见 KeyPressAgentActionTest.kt)。

焦点自动寻路:moveFocusToElement 算法解析

DpadTryAutoFocusBy* 背后是 ArbigentDevice.kt 中的 moveFocusToElement,它模拟真人"看焦点在哪、目标在哪,一步步按过去"的过程:

  1. 同帧读取:从一次 UI 层级抓取中同时拿到"当前焦点节点"和"目标元素 bounds",保证两者在同一帧、不受滚动干扰;
  2. 重叠判断:若当前焦点与目标 bounds 重叠 → 已经聚焦,结束;
  3. 方向候选:
    • X 范围重叠 → 优先垂直移动(上/下);
    • Y 范围重叠 → 优先水平移动(左/右);
    • 都不重叠 → 组合出两个候选方向并随机选择,模拟真实操作的不确定性;
  4. 按键 + 等待稳定:发出方向键后调用 waitForAppToSettle,等焦点动画、页面滚动完全静止后,再重新读取层级进入下一轮;
  5. 最多 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 测试中"遥控器 + 焦点"的复杂性收敛为三个层次:

  1. 基础层:方向键/中心键动作 + 通用 KeyPress,覆盖一切按键场景;
  2. 智能层:DpadTryAutoFocusBy* 自动寻路,AI 只需说"把焦点移到 X";
  3. 感知层:FOCUSED_TREE 让 AI 始终知道"焦点现在在哪、中心键会点中谁"。

只需把场景标记为 type: Tv,Arbigent 的 AI Agent 就能像真人一样握着遥控器完成 TV 应用的端到端测试。

登录后查看全文
arbigent