トラブルシューティング

This page is not available in the language you requested. You have been redirected to the English version of the page.
Link to this page copied to clipboard

Axe Watcherの一般的な問題と解決策

Not for use with personal data

Watcher は テスト用Chrome、Chromium、または Microsoft Edge のみをサポートします

Axe Developer Hubのウェブサイトは複数のブラウザをサポートしていますが、Watcherパッケージはテスト用Google Chrome、Chromium、またはMicrosoft Edgeのみをサポートしています。考えられる問題点は次の通りです:

  • Google Chromeバージョン139以降を使用すると、Watcherからエラーが出ります。代わりに、Chrome for Testing、Chromium、またはMicrosoft Edgeを使用してください。
  • CypressのElectronブラウザーを使用すると、エラーが発生します。Cypressを起動する際にブラウザーをテスト用Chrome、Chromium、またはMicrosoft Edgeに指定してください。そうしないと、デフォルトでElectronブラウザーが使用されます。詳細はCypressのドキュメントのブラウザの起動をご覧ください。

WebdriverIO、WebDriverJS、またはJava Seleniumを使用する場合、テストセットアップをChrome for TestingまたはMicrosoft Edgeを明示的に使用するように構成する必要があります。インストール手順やプラットフォーム固有の設定例についてはテスト用Chromeの使用を参照してください。

Watcherでサポートされるソフトウェアの詳細については自動テストプラットフォームをご覧ください。

Microsoft EdgeがJava Seleniumで失敗する

Java Selenium テストがメッセージ Microsoft EdgeのサポートにはSelenium 4以降が必要です を持つ IllegalStateException をスローする場合、プロジェクトは Selenium 3 を使用しています。Selenium 3 のEdgeOptionsはレガシーな EdgeHTML ブラウザを対象としており、Axe Watcher はサポートしていません。Microsoft Edge でテストするには selenium-java を 4.x にアップグレードするか、Selenium 3.141.59 以降で Java Selenium 統合がサポートしている ChromeOptions と ChromeDriver を使って Chrome for Testing または Chromium でテストを続けてください。

WebdriverIO を使用した Microsoft Edge で結果が出ない

WebdriverIO のテストが Microsoft Edge で実行され、エラーなく完了し、Axe Developer Hub で結果が何も出ない場合は、Watcher のバージョンを確認してください。Microsoft Edge を WebdriverIO で使用するには、Watcher 4.6.0 以降が必要です。

以前のバージョンでは、Watcher はそのブラウザーオプションを goog:chromeOptions 機能に送信していました。Microsoft Edge WebDriver はこれらを ms:edgeOptions から読み取るため、オプションは無視され、解析は行われませんでした。何も失敗せず、テストは空の結果セットで成功したのでした。問題を解決するには 4.6.0 にアップグレードしてください。

ブラウザー機能のargsプロパティが無効です

Watcher が args プロパティが goog:chromeOptions または ms:edgeOptions ブラウザー機能で文字列の配列である必要があると報告した場合、args をブラウザーのコマンドラインフラグの配列に設定するか、削除してください。

capabilities: {
  browserName: 'MicrosoftEdge',
  'ms:edgeOptions': {
    args: ['--window-size=1280,720']
  }
}

単一の文字列やオブジェクト、または文字列以外のものを含む配列などの値は拒否されます。Watcher 4.5.0 以前ではこれらのいくつかを受け入れていましたが、後で関係のないエラーで失敗しました。

クロスオリジン iframe 内のアクセシビリティ問題が欠落している

解析が成功しても、テスト中のページとは異なるオリジンから提供される <iframe> から結果が何も出ない場合、そのフレームは解析されていません。Watcher は常に同一オリジンフレームを解析しますが、クロスオリジンフレームはそのフレームのオリジンを一覧に追加した場合のみ解析します。

axe: {
  allowedOrigins: [ 'https://pay.example.com' ]
}

常に許可されているため、独自のアプリケーションのオリジンは含めないでください。

スキップされたオリジンを確認するには、cross_origin_frame_not_allowlisted診断を探してください。それはオプションを設定したかどうかに関係なく報告され、解析されなかったクロスオリジンのオリジンを名前で示し、貼り付けできる設定行を表示します。診断はデバッグ出力にのみ表示されます：（JavaScript または TypeScript）の場合、テストを実行するときに DEBUG=axe-watcher:* を設定するか、（Java）では Axe Watcher のためにDEBUGメッセージを表示するようにログフレームワークを構成してください。Java Selenium 統合では、enableDebugLogger()でデバッグロギングを有効にすることもできます。

