用途
verify-keyboard-access 用于验证页面上的每个交互控件都可以获取键盘焦点,并且其主要操作能够从键盘触发,而不仅仅是从鼠标触发。
资料强调的核心区别:Reachable is not the same as operable(可达不等于可操作)。一个被样式做成按钮的 <div onClick> 可能看起来可达,且仍然在按下 Enter 时什么都不做。能够获取焦点证明控件可达,并不证明它可用。Reticle 可以在运行中的应用里同时驱动这两部分。
前提与安装
如果尚未安装 Reticle,资料给出的命令为:RETICLE_INSTALL_SOURCE=npx_skill npx @reticlehq/server@latest init,然后使用 install-and-verify 技能。
重要限制:Tab 顺序无法验证
资料明确要求:开始前先读取这一点——Tab order cannot be verified today(今天无法验证 Tab 顺序)。press 始终通过合成键盘事件发出,而合成的 Tab 不会移动焦点。这在每种模式下都成立,包括 reticle drive:不存在代理可以证明焦点顺序的模式。不要去寻找这样的模式,也不要将 Tab 顺序结果报告为通过或失败,应报告为 unknown。
该技能能证明的范围更窄:每个控件都能获取焦点,且其主要操作能从键盘触发。
使用方式
1. 确认会话健康
确认页面存在活跃会话,并且能够渲染和观察:
reticle_session({ action: "list" })
在断开连接、隐藏或被节流的标签页中,按键可能被接受,但计时器、渲染和后续观察不会推进,因此读回的任何内容都不可信。首先要获取可用上下文,例如一个租用的标签页:
reticle_run({ tool: "reticle_lease", args: { action: "acquire", url } })
在该操作上传入 refuseWhenThrottled: true,这样暂停的标签页会响亮地失败,而不是静默地什么都不做。如果无法获得健康会话,报告该次运行被阻塞(blocked),而不是通过(passed),并且不要持续重试。
2. 列出控件
在触碰键盘之前先列出每一个交互控件,否则只会测试到你已经知道的那几个:
reticle_look({ sessionId, action: "page", mode: "interactive" })
3. 检查每个控件能否获取焦点
对该列表中的每个控件,聚焦它并断言它已获得焦点:
reticle_act({ sessionId, ref, action: "focus" })
reticle_assert({
sessionId,
predicate: { kind: "element", query: { testid: "the-control" }, state: "focused" },
})
这证明控件能够获取焦点,但不证明该控件位于 Tab 顺序中(tabindex="-1" 可聚焦但会被 Tab 跳过),因此将其报告为 focusable(可聚焦),而不是 Tab-reachable。没有 tabindex 的 <div onClick> 不会获取焦点,这是一个真实的发现。
4. 证明主要操作,而不仅是焦点
焦点是前提条件,而不是检查本身。命名后果,然后用键盘激活:
reticle_act_and_wait({
sessionId,
ref,
action: "press",
args: { text: "Enter" },
until: { kind: "element", query: { testid: "expected-result" } },
})
按钮和链接接受 Enter。复选框和原生 <select> 接受 Space,选项还需要箭头键。在表单控件上合成 Enter 会提交其表单,因此 Enter-to-submit 在这里可以检查。自定义样式的组合框(combobox)是最可能失败的控件:它看起来与原生控件完全相同,且通常只监听 click。请按下按键,不要用点击代替并假设键盘行为相同。
某个 until 条件在你操作之前就可能已经为真,此时 already_true 不能证明你的按键。先检查该后果不存在。如果不是,则重置应用状态并重新开始,或者将结果报告为 inconclusive(不确定)。如果要求是文本变为可见,请使用要求可见性的谓词,因为隐藏元素仍然满足存在性检查。请通过 reticle_tools({ names: ["reticle_act_and_wait"] }) 加载准确字段,而不要猜测。
应当断言什么
- 初始 look 得到的每个控件都能获取焦点,每个都通过 focus 动作和
state: "focused"断言证明。 - 主要操作从键盘触发,通过
reticle_act_and_wait({ until })命名一个此前不为真的后果来证明。 - Tab 顺序和焦点陷阱不在该列表中。两者今天都无法验证,因此都将二者报告为 unknown,绝不要报告为通过。
诚实性要求
将每个结果报告为 verified(Reticle 对确切条件返回了正面判定)、failed、blocked(无健康会话)或 unknown。verified: "unknown" 或 verified: "no-fault" 的判定不是通过。unknown 意味着 Reticle 无法判断发生了什么。如实地报告任一结果,绝不要削弱检查以使其通过。观察到的证据不是已验证结果,already_true 不是你的操作导致后果的证明,一次已派发但从未结算的按键不是已完成的交互。
结束时需报告:发现的控件、其中哪些获取了焦点、你按下的按键和你等待的确切后果、Reticle 返回的判定、Tab 顺序为 unknown,以及任何限制结果的节流或超时。
能力参考
curl https://docs.reticle.sh/capabilities.md
其他内容:curl https://docs.reticle.sh/llms.txt