axe-core

axe-core - クイックリファレンス

このスキルを使用しない場合

• 手動での WCAG 準拠監査 - ガイドラインの理解や手動テストには wcag スキルを使用してください
• スクリーンリーダーのテスト - axe-core は手動でのスクリーンリーダー検証に代わるものではありません
• 複雑な ARIA パターンの実装 - ARIA の作成方法については wcag スキルを使用してください
• アクセシビリティ戦略の策定 - このスキルはテストの自動化を目的としており、アクセシビリティのコンサルティングには使用しません

詳細情報：ルール、設定、統合に関する包括的なドキュメントを参照するには、technology に axe-core を指定して mcp__documentation__fetch_docs を使用してください。

基本設定

npm install -D @axe-core/react  # For React
npm install -D axe-core         # Core library

基本パターン

React DevTools との統合

import React from 'react';
import ReactDOM from 'react-dom/client';

if (process.env.NODE_ENV !== 'production') {
  import('@axe-core/react').then(axe => {
    axe.default(React, ReactDOM, 1000);
  });
}

Jest/Vitest との統合

import { axe, toHaveNoViolations } from 'jest-axe';

expect.extend(toHaveNoViolations);

test('should have no accessibility violations', async () => {
  const { container } = render(<MyComponent />);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});

Playwright との統合

import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test('should not have accessibility issues', async ({ page }) => {
  await page.goto('/');

  const accessibilityScanResults = await new AxeBuilder({ page }).analyze();

  expect(accessibilityScanResults.violations).toEqual([]);
});

// With specific rules
test('should pass WCAG AA', async ({ page }) => {
  await page.goto('/');

  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa'])
    .analyze();

  expect(results.violations).toEqual([]);
});

Cypress との統合

// cypress/support/commands.ts
import 'cypress-axe';

// In test
describe('Accessibility', () => {
  it('has no violations', () => {
    cy.visit('/');
    cy.injectAxe();
    cy.checkA11y();
  });
});

プログラムからの使用

import axe from 'axe-core';

async function checkAccessibility() {
  const results = await axe.run();

  if (results.violations.length > 0) {
    console.log('Violations:', results.violations);
  }
}

アンチパターン

アンチパターン	問題点	適切な方法
空の状態や読み込み中の状態で axe を実行する	不完全な DOM をテストするため、偽陰性が発生します	axe の実行前にコンテンツの読み込みを待ちます
すべての違反を無視する	自動テストの目的が失われます	違反を修正するか、理由を添えて例外を記録します
ホームページのみをテストする	アクセシビリティの問題は、複雑なインタラクションで多く発生します	重要なユーザーフローとコンポーネントをすべてテストします
WCAG レベルを設定しない	すべてのルールが対象になり、厳しすぎる場合があります	対象レベルに応じて withTags(['wcag2a', 'wcag2aa']) を設定します
ループ内で axe を同期的に実行する	テストの実行が遅くなります	Promise.all() を使って並列実行します
違反を CI にコミットする	リグレッションを検出できなくなります	新たな違反があればビルドを失敗させます
非表示または非アクティブなコンポーネントをテストする	axe が不要な非表示要素をテストします	非表示のセクションには exclude パラメーターを使用します
レガシーコードにベースラインがない	すべての違反が進捗を妨げます	ベースラインを作成し、改善状況を段階的に追跡します

よくある問題の解決方法

問題	原因	解決方法
axe で違反が見つからないのに、ページにアクセシビリティの問題がある	自動ツールで検出できる問題は約 30～40％に限られます	手動でのキーボード操作とスクリーンリーダーのテストを併用します
「違反なし」と表示されるが、フォームに問題がある	axe はフォームのロジックやフローをテストしません	フォームの送信やエラー処理を手動でテストします
Playwright の axe テストでタイムアウトする	大規模または複雑なページでは処理に時間がかかります	タイムアウトを延長するか、特定の領域を解析します
カスタムコンポーネントで誤検知が発生する	axe のルールがパターンを認識できません	disableRules を使用するか、適切な ARIA を追加して修正します
サードパーティーのウィジェットで違反が発生する	外部コードを変更できません	例外を記録し、提供元に問い合わせるか、ウィジェットを置き換えます
ブラウザーによって結果が異なる	ブラウザーごとにレンダリングが異なります	複数のブラウザーで axe を実行し、クロスブラウザーテストスイートを使用します
CI では失敗するが、ローカルでは成功する	環境の違い（タイミング、コンテンツ）が原因です	テストデータと待機条件を統一します
一度に修正できないほど違反が多い	レガシーコードベースに広範な問題があります	ベースラインを作成し、改善状況の追跡には --save フラグを使用します