verify-keyboard-access

到達可能であることと操作可能であることは同じではありません

ボタンのように見えるようスタイル設定された <div onClick> は、到達可能に見えることがあります（多くのコンポーネントライブラリは、何もしなくても tabindex="0" を付与します）。それでも、Enter を押したときに何も起こらない場合があります。フォーカスできることが証明するのは、コントロールに到達できるということだけであり、動作することではありません。

Reticle を使えば、実行中のアプリでどちらの側面も操作できます。まだセットアップしていませんか？reticle スキルに従ってください。Reticle をインストールし、init によるアプリのファイル変更の前にユーザーに確認し、1 つのフローを実証します。

始める前にお読みください：現在、Tab 順序は検証できません

press は常に合成キーイベントを介して実行され、合成 Tab イベントではフォーカスが移動しません。これは reticle drive を含むすべてのモードで同じです。エージェントがフォーカス順序を実証できるモードはありません。探そうとせず、Tab 順序の結果を合格または不合格として報告しないでください。不明として報告してください。

このスキルで実証できるのは、各コントロールがフォーカスを受け取れることと、キーボードから主要なアクションが実行されることに限られます。

セッションが正常であることを確認する

ページでライブセッションが存在し、レンダリングと観察が可能であることを確認します。

reticle_session({ action: "list" })

切断されたタブ、非表示のタブ、またはスロットリングされたタブでは、キー押下が受け付けられても、タイマー、レンダリング、その後の観察が進まないことがあるため、読み取った内容は信頼できません。まず、たとえばリースされたタブなど、利用可能なコンテキストを確保してください。

reticle_run({ tool: "reticle_lease", args: { action: "acquire", url } })

アクションに refuseWhenThrottled: true を渡し、一時停止中のタブが何も起きないままになるのではなく、明確に失敗するようにしてください。正常なセッションを確保できない場合は、実行結果を合格ではなくブロックとして報告し、そのセッションに対して再試行を続けないでください。

コントロールを一覧表示する

キーボードに触れる前に、すべてのインタラクティブなコントロールを一覧表示してください。そうしないと、すでに把握しているコントロールしかテストできません。

reticle_look({ sessionId, action: "page", mode: "interactive" })

各コントロールがフォーカスを受け取れることを確認する

一覧にある各コントロールにフォーカスし、実際にフォーカスされたことをアサートします。

reticle_act({ sessionId, ref, action: "focus" })
reticle_assert({
  sessionId,
  predicate: { kind: "element", query: { testid: "the-control" }, state: "focused" },
})

これで、そのコントロールがフォーカスを受け取れることが証明されます。ただし、そのコントロールが Tab 順序に含まれることは証明されません（tabindex="-1" はフォーカス可能ですが、Tab ではスキップされます）。そのため、Tab で到達可能ではなく、フォーカス可能として報告してください。tabindex のない <div onClick> はフォーカスを受け取れません。これは実際の問題として報告してください。

フォーカスだけでなく、主要なアクションを実証する

フォーカスは前提条件であり、確認すべき内容ではありません。結果を指定してから、キーボードで有効化します。

reticle_act_and_wait({
  sessionId,
  ref,
  action: "press",
  args: { text: "Enter" },
  until: { kind: "element", query: { testid: "expected-result" } },
})

ボタンとリンクでは Enter キーを使います。チェックボックスとネイティブの <select> では Space キーを使い、選択肢には矢印キーも使います。フォームコントロールで合成 Enter を押すとフォームが送信されるため、ここでは Enter による送信を確認できます。カスタムスタイルのコンボボックスは、最も失敗しやすいコントロールです。ネイティブのものと見た目が同じで、click だけをリッスンしていることがよくあります。実際にキーを押してください。クリックに置き換えて、キーボードでも同じように動作すると想定してはいけません。

until の条件はアクションの前から真である場合があり、その場合 already_true ではキー押下について何も証明できません。まず、結果が生じていないことを確認してください。すでに生じている場合は、アプリの状態をリセットしてやり直すか、結果を判定不能として報告してください。テキストが表示されることが要件なら、要素の存在だけでなく表示状態も必須とする述語を使ってください。非表示の要素も存在チェックを満たすためです。推測せずに、reticle_tools({ names: ["reticle_act_and_wait"] }) で正確なフィールドを読み込んでください。

アサートする内容

1. 最初の確認で見つかったすべてのコントロールがフォーカスを受け取れること。それぞれについて、focus アクションと state: "focused" のアサートで実証します。
2. 主要なアクションがキーボードから実行されること。すでに真ではなかった結果を指定する reticle_act_and_wait({ until }) で実証します。

Tab 順序とフォーカストラップは、この一覧に含まれません。どちらも現在は検証できないため、合格ではなく必ず不明として報告してください。

正直さ

各結果を verified（Reticle がその条件について肯定的な判定を返した）、failed、blocked（健全なセッションがない）、または unknown として報告してください。verified: "unknown" または verified: "no-fault" という判定は合格ではありません。unknown は、Reticle が何が起きたか判断できなかったことを意味します。どちらの場合も、そのまま報告し、合格させるためにチェックを緩めてはいけません。観測された証拠は検証済みの結果ではありません。already_true は、あなたの操作がその結果を引き起こした証明にはなりません。また、キー入力が送信されても処理が完了するまで待てなかった場合、操作は完了していません。

見つかったコントロール、そのうちフォーカスを受け取ったもの、押したキーと、待機した結果の正確な内容、Reticle が返した判定、Tab の順序が不明であること、そして結果を制限するスロットリングやタイムアウトを最後に記載してください。

---

機能リファレンス：curl https://docs.reticle.sh/capabilities.md。その他すべて：curl https://docs.reticle.sh/llms.txt。