accessibility-selenium-testing

Selenium WebDriver と Axe Core によるアクセシビリティテスト

このスキルは、axe-core エンジンを使用して Selenium WebDriver フレームワーク内でアクセシビリティを自動分析し、ブラウザー上で WCAG 違反やベストプラクティスに関する問題を検出できるようにします。

有効化： WCAG 準拠の検証、アクセシビリティ違反のスキャン、キーボードナビゲーションのテスト、ARIA セマンティクスの監査、または a11y レポートの生成が必要な場合に、このスキルが起動します。

最初に確認する質問

• 対象となるアプリの URL やユーザーフローは何ですか（また、明確に対象外となるものは何ですか）？
• 既存の Selenium 環境はありますか。また、CI はどのように実行されていますか？
• 対象とする規格は何ですか（デフォルトは WCAG 2.2 AA）。組織固有のポリシーはありますか？
• リスクが最も高いページやコンポーネント（認証、チェックアウト、フォーム、モーダル、ナビゲーション）はどれですか？
• 例外が必要となる既知の制約（レガシーなマークアップ、サードパーティ製ウィジェット）はありますか？

前提条件

コンポーネント	バージョン	用途
Java JDK	21+	最新機能を備えたランタイム
Maven	3.9+	依存関係管理
Selenium WebDriver	4.x	ブラウザーの自動化
axe-core-selenium	4.10+	Deque axe-core との連携
JUnit 5	5.10+	テストフレームワーク
AssertJ	3.x	読みやすい失敗メッセージのための流れるようなアサーション
Allure	2.x	a11y 違反の添付ファイルを含むレポート

注： axe 連携には、Maven 依存関係 com.deque.html.axe-core:selenium を使用してください。

---

対象： WCAG 2.2 AA（wcag2a、wcag2aa、wcag21a、wcag21aa、wcag22a、wcag22aa）。WCAG 2.2 仕様を参照してください。

使用しないケース

• Playwright／TypeScript によるアクセシビリティテスト（a11y-playwright-testing を使用してください）。
• Selenium による機能的な UI テストの作成（webapp-selenium-testing を使用してください）。
• 完全な適合性の最終確認。自動 axe スキャンで検出できる問題は約 30～50％です。手動監査と支援技術によるテストも引き続き必要です。

Axe-Core ツールリファレンス

AxeBuilder の設定

メソッド	用途	例
new AxeBuilder()	スキャナーインスタンスを作成	エントリポイント
.withTags(List<String>)	WCAG タグで絞り込む	wcag2aa、wcag21aa、wcag22aa
.include(String)	特定のセレクターをスキャン	#main-content
.exclude(String)	セレクターをスキャン対象から除外	.third-party-widget
.disableRules(List<String>)	特定のルールを無効化	color-contrast
.withRules(List<String>)	特定のルールのみ実行	label、button-name
.analyze(WebDriver)	スキャンを実行	Results を返します

Results オブジェクト

メソッド	戻り値	用途
getViolations()	List<Rule>	失敗したルール
getPasses()	List<Rule>	合格したルール
getIncomplete()	List<Rule>	手動レビューが必要なルール
getInapplicable()	List<Rule>	ページに適用されないルール
violationFree()	boolean	違反がない場合に True

違反の影響度

影響度	深刻度	CI での対応
Critical	ユーザーの利用を完全に妨げる	常にビルドを失敗させる
Serious	重大な障壁となる	常にビルドを失敗させる
Moderate	多少の困難がある	警告するか、失敗させる
Minor	不便が生じる	レビュー用に記録する

---

ステップごとのワークフロー

ワークフロー 1：既存のテストに A11y スキャンを追加する

1. pom.xml に依存関係を追加する

   <dependency>
       <groupId>com.deque.html.axe-core</groupId>
       <artifactId>selenium</artifactId>
       <version>4.10.0</version>
   </dependency>
   

2. AccessibilityHelper ユーティリティを作成する

   • Axe パターン：ヘルパーによるスキャンを参照してください。

3. ページの読み込み後にスキャンを追加する

   driver.get("https://example.com");
   waitForPageReady();
   AccessibilityHelper.verifyPageAccessibility(driver);
   

4. 実行して違反を確認する

   mvn test -Dtest=A11yTest
   

ワークフロー 2：特定のコンポーネントをテストする

1. コンポーネントが表示されているページに移動する

2. コンポーネントの状態を切り替える（モーダルを開く、ドロップダウンを表示する）

3. コンポーネントのみをスキャンする

   Results results = new AxeBuilder()
       .withTags(List.of("wcag2a", "wcag2aa", "wcag22aa"))
       .include("#login-modal")
       .analyze(driver);
   

4. アサーションを行い、記録する

ワークフロー 3：キーボードナビゲーションの監査

1. すべてのインタラクティブ要素を特定する
2. プログラムからページ内を Tab キーで移動する

   element.sendKeys(Keys.TAB);
   WebElement focused = driver.switchTo().activeElement();
   

3. フォーカスの順序が論理的であることを確認する
4. Escape キーでモーダルが閉じることをテストする
5. キーボードトラップがないことを確認する

