Seleniumテストを書く
Java用のAxe DevTools for Webを使ったSelenium WebDriverによるアクセシビリティテストの書き方
このAxe DevTools構成は、いかなるアサーションライブラリにも固有の結びつきはありません。これにより、シンプルなアクセシビリティテストだけでなく、テストのカスタマイズや独自のアサーションを用いた使用も可能になります。
前提条件
Axe DevTools Java Seleniumを使用して結果を生成するには、すでにAxe DevToolsを使ってテストファイルを作成し、選択したSelenium WebDriverをインポートして初期化しておく必要があります。このステップを完了していない場合は、まずこのガイドを読んでその方法を確認してください。
スキャンを実行する
この構成では、基本的なアクセシビリティスキャンはたった3行のコードで実行できます。テストファイル内で、テストしたいページのウェブアドレスに<URL>を置き換えてください。スキャン結果はresults変数に保存されます。
webdriver.get("<URL>");
Results results = axeSelenium.run(axedriver);
webdriver.quit();スキャン結果の利用
スキャンを実行したら、結果を活用したいと思うかもしれません。最も簡単な方法は、結果をコンソールに出力することです。
System.out.print(results);また、結果を使ってアクセシビリティ違反をチェックすることもできます。これを行う最も簡単な方法は、次のようなステートメントを使用することです。
if (!results.violationFree()) {
//do something, like throw an exception
}結果オブジェクトを活用してカスタムテストを作成する方法について詳しくは、結果を使用するのページを参照してください。
サンプルテストファイル
このテストファイルは、インポートと初期化でカバーされた同じ基本構築ブロックと、このページのテストを書くガイドに基づいています。
import com.deque.html.axedevtools.selenium.*;
import com.deque.html.axedevtools.selenium.results.*;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
public class Example {
public static void main(final String[] args) {
AxeSelenium axeselenium = new AxeSelenium();
WebDriver webdriver = new ChromeDriver();
AxeDriver axedriver = new AxeDriver(wd);
webdriver.get("<URL>");
Results results = axeselenium.run(axedriver);
webdriver.quit();
if (!results.violationFree()) {
int violationCount = results.getViolations().size();
System.out.printf("Found %d violations!\n", violationCount);
System.exit(1);
}
System.out.println("No violations found!");
}
}この例では、ChromeとChromeDriverを使用します。これを他のSeleniumブラウザドライバとブラウザに置き換えることができます。このテストファイルがアクセシビリティの問題を発見した場合、見つかった違反の数を出力し、ステータスコード1(エラー)で終了します。このテストファイルを自身の環境で使用するには、行にURLを追加する必要があります。
webdriver.get("<URL>");追加の参考資料
上記の基本的な使用法に加えて、Axe DevTools Java Selenium は、スキャンの実行方法を修正するためのいくつかのチェーンメソッドを提供しています。これらのメソッドにより、スキャンの範囲やルールセットを希望する構成に変更できます。デフォルトでは、ページ全体がスキャンされ、WCAG 2.1 レベル AA ガイドラインに基づいてアクセシビリティ違反がチェックされ、ベストプラクティスと実験的なルールは無効になっています。これらのチェーンメソッドの設定は AxeSelenium オブジェクトに残り、include と exclude は呼び出すたびに前のエリアに追加されるので、異なる構成のスキャンのために1つのオブジェクトを再利用すると、最初のスキャンの設定が引き継がれます。異なる構成のスキャンごとに新しい AxeSelenium を作成してください。
スコープ設定
デフォルトでは、ページ全体がスキャンされます。ただし、Axe DevTools ではスコープチェーンメソッドによってページの特定部分をスキャンする機能をサポートしています。これらのスコープメソッドは、スキャン対象のページの「表面積」を希望のターゲットエリアに効果的に変更します。さらに、違反を無視するメソッドも利用可能です。このメソッドは、スキャンの範囲を縮小することはなく、特定の要素でルールが失敗したとき、そのルールの違反を無視し、残りのページは通常通りチェックされます。これらのすべてのメソッドは CSS セレクタ領域に基づいて動作します。与えられたページ上の各 CSS セレクタの領域は、ブラウザの開発ツールの「要素を検査」ウィジェットを使用することで確認できます。
スコープメソッド
前述のとおり、これらのメソッドはページをスキャンする対象領域を効果的に変更します。このカテゴリには、「包括的」メソッドと「排他的」メソッドの2つのメソッドがあります。それらは互いにチェーンして、スキャンする領域を含む複数のエンクレーブと除外を作成できます。
スコープ - 包括
include スコープチェーンメソッドは、指定された CSS セレクタで指定されたページエリア内のみでスキャンを実行するようにスキャンを変更します。include メソッドを使用する方法は、単一スコープ、複数スコープ、複合スコープ、IFrame スコープなど、いくつかの方法があります。
このメソッドは、単一のセレクターで以下のように使用できます:
axeselenium.include("#selector1").run(axedriver);このスキャンは、セレクター1の範囲内でのみ実行されます
複数のスコープでスキャンを設定することができます:
axeselenium.include("#selector1").include("#selector2").run(axedriver);この呼び出しは、セレクタ1およびセレクタ2のスコープ内をスキャンします。それらはカンマで区切るか、別の include 呼び出しで宣言できます。
複合スコープは以下の構文で達成できます:
axeselenium.include("#selector1 .selector2").run(axedriver);この複合スコープは、セレクター2内のセレクター1を持つ要素のみがスキャンされる結果となります。これは、セレクターをカンマで区切らないことで設定されます。
iFrame内でスコープを設定するには、List<String>を渡すことができます。iFrame内でスキャンするスコープは追加のパラメーターとして渡されます。
axeselenium.include(Arrays.asList(new String[] {"#frame1", "#selector1"})).run(axedriver);このスキャンは、フレーム1内のセレクター1の要素で実行されます。
複数のiFrame内でスコープを設定するには、標準の複数選択と同じ方法で行います。includeを再度呼び出します。
axeselenium.include(Arrays.asList(new String[] {"#frame1", "#selector1"}))
.include(Arrays.asList(new String[] {"#frame2", "#selector2"})).run(axedriver);このスキャンは、フレーム1内のセレクター1と、フレーム2内のセレクター2の中のみで実行されます。
ネストされたiFrame内でスコープを設定することも可能です:
axeselenium.include(Arrays.asList(new String[] {"#frame1", "#frame2", "#selector1"})).run(axedriver);このスキャンは、フレーム2内のセレクター1の範囲内で実行され、さらにそれはフレーム1内にあります。
スコープ - 排除
include チェーンメソッドに加えて、この API には exclude メソッドがあります。このメソッドは、指定したスコープの外にある要素のみがスキャンされるように変更します。その設定と使用法は include メソッドと同じですので、詳細や使用例については上記のセクションを参照してください。重要な点として、include と exclude メソッドは、お互いにチェーンすることで、include または exclude のみを使用するよりもはるかに簡単に複雑なスコープを作成できます。
この例は、include と exclude メソッドを組み合わせる一つの方法を示しています:
axeselenium.include("#selector1").exclude("#selector2").run(axedriver);このスキャンは、セレクター1の内側でセレクター2の内側ではないページの部分のみで実行されます。
スコープ - 違反の無視
最後のスコープ関連のチェーンメソッドは、結果を無視するメソッドです。このメソッドはスキャンの全体的なスコープを変更せず、特定の要素でルールが失敗したときに、そのルールの違反を無視します。結果に表示されるように無視したい要素の target をルールと一緒に渡すことで機能します。ターゲットは、Java が一覧を出力する方法で記述され、セレクタが括弧内に入っています。例:"[.sidebar]"。ルールごとに1回の ignoring 呼び出しで十分です。マッチするとルールの全体的なエントリが削除されます。同じルールで2回呼び出さないでください:両方のターゲットが失敗する要素にマッチすると、スキャンは IllegalStateException を投げます。
axeselenium.ignoring("[.sidebar]", "color-contrast").ignoring("[#branded-content]", "image-alt").run(axedriver);このスキャンは、サイドバーの色の対比違反と、ブランドコンテンツ画像の代替テキスト違反を無視します。ターゲットがルールに失敗する要素にマッチすると、そのルールのエントリ全体が他の要素の失敗を含めて違反から削除されます。APIリファレンスのAxeSelenium.ignoring(String, String)を参照してください。
ルール
各スキャンのルール構成を変更する方法は3つあります。これらの異なるメソッドは、テストするルールを選択する際に異なる粒度を提供します。最も粗い粒度のルールセットメソッドは、一般的なアクセシビリティ基準に基づいてルールセット、またはより大きなルールグループを選択します。やや細かい粒度のルールセット標準メソッド、別名タグは、より大きなアクセシビリティ標準のどの領域に属するかに基づいてルールを選択します。最後に、1つのルールを単位として構成するオプションが3つあります。これらのチェーンメソッドを組み合わせることで、実行したい特定のルールにまでスキャンを調整できます。
axe-coreルールに関する情報は、ルールセット概要ページをご覧ください。
ルールセットの選択
このメソッドは、ルールセットという最も集約された関連付けによってルールを選択します。ルールセットとは、業界全体のアクセシビリティ標準に関するすべてのルールの集まりです。WCAG 2.0、2.1、および2.2のルールセット、ADAセクション508、Trusted Tester v5、EN 301 549、RGAA。さらに、最良の実践ルールはブール値のフラグで有効にすることができます。
ルールセットはしばしば、より具体的な区分でまとめられたルールの複数のタグで構成されます。例えば、wcag2ルールセットには、wcag2aWCAG 2.0レベルAルール、wcag2aaWCAG 2.0レベルAAルール、wcag2aaaWCAG 2.0レベルAAAルールがタグ付けされたすべてのルールが含まれています。
ルールセットを修正せずに選択したい場合、このオプションを使用します。
axeselenium.forRuleset("wcag2.1").run(axedriver);このスキャンはWCAG 2.1ルールのみで実行されます。
最良の実践ルールを有効にするには、forRulesetの第2の形式を使用します。
axeselenium.forRuleset("wcag2.1", true).run(axedriver);標準選択
アクセシビリティ標準、またはタグ、チェインメソッドは、axe-coreのルールセット内で若干の細分化を可能にします。WCAGに基づくルールで、このメソッドはシングルAまたはダブルAにタグ付けされたルールのみを選択することができます。このリストは、利用可能なタグ名とそれに対応する標準を示しています。
このオプションは、特定の部分のルールセットのみをテストしたい場合、例えばWCAG 2.0の下のシングルAルールのみの場合に特に有用です。
| タグ名 | アクセシビリティ標準 |
|---|---|
| wcag2a | WCAG 2.0 レベルA |
| wcag2aa | WCAG 2.0 レベルAA |
| wcag2aaa | WCAG 2.0 レベルAAA |
| wcag21a | WCAG 2.1 レベルA |
| wcag21aa | WCAG 2.1 レベルAA |
| wcag21aaa | WCAG 2.1 レベル AAA |
| wcag22a | WCAG 2.2 レベルA |
| wcag22aa | WCAG 2.2 レベルAA |
| wcag22aaa | WCAG 2.2 レベルAAA |
| section508 | セクション508 |
| EN-301-549 | EN 301 549 |
| RGAAv4 | RGAA バージョン4 |
| TTv5 | Trusted Tester v5 |
| ベストプラクティス | Dequeが推奨するベストプラクティス |
特定のアクセシビリティ標準の一部として明示的に定義されてはいませんが、私たちは「ベストプラクティス」と呼ばれるいくつかのルールを提供しています。厳密には必要ありませんが、これらのルールでテストすることで、あなたのウェブサイトは利用可能な限り均等になります。
1つの標準を選択するには、次のようにします:
axeselenium.accordingTo("wcag2a").run(axedriver);このスキャンは、WCAG 2.0レベルAにタグ付けされたルールのみで実行されます。
さらに、複数のタグを指定して、複数のアクセシビリティ標準を選択できます:
axeselenium.accordingTo("wcag2a", "section508").run(axedriver);これらのスキャンは、WCAG 2.0レベルAおよびADAセクション508にタグ付けされたルールの両方を実行します。
ルール選択
最後に、個別のルールによってルールセットを変更することができます。axe-coreのすべてのルールの名前と各ルールが何をテストしているかについての情報は、axe-coreのルール記述ドキュメントを参照してください。
これらの方法は、既存のルールセットや標準/タグからわずか数個の個別のルールが異なるだけの場合に有効です。完全にカスタマイズされたルールセットを構築するには、当社のカスタムルールオプションをご覧ください。
追加ルールのチェック
チェックチェインメソッドを使用すると、標準のルールセットに加えてテストする追加ルールを追加できます。
このメソッドは、単一の追加ルールをチェックするために使用できます:
axeselenium.checking("label").run(axedriver);スキャンがデフォルトのルールセットに加えて「label」ルールで実行される場合。
複数の追加ルールを確認するには、それらをすべて1回の呼び出しで渡します。2回目に checking を呼び出すと、最初の呼び出しからのルールが置き換えられます。
axeselenium.checking("label", "tabindex").run(axedriver);スキャンがデフォルトのルールセットに加えて「label」および「tabindex」ルールで実行される場合。
指定されたタグに単一または複数のルールを追加するためにも使用できます。
axeselenium.accordingTo("wcag2a").checking("tabindex").run(axedriver);スキャンがWCAG 2.0レベルAのルールに対して実行され、「tabindex」ルールが追加される場合。
ルールのスキップ
チェックメソッドと類似して、スキップメソッドも指定されたルールによりデフォルトのルールを変更します。しかし、それらをルールセットに追加するのではなく、スキップメソッドはテストに使用されるルールから指定されたルールを削除します。その設定と使用法はチェックメソッドと同様ですので、詳細や使用例については上記のセクションを参照してください。
axeselenium.accordingTo("wcag2a").skipping("label").run(axedriver);この例は、WCAG 2.0 レベル A のルールに対してテストを行い、「ラベル」ルールを削除したスキャンを示しています。
チェックメソッドとスキップメソッドは同じオプションを設定するため、チェーン内の2つの呼び出しのうち最後のものだけが効果を発揮します。同じスキャンにそれらを組み合わせないでください。
チェックのみ
チェックのみの方法は、指定されたルールのみをチェックします。明示的に指定されていないルールはスキャンに含まれません。
この連鎖方法は単一のルールを指定するために使用できます。
axeselenium.checkingOnly("tabindex").run(axedriver);スキャンが「tabindex」ルールのみで実行される場合。
複数のルールを指定するには、一度の呼び出しですべてを渡します。2回目の checkingOnly 呼び出しは最初のルールを置き換えます。checkingOnly と accordingTo も同じオプションを設定するので、最後のものだけが効果を発揮します。
axeselenium.checkingOnly("label", "tabindex").run(axedriver);スキャンが「label」および「tabindex」ルールのみで実行される場合。
iframeテストの無効化
不安定なページでは、iframeが問題を引き起こす可能性があります。Axeは各フレームに注入され、同じ方法で設定される必要があります。AxeSelenium::runがページをテストしている間にiframeが追加または削除されると、例外が発生したり予期しない動作が起こる可能性があります。セーフティとして、AxeSeleniumはすべてのiframeの操作を無効にする方法をAxeSelenium::disableIframeTestingで提供しています。有効にすると、axe-coreはページ内のiframeに注入されず、これらのiframeで実行されることもありません。トップレベルのページのみがチェックされます。
このように使用できます。
axeselenium.disableIframeTesting().run(axedriver);この方法の使用は推奨されません。ページが安定するのを待ってからAxeSelenium::runに渡す方が常に良いです。
使用サービス
組織内のAxe DevToolsの使用傾向について洞察を得る
使用サービスは、環境変数やランタイムでのメソッドを通じて設定できます。両方が使用される場合、メソッド内の値が使用されます。注意: すべての使用サービスデータフィールドがメソッドで設定できるわけではありません。
デフォルトでは使用サービスが有効で、結果はhttps://usage.deque.comに送信されます。それを無効にするには、環境変数AXE_TRACK_USAGEをfalseに設定します。使用イベントがDequeに届かない場合は、環境変数AXE_METRICS_URLを明示的に設定してください。
環境変数
これらの環境変数により、使用サービスを構成し、報告されるイベントのプロパティを変更することができます。
| 名前 | タイプ | 上書き可能 | 説明 |
|---|---|---|---|
AXE_DISTINCT_ID |
文字列 | — | ログイン中のユーザーに対して同じままのUUID識別子(再生成されない限り)。Rubyでは、この変数はDEQUE_DISTINCT_IDと名付けられています。 |
AXE_INCLUDE_TEST_RESULTS |
ブール値 | — | 各イベントのtestResultsオブジェクトに完全なaxe-core結果を含めるには、trueに設定します(デフォルトはfalse)。CLIおよびNode.js APIのみでサポートされています。 |
AXE_METRICS_URL |
文字列 | — | REST使用エンドポイントのURL(デフォルトはhttps://usage.deque.com) |
AXE_TRACK_USAGE |
ブール値 | — | 使用サービスの報告を無効にするには、falseに設定します。報告はデフォルトで有効です。 |
AXE_ACTOR |
文字列 | — | テストを実行するのが人か自動化されたパイプラインかを上書きするには、humanまたはautomationに設定します。デフォルトでは、一般的なCI環境変数からautomationが検出されます。CLI、Node.js API、およびRuby APIのみがサポートしています。 |
AXE_APPLICATION |
文字列 | false | アクセシビリティエラーのチェックに使用されたアプリケーション |
AXE_DEV_INSTANCE |
ブール値 | true | このイベントがソフトウェア開発者の行動によるものかを示します。開発またはテスト中に記録されたイベントをマークし、後で削除するのに便利です。 |
AXE_DEPARTMENT |
文字列 | true | 組織内でのユーザーの部署 |
AXE_KEYCLOAK_ID |
文字列 | false | ユーザーのKeycloak ID |
AXE_LOGGED_IN |
ブール値 | false | テスト対象アプリケーションにユーザーがログインしているかどうかを記録します |
AXE_ORGANIZATION |
文字列 | true | ユーザーの組織。Axe Reportsに使用状況を表示するには、これを組織のIDに設定してください(取得するにはDequeに連絡してください)。 |
AXE_SESSION_ID |
文字列 | false | ユーザーのセッションを識別するUUID |
AXE_TEAMS |
文字列 | false | テストを実行するチームを、{ "id": "...", "name": "..." }オブジェクトのJSON配列として、またはそれを含むJSONファイルへのパスとして指定します。CLIの--set-teamsオプション、Node.js APIのsetTeamsメソッド、Ruby APIのfor_teams句またはteams設定プロパティに渡された値が優先されます。CLI、Node.js API、およびRuby APIのみがサポートしています。 |
AXE_USER_ID |
文字列 | false | 特定のユーザーのID。例えば、メールアドレス、名前、またはログインIDなどです。Axe Reportsはこの値を基にユニークユーザーをカウントします。 |
AXE_USER_JOB_ROLE |
文字列 | false | ユーザーの役割 |
AXE_USER_STATUS |
文字列 | false | ユーザーに紐づけたいステータス情報 |
トラッキングを有効にする
この方法により、ユーザーは使用サービスへのデータ送信を選択できるようになります。送信はデフォルトで有効です。
.enableTracking(boolean state)トラッキングURLを設定する
この方法により、使用メトリクスデータが送信される場所を変更できます。デフォルトはhttps://usage.deque.comです。
.setTrackingUrl(String url)ユニークIDを設定する
この方法により、保存/使用される一意のIDを変更できます。
.setDistinctId(String distinctId)次のステップ
Axe DevToolsでテストを作成し始めたら、より詳細でカスタムなテストを書くために結果を使用するを読み、またはアクセシビリティスキャンのレポートを生成するためにレポーターを使用するを読むことができます。
トラブルシューティング
アクセシビリティテストの設定で問題が発生した場合は、Dequeの担当者に直接連絡するか、私たちのサポートデスク、またはメールを送るでご連絡ください。アクセシビリティテストの取り組みをサポートすることを喜んでいます。
