クロスオリジンのiframeを分析する

Axe Watcherは、ページの残りとともに、同一オリジンの<iframe>要素のコンテンツを分析します。異なるオリジンから提供されるフレームはデフォルトでスキップされ、その中のアクセシビリティの問題は結果から完全に除外されます。

allowedOriginsオプションを使用すると、それらのフレームを分析するように設定できます。カバーしたいオリジンを指定すると、Watcherはそれらから提供されるフレームを、埋め込みページの各分析の一部として分析します。

このオプションは、Watcher 4.6.0以降が必要で、JavaScript/TypeScriptおよびJavaの統合で利用可能です。

必要な場合

ユーザーエクスペリエンスの意味のある部分が別のオリジンから提供される場合にallowedOriginsを設定してください。例えば、ホストされた支払いフォーム、埋め込みの予約やスケジュールウィジェット、独自のコントロールを持つメディアプレーヤー、またはヘルプやチャットウィジェットなどです。

自身のオリジンから提供されるフレームには必要ありません。これらは常に分析されます。

許可されたオリジンの設定

カバーしたい埋め込みオリジンのみをリストしてください。自身のアプリケーションのオリジンは常に許可されるので、含めないでください。

JavaScriptとTypeScript

axe: {
  apiKey: process.env.AXE_DEVELOPER_HUB_API_KEY,
  projectId: process.env.AXE_PROJECT_ID,
  allowedOrigins: [ 'https://pay.example.com' ]
}

Java

AxeWatcherOptions options = new AxeWatcherOptions()
    .setApiKey(System.getenv("ACCESSIBILITY_API_KEY"))
    .setProjectId(System.getenv("PROJECT_ID"))
    .setAllowedOrigins(new String[] {"https://pay.example.com"});
AxeWatcher watcher = new AxeWatcher(options);

信頼できるオリジンを決める

許可リストはすべてのフレームで適用され、トップフレームだけではなく、双方向に機能します。フレームは自分自身のリストにあるオリジンからのみメッセージを受け入れ、それらのオリジンにのみ返信します。実際には、各フレームは自身のオリジンを許可し、リストにある各オリジンを許可し、フレーム自身のオリジンがリストにあるオリジンの一つである場合のみ、それを直接埋め込むフレームのオリジンを許可します。これは、埋め込みがトップレベルページまたはリストされた別のオリジンである場合に限ります。

したがって、オリジンをリストに入れても、フレーム化されるページがどんなものでも応答できるわけではありません。それが許可するのは、テスト対象のページ内でそのフレームとその埋め込み元とのマークアップの交換です。したがって、リストは信頼できる埋め込みに限定するべきです。

これがワイルドカードがサポートされない理由であり、「すべてのフレームを分析する」という意味のオプションがない理由です。列挙できない許可リストは許可リストではありません。各オリジンを明示的に名付け、実際にカバーが必要な埋め込みにリストを制限してください。

テスト中にテスト対象のページが機密情報を表示しているかどうかを考慮してください。テストフィクスチャに現実的な個人情報や支払いデータを使用している場合、それを今から許可しようとする第三者のオリジンと比較検討してください。

オリジンを正しく記述する

各エントリーはオリジンのみでなければなりません: スキーム（httpまたはhttps）、ホスト、およびオプションのポート。Watcherは、提供されたものから末尾のスラッシュとデフォルトのポート（httpには:80、httpsには:443）を削除し、ホストを小文字にし、重複を排除することで標準化します。

Watcherは使用できないエントリーを拒否し、設定が読み込まれたときにエラーを報告します。テストを続行し何も分析しないままであるよりも良いです。Javaでは、setAllowedOrigins()がIllegalArgumentExceptionを投げます。

非英語文字を含むドメイン

café.example.comやпример.рфなど、英字以外の文字を含むドメインは、aからzまでの文字、0から9までの数字、ハイフンだけで構成される第二の、同等の綴りを持っています。この綴りはプニコードと呼ばれ、常にxn--で始まります。ブラウザは使用前にドメインをプニコード形式に変換するため、Watcherはプニコード形式と比較します。