ワークフロー 4：CI との統合

1. ヘッドレスブラウザーを設定する

   mvn test -Dheadless=true -Dgroups=a11y
   

2. Critical／Serious の許容件数をゼロに設定する

   long criticalCount = violations.stream()
       .filter(v -> List.of("critical", "serious").contains(v.getImpact()))
       .count();
   assertThat(criticalCount).isZero();
   

3. 追跡用に JSON レポートを生成する

---

コードパターン

AxeBuilder のスキャンパターン、違反のログ記録、JUnit 5 との統合、CI/CD YAML の詳細については、references/code-patterns.md を参照してください。

主要なコード例：

Results results = new AxeBuilder()
    .withTags(List.of("wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22a", "wcag22aa"))
    .analyze(driver);
assertThat(results.violationFree()).as("A11y violations").isTrue();

トラブルシューティング

問題	原因	解決策
Axe の結果が空になる	ページの読み込みが完了していない	ページの準備状態を明示的に待機する
コントラストに関する誤検出	動的なテーマ	ライトモードとダークモードの両方でテストする
サードパーティ製ウィジェットでの違反	ベンダーのコードを変更できない	ドキュメント化されたチケットを添えて .exclude() を使用する
ルールが不完全	手動レビューが必要	手動監査用に記録し、自動的に失敗としない
実行ごとに結果が異なる	非同期のコンテンツ読み込み	スキャン前にページの状態を確定的にする
CI では失敗するが、ローカルでは成功する	ビューポート／ブラウザーが異なる	CI と同じヘッドレス設定を使用する

---

POUR 原則に基づくトリアージ

原則	主な確認項目	よくある違反
知覚可能	テキストによる代替、キャプション、コントラスト、構造	代替テキストがない、コントラストが低い、ラベルがない
操作可能	キーボード操作、フォーカス順序、コンテンツをスキップする手段	キーボードトラップ、スキップリンクがない、フォーカスが見えない
理解可能	ラベル、予測可能な動作、エラー処理	説明が不明瞭、予期しない変更
堅牢	有効な HTML、ARIA、名前／ロール／値	無効な ARIA、重複 ID、ロールがない

---

テストの実行

Maven コマンド

コマンド	目的
mvn test -Dgroups=a11y	すべてのアクセシビリティテストを実行する
mvn test -Dtest=A11yTest	特定のテストクラスを実行する
mvn test -Dheadless=true	ヘッドレスモードで実行する（CI モード）
mvn allure:serve	違反を含む Allure レポートを表示する

CI/CD との統合

- name: Run Accessibility Tests
  run: mvn test -Dgroups=a11y -Dheadless=true

- name: Upload A11y Report
  uses: actions/upload-artifact@v3
  with:
    name: a11y-report
    path: target/a11y-results/

---

注意すべき点

• axe スキャンで違反がないことを、WCAG に完全準拠していることと見なすこと。自動化で確認できるのは基準の約 30〜50％にすぎません。
• ドキュメント化された修正チケットを添えた範囲限定の .exclude() ではなく、ルールをグローバルに無効化すること。
• ページの読み込みが完了する前にスキャンすること。非同期コンテンツによって、「違反 0 件」という誤った結果が生じます。
• incomplete ルールでビルドを失敗させること。これらは自動的に失敗とするのではなく、手動でレビューする必要があります。

---

参考資料

• Axe パターン：ヘルパーによるスキャン - Maven の設定と AccessibilityHelper のスキャンメソッド
• Axe パターン：ヘルパーによる処理 - AccessibilityHelper の結果、フィルタリング、ログ記録、レポート
• Axe パターン：タグとテスト - axe の一般的なタグのリファレンスとテストパターン
• Axe パターン：キーボードと CI/CD - キーボードナビゲーションのテストと CI/CD との統合
• Axe-Core API リファレンス - AxeBuilder の設定、Results オブジェクト、影響度レベルの全項目
• WCAG 2.2 AA チェックリスト：知覚可能・操作可能 - 手動監査チェックリスト、POUR 原則 1〜2
• WCAG 2.2 AA チェックリスト：理解可能・堅牢 - 手動監査チェックリスト、POUR 原則 3〜4 および支援技術
• WCAG 2.2 AA チェックリスト：追加項目と例外 - WCAG 2.2 の追加項目、例外テンプレート、W3C の参考資料
• Deque Axe ルール - ルールの説明
• W3C WCAG 2.2 - 公式仕様
• WAI-ARIA プラクティス - ウィジェットのパターン

---

検証

• Axe WebDriver の監査に合格 — AxeBuilder.analyze(driver) で重大な違反がゼロ件であること
• キーボードアクセシビリティを確認済み — Tab キーによるナビゲーションで、すべてのインタラクティブ要素にアクセスできること
• WCAG 2.2 AA に準拠 — AA レベルのすべてのルールに合格していること（WCAG 2.2 で追加された項目として、フォーカスの非遮蔽、ドラッグ操作、ターゲットサイズの最小要件を含む）