playwright-testing

Playwright によるアクセシビリティテスト

Playwright と @axe-core/playwright を使用した、ブラウザー上でのアクセシビリティテスト向け再利用可能なナレッジモジュールです。

利用可能な MCP ツール

ツール	目的	@axe-core/playwright が必要
run_playwright_keyboard_scan	Tab 順序の巡回、キーボードトラップの検出	いいえ
run_playwright_state_scan	クリックトリガー、axe-core による表示コンテンツのスキャン	はい
run_playwright_viewport_scan	複数ビューポートでの axe-core スキャン＋タッチターゲットの測定	はい
run_playwright_contrast_scan	CSS カスケード適用後の計算済みスタイルによるコントラスト比	いいえ
run_playwright_a11y_tree	ブラウザーのアクセシビリティツリーのスナップショット	いいえ

@axe-core/playwright のパターン

ページ全体のスキャン

import AxeBuilder from '@axe-core/playwright';

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

要素を指定したスキャン

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

単一ルールの検証

const results = await new AxeBuilder({ page })
  .include('#hero-image')
  .withRules(['image-alt'])
  .analyze();
expect(results.violations).toEqual([]);

インタラクション後のスキャン

await page.click('[aria-expanded="false"]');
await page.waitForSelector('.accordion-content', { state: 'visible' });
const results = await new AxeBuilder({ page })
  .include('.accordion-content')
  .analyze();

キーボード巡回のパターン

Tab の順序を記録する

const tabStops = [];
for (let i = 0; i < maxTabs; i++) {
  await page.keyboard.press('Tab');
  const info = await page.evaluate(() => {
    const el = document.activeElement;
    return {
      tagName: el?.tagName,
      role: el?.getAttribute('role'),
      name: el?.getAttribute('aria-label') || el?.textContent?.trim().slice(0, 50),
      id: el?.id,
      tabIndex: el?.tabIndex
    };
  });
  tabStops.push(info);
}

キーボードトラップを検出する

連続して Tab キーを押した後、同じ要素にフォーカスが戻る場合、キーボードトラップが検出されます。

let trapCount = 0;
let lastSelector = '';
for (const stop of tabStops) {
  const currentSelector = `${stop.tagName}#${stop.id}`;
  if (currentSelector === lastSelector) {
    trapCount++;
    if (trapCount >= 3) { /* TRAP DETECTED */ }
  } else {
    trapCount = 0;
  }
  lastSelector = currentSelector;
}

モーダルを開いた後のフォーカス管理

await page.click('[data-modal-trigger]');
await page.waitForSelector('[role="dialog"]', { state: 'visible' });
const focusedRole = await page.evaluate(() =>
  document.activeElement?.closest('[role="dialog"]') ? 'inside-dialog' : 'outside-dialog'
);
// focusedRole should be 'inside-dialog'

フォーカス管理テストのテンプレート

モーダルのフォーカストラップテスト

test('modal traps focus correctly', async ({ page }) => {
  await page.goto(url);
  await page.click('[data-open-modal]');
  await page.waitForSelector('[role="dialog"]', { state: 'visible' });

  // Focus should be inside the dialog
  const inDialog = await page.evaluate(() =>
    document.activeElement?.closest('[role="dialog"]') !== null
  );
  expect(inDialog).toBe(true);

  // Tab through dialog — should not escape
  for (let i = 0; i < 20; i++) {
    await page.keyboard.press('Tab');
    const stillInDialog = await page.evaluate(() =>
      document.activeElement?.closest('[role="dialog"]') !== null
    );
    expect(stillInDialog).toBe(true);
  }

  // Escape should close and return focus to trigger
  await page.keyboard.press('Escape');
  const focusedId = await page.evaluate(() => document.activeElement?.id);
  expect(focusedId).toBe('modal-trigger-id');
});

スキップリンクのテスト

test('skip link moves focus to main content', async ({ page }) => {
  await page.goto(url);
  await page.keyboard.press('Tab'); // Focus skip link
  await page.keyboard.press('Enter'); // Activate it
  const focusedId = await page.evaluate(() => document.activeElement?.id);
  expect(focusedId).toBe('main-content');
});

CI との統合

Playwright を使用した GitHub Actions

name: Accessibility Tests
on: [push, pull_request]

jobs:
  a11y:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - name: Start dev server
        run: npm run dev &
        env:
          CI: true
      - name: Wait for server
        run: npx wait-on http://localhost:3000 --timeout 30000
      - name: Run accessibility tests
        run: npx playwright test tests/a11y/
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: a11y-test-results
          path: test-results/

アクセシビリティテスト用 Playwright 設定

// playwright.config.js (a11y section)
export default {
  testDir: './tests/a11y',
  use: {
    baseURL: process.env.BASE_URL || 'http://localhost:3000',
    // Use Chromium only — @axe-core/playwright is Chromium-validated
    browserName: 'chromium',
  },
  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
  },
};

段階的な機能低下

検出パターン

let _playwrightAvailable = null;
async function isPlaywrightAvailable() {
  if (_playwrightAvailable !== null) return _playwrightAvailable;
  try {
    await import('playwright');
    _playwrightAvailable = true;
  } catch {
    _playwrightAvailable = false;
  }
  return _playwrightAvailable;
}

機能低下マトリックス

Playwright	@axe-core/playwright	利用可能なスキャン
はい	はい	5 つのツールすべて（キーボード、状態、ビューポート、コントラスト、ツリー）
はい	いいえ	3 つのツール（キーボード、コントラスト、ツリー）
いいえ	—	なし — コードレビュー＋axe-core CLI に切り替えます

ユーザー向けメッセージ

利用できない場合：

Playwright not installed. Behavioral testing (keyboard traversal, dynamic states,
responsive viewport, rendered contrast) is unavailable.

Install: npm install -D playwright @axe-core/playwright && npx playwright install chromium

一部の機能のみ利用できる場合：

@axe-core/playwright not installed. State scanning and viewport scanning are
unavailable. Keyboard, contrast, and accessibility tree scans will proceed.

Install: npm install -D @axe-core/playwright

WCAG 対応表

WCAG SC	説明	Playwright ツール
1.3.1	情報と関係性	a11y ツリー、状態スキャン
1.4.3	コントラスト（最低限）	コントラストスキャン
1.4.6	コントラスト（高度）	コントラストスキャン
1.4.10	リフロー	ビューポートスキャン
2.1.1	キーボード	キーボードスキャン
2.1.2	キーボードトラップなし	キーボードスキャン
2.4.3	フォーカス順序	キーボードスキャン
2.4.7	フォーカスの可視化	キーボードスキャン
2.5.5	ターゲットサイズ（高度）	ビューポートスキャン
2.5.8	ターゲットサイズ（最低限）	ビューポートスキャン
4.1.2	名前、役割、値	a11y ツリー、状態スキャン