オリジンを一覧に追加しても結果がまだ欠落している場合：

  • フレームには sandbox 属性があり、allow-same-origin を省略して cross_origin_frame_unscannable として報告されています。そのため、フレームにはリスト内のエントリで名前指定できない不透明なオリジンがあります。 allow-same-origin をsandbox属性に追加してください。
  • フレームがsrcのオリジンからリダイレクトされる場合、たとえば、トップレベルドメインがwwwにリダイレクトされる、またはhttpがhttpsにリダイレクトされる場合には、実際にフレームが到達するオリジンを一覧に追加してください。
  • フレームが 1 レベル以上深くネストされている場合。カバレッジ診断は直接埋め込まれているフレームに関してトップレベルページから報告されるため、深くネストされたフレームは報告されません。

解析が単に失敗している場合、cross_origin_frame_timed_out診断を確認してください。フレームが Watcher の最初の ping に応答したが、期限内に結果を返さなかったことが示されています。そのオリジンをリストから削除するか、runOptions.frameWaitTimeを引き上げてください。

フレームが解析されても、その結果がテスト内で実行された内容を反映していない場合、自動解析が原因です。フレーム内で行われた変更を検出できないため、許可されたフレームはトップレベルページの最後の変更時に解析されます。フレーム内のコンテンツと対話した後に analyze() を自分で呼び出してください。これはブラウザーのコンテキストがフレームに切り替わったときに適用される子フレームに切り替えた後のページ状態はキャプチャされませんとは別の問題です。

全体像については、クロスオリジン iframe の解析を参照してください。

allowedOriginsによって拒否されたオリジン

Watcher が allowedOrigins エントリが無効であると報告した場合、エントリはフレームと比較可能な単なるオリジンではありません。各エントリにはスキーム（http または https）、ホスト、およびオプションのポートが必要で、それ以外は存在しません。一般的な原因は次の通りです。

  • https://*.example.com のようなワイルドカード。すべてのオリジンを明示的に名前指定してください。
  • パス、クエリ文字列、フラグメント、または https://pay.example.com/checkout のような資格情報。
  • pay.example.com のようなスキームが欠落している。
  • httpまたはhttps以外のスキーム。
  • 英字以外の文字を含むドメイン、例えば café.example.com 。代わりに Punycode 形式を使用してください。

これらは無視されるのではなく、実際のオリジンと一致しないエントリがテストの成功とともにフレームを未解析のままにしてしまうため、却下されます。詳細は クロスオリジン iframe の解析 を参照してください。

不完全な結果

テストスイートが複数のテストランナーを並行して使用しており、同じ非ヌルのビルドIDを使用している場合、テストランナーごとの結果が同じGitコミットSHAの他のテストランナーの結果を上書きし、不完全な結果になります。各テストランナーが同じ非ヌルのビルドIDを使用するようにする必要があります。

important
  • JavaScript/TypeScript: buildID（大文字D）
  • Java: buildId（小文字d）

通常、ビルドIDはAxeConfigurationで設定します。

異なるCI/CDプラットフォームで並列テストランナーを使用する方法の詳細についてはテストの並行実行をご覧ください。

重複したアクセシビリティエラーまたは新しい問題の数が間違っている

あなたのウェブサイトがページを更新するたびに変わる動的なIDを使用している場合、特に以前のテストで同じ要素に同じ問題が表示されたとされる新しいとマークされた問題について、重複したアクセシビリティエラーが発生する可能性があります。(Axe Developer Hub は CSSセレクターと XPath によってテスト間で同一の要素を特定しますが、これらには要素のIDが組み込まれています。) この問題を解決するには、設定のrunOptionsオブジェクト内のancestryプロパティをtrueに設定する必要があります。以下の例は、設定オプションをどのように設定するかを示しています。

axe: {
  runOptions: {
    ancestry: true
  }
}

動的セレクターの使用に関する詳細なガイダンスについてはに関するガイダンスについては、をご覧ください。

ancestryを有効にした後も問題が解消されない場合は、テストが訪れるURLが実行間で変わっているかどうかを確認してください。セッションIDやキャッシュバスティングパラメータを含むクエリ文字列を含め、URLは完全に比較されるため、ページ上のすべての問題が新しいもののように見えてしまいます。動的URLを参照してください。