プニコード形式を見つけるには、フレームのURLを訪れ、ページが読み込まれた後でブラウザのアドレスバーを確認するか、オンラインのプニコード変換ツールを使用してください。

cafe.example.com を café.example.com のように、見た目が似ている英文字の綴りに置き換えないでください。Watcherはそれを有効なオリジンとして受け入れますが、フレームの実際のオリジンと一致することはなく、そのフレームは黙って分析されないままの状態になります。

<same_origin> および <unsafe_all_origins> キーワード

Watcherが使用するアクセシビリティエンジンであるaxe-coreは、自身の同等設定で2つのキーワードを受け入れます。axe-coreのドキュメントまたは移行中の設定でこれらに出会うことがあります。

• <same_origin>は「このページ自身のオリジン」を意味します。Watcherはこれを受け入れますが、効果はありません。あなた自身のオリジンは常に許可されているからです。
• <unsafe_all_origins>は「まだリストされていないオリジンを含む、すべてのオリジン」を意味します。Watcherは信頼できるオリジンを決めるで説明された理由からこれをエラーで拒否します。

フレーム内での変更を検出する

自動分析はトップレベルのページに対する変更を検出します。内部フレーム内で行われた変更は検出できません。同一オリジンであろうとクロスオリジンであろうと関係ありません。そのため許可されたフレームは、トップレベルページの最後の変更時点で分析されます。

このことは、フレーム内のコンテンツと対話する際に重要です。対話がフレームのコンテンツを変更しても、トップレベルページは変更されず、したがって自動分析は実行されません:

// Interacting inside the frame doesn't trigger an automatic analysis
await page.frameLocator('#pay').getByRole('button', { name: 'Continue' }).click()

// Analyze explicitly to capture the resulting state
await controller.analyze()

インタラクションの後にanalyze()を呼び出して、結果の状態をキャプチャします。明示的に要求された分析は常に実行されます。テストフレームワークでコントローラーオブジェクトを取得する方法についてはスキャンを制御するを参照してください。

欠落しているフレームを見つける

Watcherは、allowedOriginsを設定しているかどうかに関わらず、スキップされたクロスオリジンフレームを報告します。これにより、設定を行う前にどの埋め込みが結果から欠落しているかを発見することができます。

cross_origin_frame_not_allowlisted診断は、スキップされたそれぞれのオリジンを名前付きで列挙し、設定に貼り付けるためのallowedOrigins行が含まれています。多くのサードパーティの埋め込みがあるページでは、リストが制限され、残りは「さらにN件」のように要約されます。

診断はデバッグ出力にのみ表示され、それぞれのテスト実行につき一度だけ報告されます。

JavaScriptおよびTypeScript:テストを実行する際にDEBUG環境変数を設定します。

DEBUG=axe-watcher:* npx playwright test

Java:コントローラーは各診断をDEBUGレベルでログに記録するので、Axe WatcherのDEBUGメッセージを表示するようログフレームワークを設定してください。Selenium統合を使用している場合は、AxeWatcherに対してenableDebugLogger()を呼び出すこともできます。

他の2つの診断は許可されたがまだ分析されていないフレームを報告します。両方とも制限の下で説明されています。

• cross_origin_frame_unscannable、allow-same-originを含まないサンドボックス化されたフレームの場合。
• cross_origin_frame_timed_out、時間内に結果を返さなかったフレームの場合。

フレームのカバレッジがデバッグ出力ではなく結果に表示されるようにしたい場合、ベストプラクティスを有効にします。axe-core frame-testedルールは「このフレームには問題がない」と「このフレームは分析されたことがない」を区別します。Watcherが到達できなかったフレームはレビューが必要と報告されます。これはベストプラクティスルールであるため、WCAGルールのみに限定されたルールセットでは省かれます。

フレーム内で見つかった問題は、フレームを埋め込むページのページ状態に帰属され、独自のページ状態には帰属されません。

制限事項