詳細については（JavaScript/TypeScript）runOptionsまたは（Java）AxeWatcherOptions.setRunOptions()をご覧ください。

旧バージョンの@axe-core/watcher

バージョン3.18.0またはそれ以前の@axe-core/watcherを使用している場合、次の警告メッセージが表示されます:

@axe-core/watcherパッケージが古すぎてグローバル設定をサポートできない場合に表示されるメッセージのスクリーンショット

Axe Developer Hubは現在Axe設定で定義された設定に従っています。バージョン3.18.0以前の@axe-core/watcherが生成するテスト走行は、Axe設定のグローバル設定を認識せずにセッションを生成します。@axe-core/watcherパッケージを更新して、エンタープライズのAxe設定に従ったセッションを作成するためにテストを再実行してください。詳しくはUsing Global Configurationsをご覧ください。

子フレームに切り替えた後のページ状態はキャプチャされません

テストが switchToFrame() (WebdriverIO または WebDriverJS) や switchTo().frame() (Java Selenium) を使用してブラウザーの現在のコンテキストを子フレームに切り替える場合、Axe Watcher は、ブラウザーが子フレームにフォーカスを当てている間に行われたアクションのためのページ状態をキャプチャしません。Axe Watcher は、ブラウザーのコンテキストがトップレベルのフレームにある間のみページ状態をキャプチャします。

これは iframe コンテンツが解析されるかどうかとは別の問題です。Watcher は同一オリジンフレームと、オリジンを一覧に挙げたクロスオリジンフレームを解析します。クロスオリジン iframe の解析 を参照してください。

例えば、WebdriverIOでは、以下のclick()呼び出しはページ状態を生成しません:

await browser.url('https://example.com')
const iframe = await browser.$('iframe')
await browser.switchToFrame(iframe)
// Actions taken in the child frame will not be analyzed
await button.click()

ページ状態のキャプチャを再開するには、先にトップレベルのフレームに切り替えてから続行してください。

// WebdriverIO
await browser.switchToParentFrame()

// WebDriverJS / Java Selenium
await driver.switchTo().defaultContent()
note

Cypress はこの制限の影響を受けません。

PlaywrightのsetContent()メソッドはサポートされていません

Axe WatcherはPlaywrightのpage.setContent()またはframe.setContent()メソッドを呼び出すテストをサポートしていません。この制限はJavaScript/TypeScriptパッケージとJavaライブラリの両方に適用されます。

これらのメソッドは、内部でdocument.write()を使用してドキュメント全体を置き換え、Axe Watcherがページを分析するために依存するコンテキストを破棄します。Axe Watcherは呼び出しのポイントまでページを正常に分析しますが、その後はページを分析したり結果を送信したりすることができなくなり、タイムアウトメッセージに類似したエラーが発生してテストが失敗します。

Error: Watcher timed out before it could finish analyzing the page state. To resolve this problem, increase the `timeout.analyze` property within your configuration or see https://docs.deque.com/developer-hub/2/en/dh-troubleshooting for more troubleshooting.

Error: Watcher timed out sending results to the server. To resolve this problem, increase the `timeout.flush` property within your configuration or see https://docs.deque.com/developer-hub/2/en/dh-troubleshooting for more troubleshooting.
important

これらのメッセージが示唆する内容に反して、timeout.analyzeおよびtimeout.flush値を増やしてもこの問題は解決しません。タイムアウト調整が役立つ場合についてはSet Timeoutsを参照してください。

マークアップを直接設定する代わりに、URLからそれを配信し、page.goto()でナビゲートしてブラウザが通常通りにドキュメントをロードするようにします。

// Not supported by Axe Watcher:
await page.setContent('<my-button disabled></my-button>')

// Navigate to a URL that serves the same markup instead:
await page.goto('http://localhost:6006/my-button.html')

cy.screenshot()によって生成される余分なページ状態

Cypressテストでcy.screenshot()を呼び出すと、Axe Watcherが余分なページ状態を生成することがあります。Cypressがスクリーンショットを撮る際に、アニメーションを無効にするために一時的にDOMを変更し、Axe WatcherのDOMオブザーバーがその変更をページ状態の変更として検出する場合があるためです。これは想定された動作であり、アクセシビリティ結果の精度には影響しません。

コントローラーメソッドのタイムアウト

important

Java Watcherは現在、タイムアウト値の変更を許可していません。

（JavaScriptまたはTypeScriptのみ）コントローラーメソッド（Controller抽象基底クラスで定義されたanalyze()、flush()、start()、およびstop()）またはCypressのカスタムコマンドの呼び出しがタイムアウトした場合、次のようなメッセージを受け取ります。

Error: Watcher could not send results to the server. To resolve this problem, adjust your `timeout.flush` property within your configuration or see https://docs.deque.com/developer-hub/wa-troubleshooting for more troubleshooting.

指定されたControllerメソッド（ここではflush()メソッド）がデフォルトの時間以上を必要とし、タイムアウトしました。デフォルトの時間はtimeoutオブジェクトを設定に追加して変更できます。

axe: {
  timeout: {
    flush: 10000
  }
}
important

これらのタイムアウト値は、使用しているテストフレームワークとは独立しており、そのフレームワークのタイムアウト値も増やす必要があるかもしれません。

タイムアウトの使用に関する情報についてはSet Timeoutsをご覧ください。

詳細はTimeoutsインターフェースおよびtimeoutsをご覧ください。デフォルトのタイムアウト値は、Timeoutsインターフェースの下の表に示されています。

結果が表示されない

テストスイートを実行しても、特定のプロジェクトに対する結果がAxe Developer Hubに表示されない場合、その原因は以下のセクションに示された理由にあります。

Axe Watcherを設定していない

修正したテストスイートは、テストを実行する前にテストフレームワークに適した設定関数を呼び出す必要があります。Axe Watcherを正しく設定しないと、Axe Watcherを設定する必要があるというメッセージが表示されます。例えば、CypressでAxe Watcherの設定を忘れると、テストスイートを実行した際にこのメッセージが表示されます。

Cypress is not configured for axe Watcher. Please ensure that axe Watcher's cypressConfig() is invoked within Cypress's defineConfig() in your cypress.config.js. All tests will fail with this error.

設定の手順で、言語およびブラウザーテストフレームワークの設定例を参照してください。

結果をフラッシュしない

収集された結果をDequeのサーバーに送信して、Axe Developer Hubウェブサイトで結果を表示できるようにするには、対応するflush()機能（またはCypressでのカスタムコマンドaxeWatcherFlush()）を呼び出す必要があります。通常、flush()機能を自動化プラットフォームのクリーンアップフックで呼び出します。

例えば、Cypressのsupport/e2e.jsファイルでは、afterEach()の呼び出しを追加します。

// Flush axe-watcher results after each test.
afterEach(() => {
  cy.axeWatcherFlush()
})

--incognito オプションの使用

Chromeで--incognitoコマンドラインオプションを使用することはできません。そうしないと、テストが静かに失敗します。インコグニートモードを使用してキャッシュファイルをディスクに書き込まないようにする場合（キャッシュファイルはインコグニートモードでのみメモリに保持されます）、テストスイートのキャッシングメソッドを使用してください。

必要な環境変数を設定していない

watcher-examples リポジトリのサンプルを試している場合、サンプルはAPIキーとプロジェクトIDを設定するために環境変数を使用していることに注意してください。API_KEYとPROJECT_ID。

テストが早すぎる

テストが早すぎて、Watcherが分析する前にページをアンロードし、リソースを解放することがあります。この問題を修正するには、テストの最後に遅延を追加してページを分析する時間を確保してください。

例えばCypressでは、cy.wait()メソッドを使って10秒の遅延（10,000ミリ秒）を追加できます。

describe('Visitor', () => {
  it('should visit example.com', () => {
    cy.visit('https://www.example.com')
    cy.wait(10000);  })
})

APIキーの欠落または無効

無効または欠落したAPIキーは、Cypressで無効な設定ファイルとして表示されます。スタックトレースはそれが無効か欠落しているかを明らかにします。欠落しているキーは次のように表示されます。

AssertionError [ERR_ASSERTION]: API key is required
    at validateApiKey ...

（スタックトレースの多くの行は省略されました。）

キーは次のスタックトレースの結果になります（短縮版）： キーは次のようなスタックトレースを生成します（短縮版）：

Error: Server responded to https://axe.deque.com/api/api-keys/test/validate/axe-devtools-watcher with status code 404:
{"error":"Invalid API key"}
    at Response.getBody
...

ヘルプ

問題を解決できない場合は、メールでご連絡までご連絡ください。

Is this page helpful?

Help us improve this page

Still need help?