最もよく直面する制限は、フレーム内で行われた変更のキャプチャで説明されているように、自動分析がフレーム内で行われた変更を認識できないことです。その他の制限については以下をご覧ください。

サンドボックス化されたフレームにはallow-same-originが必要

sandbox属性がallow-same-originを省略しているフレームは、そのオリジンが不透明であるため、許可リストのどのエントリーでも名前を指定できず、リストに載せたとしても分析できません。そのオリジンを記載した後、Watcherはそのcross_origin_frame_unscannable診断を報告します。それまでの間は、他のスキップされたフレームと同様にcross_origin_frame_not_allowlistedとして報告されます。そのフレームを分析するためにはallow-same-originをsandbox属性に追加します。

ここで重要なのはallow-same-originだけです。allow-scriptsを省略したサンドボックス化されたフレームは、フレームがページの独自のスクリプトによってブロックされている場合でも、Watcherのコンテンツスクリプトが分断された環境で実行されるため、通常通り分析されます。

リダイレクトされる埋め込み

srcが、wwwへのリダイレクトやhttpがhttpsへリダイレクトするような他のオリジンにリダイレクトされる埋め込みは、リストに載せたオリジンではないオリジンに着地するため、分析されません。実際に対象となるフレームが到達するオリジンをリストに載せ、そのsrcとの違いを明確にします。

複数レベル深くにネストされたフレームは報告されない

フレームカバレッジ診断は、直接埋め込まれたフレームに関してトップレベルのページから報告されます。到達できないが2レベル以上深くネストされたフレームは、その内容が結果から欠落しているにもかかわらず、デバッグ出力には表示されません。

応答しないフレームが分析に失敗する

Watcherの最初のピンに応答するが、結果を返さないフレームは、分析が失敗したと見なされます。Watcherはcross_origin_frame_timed_out診断を報告します。遅いサードパーティ埋め込みがこれを行う場合は、そのオリジンをallowedOriginsから削除するかrunOptions.frameWaitTimeを引き上げてください。

遅い分析への対応

許可した各オリジンが、そのフレームのコンテンツ全体をページの各分析に追加します。フレームのコンテンツは収集され、トップレベルのページに転送され、結果の残りと結合されます。このすべてがテスト待機中に行われます。

この時間の増加は、フレーム内コンテンツのサイズと複雑さ、及び許可するフレームの数に比例して増加します。自動分析が有効になっていると、Watcherが分析するすべてのインタラクションで同様のコストがかかります。複数のフレームが許可された長いテストスイートでこれを行うと、かなりの時間が必要になることがあります。管理を容易にするための2つの方法は次のとおりです。

• allowedOriginsを実際にカバーが必要な埋め込みに限定し、そのページ上のすべてのサードパーティオリジンではないものにしてください。
• プロジェクトやテストスイートごとに有効にすることを検討し、フレームコンテンツを利用しないスイートがこれに対するコストを負わないようにしてください。

オプションを有効にする前後の代表的な実行時間を計測し、自身のスイートへの影響を考慮してください。

タイムアウト

クロスオリジンフレームを分析する際には、そのフレームが応答するのを待つ必要があるため、allowedOriginsが空でない配列に設定されている状態では、デフォルトのanalyzeおよびflushタイムアウトが5000msから10000msに変わります。startおよびstopのデフォルトは変更されません。自分で設定したタイムアウト値はそのまま使用されるため、この変更はデフォルト値のみに影響します。タイムアウトを設定するを参照してください。

これはJavaScriptおよびTypeScriptの統合に適用されます。Java Watcherは現在カスタムタイムアウトをサポートしておらず、このオプションによるタイムアウト値の変更もありません。

独自のタイムアウトを設定してからallowedOriginsを有効にする場合は、見直してください。フレームコンテンツがないページに最適化された値は、今では厳しすぎるかもしれません。

関連トピック

• タイムアウトを設定する
• スキャンを制御する
• ベストプラクティス
• トラブルシューティング
• WatcherのJavaScriptおよびTypeScript版のAPIリファレンス
• AxeWatcherOptions