Playwright でアクセシビリティテストも簡単自動化

2025年9月8日

現代の Web アプリケーション開発において、アクセシビリティは単なる「あると良い機能」ではなく、法的要件としても重要な品質基準となっています。しかし、多くの開発チームが手動でのアクセシビリティチェックに時間を費やし、見落としや品質のばらつきに悩んでいるのが現実です。

Playwright を使用することで、これらの課題を根本的に解決できます。自動化されたアクセシビリティテストにより、開発効率を向上させながら、一貫した高品質なユーザーエクスペリエンスを提供できるのです。

背景

Web アクセシビリティの現状

WCAG 2.1 準拠の必要性

Web Content Accessibility Guidelines（WCAG）2.1 への準拠は、現在多くの国や地域で法的義務となっています。日本においても、JIS X 8341（高齢者・障害者等配慮設計指針）として WCAG ベースの標準が策定されており、公共機関や企業サイトでの対応が求められています。

mermaidflowchart TD
    legal[法的要件] --> wcag[WCAG 2.1準拠]
    business[ビジネス要件] --> wcag
    ethical[倫理的要件] --> wcag
    wcag --> benefit[全てのユーザーに優しいWeb]

    legal --> |"各国の法律<br/>JIS X 8341"| compliance[コンプライアンス対応]
    business --> |"市場拡大<br/>ブランド価値向上"| growth[事業成長]
    ethical --> |"デジタル包摂<br/>社会貢献"| society[社会的価値]

WCAG 2.1 の 4 つの原則（知覚可能、操作可能、理解可能、堅牢性）に基づいた検証を行うことで、視覚障害者、聴覚障害者、運動機能障害者、認知障害者など、様々な障害を持つユーザーが Web サイトを利用できるようになります。

しかし、これらの基準を手動で確認するのは非常に複雑で時間のかかる作業です。例えば、色のコントラスト比の確認だけでも、ページ内の全ての要素について計算し、4.5:1 以上（AA 基準）や 7:1 以上（AAA 基準）を満たしているかをチェックする必要があります。

手動テストの限界と課題

従来のアクセシビリティテストは、主に手動での確認作業に依存していました。スクリーンリーダーを使った音声出力の確認、キーボードナビゲーションの動作確認、色覚異常シミュレータを使った視認性チェックなど、多岐にわたる検証が必要です。

しかし、手動テストには以下のような限界があります：

課題項目	詳細内容	影響度
1	テスト範囲の網羅性不足	高
2	人的リソースの大量消費	高
3	検証結果の属人性・ばらつき	中
4	継続的な品質管理の困難さ	高
5	新機能リリース時の回帰テスト負荷	中

特に大規模な Web アプリケーションでは、全ページ・全機能を手動で確認することは現実的ではありません。また、継続的インテグレーション（CI）環境での自動実行ができないため、開発サイクルのボトルネックになってしまいます。

Playwright の特徴

クロスブラウザ対応

Playwright の最大の特徴の一つは、Chromium、Firefox、Safari（WebKit）の主要ブラウザエンジンすべてに対応していることです。アクセシビリティ機能の実装は、ブラウザごとに微妙な違いがあるため、この包括的な対応は非常に重要です。

mermaidflowchart LR
    playwright[Playwright] --> chromium[Chromium/Chrome]
    playwright --> firefox[Firefox]
    playwright --> webkit[Safari/WebKit]

    chromium --> test1[スクリーンリーダー対応テスト]
    firefox --> test2[キーボードナビゲーションテスト]
    webkit --> test3[色覚アクセシビリティテスト]

    test1 --> report[統合テストレポート]
    test2 --> report
    test3 --> report

例えば、ARIA ラベルの実装やフォーカス管理の動作は、ブラウザエンジンによって異なる場合があります。Playwright を使用することで、同一のテストコードで全ブラウザでの動作を確認し、一貫したアクセシビリティ体験を保証できます。

高速で信頼性の高いテスト実行

Playwright は、モダンな Web アプリケーションのテストに最適化された設計になっています。従来の Selenium ベースのテストと比較して、以下の点で優れています：

実行速度の向上

並列実行による大幅な時間短縮
ネットワーク待機の最適化
効率的なブラウザリソース管理

信頼性の向上

自動待機機能による不安定テストの削減
レースコンディション回避機能
エラー時の自動リトライ機能

これらの特徴により、アクセシビリティテストを開発フローに組み込む際の障壁を大幅に下げることができます。

課題

従来のアクセシビリティテストの問題点

時間のかかる手動チェック

手動でのアクセシビリティチェックは、想像以上に時間のかかる作業です。一つの Web ページを完全にチェックするためには、以下のような多数の項目を確認する必要があります。

mermaidflowchart TB
    manual[手動アクセシビリティチェック] --> structure[構造的チェック]
    manual --> visual[視覚的チェック]
    manual --> interactive[操作性チェック]
    manual --> content[コンテンツチェック]

    structure --> |"2-3時間"| struct_items[見出し構造<br/>ランドマーク<br/>フォームラベル<br/>画像のalt属性]
    visual --> |"1-2時間"| visual_items[色コントラスト<br/>文字サイズ<br/>レスポンシブ対応]
    interactive --> |"2-4時間"| inter_items[キーボードナビゲーション<br/>フォーカス順序<br/>エラーハンドリング]
    content --> |"1-2時間"| content_items[文章の理解しやすさ<br/>多言語対応<br/>音声読み上げ確認]

実際のプロジェクトでは、一つの画面について最低 6〜10 時間程度の検証時間が必要になります。複数ページを持つ Web サイトの場合、膨大な工数が必要となり、プロジェクトスケジュールを圧迫する要因となります。

さらに、新機能追加や既存機能の修正が行われるたびに、影響範囲を特定して再テストを実施する必要があるため、継続的な品質管理が困難になります。

見落としやすいアクセシビリティ問題

人間の目視による確認では、どうしても見落としが発生してしまいます。特に以下のような問題は発見が困難です：

動的コンテンツでの問題

JavaScript で動的に生成される要素の ARIA 属性不備
SPA（Single Page Application）でのフォーカス管理ミス
非同期ロード時のスクリーンリーダー対応不備

複雑な操作フローでの問題

多段階フォームでのエラーメッセージ表示不備
モーダルダイアログでのフォーカストラップ機能不良
ドラッグ＆ドロップ操作の代替手段不提供

これらの問題は、実際にスクリーンリーダーを使用するユーザーや、キーボードのみで操作するユーザーにとって致命的な障害となる可能性があります。

テスト結果の一貫性不足

手動テストでは、テスト実施者のスキルレベルや経験によって、検出できる問題の範囲や品質が大きく変わってしまいます。同じページを異なる担当者がチェックした場合、全く異なる結果が出ることも珍しくありません。

この一貫性の不足は、以下のような問題を引き起こします：

プロジェクト内での品質基準の統一困難
チーム間での知識共有不足
顧客や監査機関への説明責任の問題
改善優先度の判断基準の曖昧さ

解決策

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

axe-core との連携

Playwright の真の力は、世界標準のアクセシビリティ検証ライブラリである「axe-core」との連携にあります。axe-core は、Deque Systems 社が開発したオープンソースのライブラリで、WCAG 2.1 のルールに基づいた包括的なアクセシビリティチェック機能を提供します。

axe-core が検出できる問題の例：

カテゴリ	検出可能な問題	検出項目数
1	色・コントラスト関連	15+
2	キーボード操作関連	12+
3	フォーム・ラベル関連	20+
4	見出し・構造関連	8+
5	画像・メディア関連	10+

axe-playwright パッケージを使用することで、これらの検証をシンプルなコードで実行できます。

以下は、基本的な連携の仕組みを示すコード例です：

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

test('アクセシビリティテスト基本形', async ({ page }) => {
  // テストページへアクセス
  await page.goto('https://example.com');

  // axe-coreによるアクセシビリティスキャンを実行
  const accessibilityScanResults = await new AxeBuilder({
    page,
  }).analyze();

  // 違反がないことを確認
  expect(accessibilityScanResults.violations).toEqual([]);
});

この連携により、WCAG 2.1 の主要ルールを自動的にチェックし、問題があれば詳細な情報と修正提案を取得できます。

自動検証の仕組み

Playwright による自動検証は、以下のようなフローで実行されます：

mermaidsequenceDiagram
    participant Test as テストスクリプト
    participant PW as Playwright
    participant Browser as ブラウザ
    participant Axe as axe-core
    participant Report as レポート

    Test->>PW: テスト実行開始
    PW->>Browser: ページロード
    Browser->>PW: ロード完了通知
    PW->>Axe: アクセシビリティスキャン開始
    Axe->>Browser: DOM解析・ルール適用
    Browser->>Axe: 解析結果返却
    Axe->>PW: 違反情報返却
    PW->>Test: テスト結果
    Test->>Report: レポート生成

この仕組みの特徴は、実際のブラウザ環境でのリアルタイムチェックにあります。静的解析ツールでは検出できない、JavaScript による動的な要素変更やユーザーインタラクションに伴う問題も発見できます。

さらに、Playwright の強力なセレクタ機能と組み合わせることで、特定の要素やページ領域に限定したチェックも可能です：

typescript// 特定のコンポーネントのみをテスト
const accessibilityScanResults = await new AxeBuilder({
  page,
})
  .include('#main-content') // メインコンテンツ領域のみ
  .exclude('.advertisement') // 広告エリアを除外
  .analyze();

CI/CD パイプラインへの組み込み

アクセシビリティテストの真価は、継続的インテグレーション（CI/CD）パイプラインに組み込むことで発揮されます。Playwright は、主要な CI/CD サービスとの連携が簡単に行えます。

GitHub Actions での設定例

プロジェクトルートに .github/workflows/accessibility.yml を作成：

yamlname: アクセシビリティテスト

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  accessibility-test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Node.js セットアップ
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'yarn'

yaml- name: 依存関係インストール
  run: yarn install --frozen-lockfile

- name: Playwright ブラウザインストール
  run: yarn playwright install

- name: アクセシビリティテスト実行
  run: yarn playwright test tests/accessibility/

- name: テスト結果アップロード
  uses: actions/upload-artifact@v3
  if: always()
  with:
    name: accessibility-report
    path: playwright-report/

この設定により、コードがプッシュされるたびに自動的にアクセシビリティテストが実行され、問題があればプルリクエストをブロックできます。

継続的品質監視のメリット

新機能追加時の回帰問題の早期発見
開発チーム全体での品質意識統一
リリース前の最終品質確認の自動化
顧客への品質保証の客観的根拠提供

具体例

環境構築からテスト実装まで

プロジェクトセットアップ

まず、新規プロジェクトで Playwright とアクセシビリティテストの環境を構築する手順を説明します。

必要パッケージのインストール

bash# プロジェクト初期化
yarn init -y

# Playwright と関連パッケージのインストール
yarn add -D @playwright/test
yarn add -D @axe-core/playwright

bash# Playwright の初期設定
yarn playwright install

# 設定ファイル生成
yarn playwright init

プロジェクト構造の作成

bashmkdir -p tests/accessibility
mkdir -p tests/utils
mkdir -p reports

プロジェクトの推奨ディレクトリ構造：

kotlinproject-root/
├── tests/
│   ├── accessibility/
│   │   ├── homepage.spec.ts
│   │   ├── forms.spec.ts
│   │   └── navigation.spec.ts
│   └── utils/
│       ├── accessibility-helper.ts
│       └── test-data.ts
├── playwright.config.ts
└── package.json

基本的なアクセシビリティテストの作成

設定ファイルの調整

playwright.config.ts でアクセシビリティテスト用の設定を行います：

typescriptimport { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  timeout: 30 * 1000,
  expect: {
    timeout: 5000,
  },
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,

typescript  reporter: [
    ['html', { outputFolder: 'playwright-report' }],
    ['json', { outputFile: 'reports/accessibility-results.json' }],
  ],
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },

  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
  ],
});

基本的なテストケースの実装

tests/accessibility/homepage.spec.ts を作成：

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

test.describe('ホームページ アクセシビリティテスト', () => {

  test.beforeEach(async ({ page }) => {
    // 各テスト前にホームページにアクセス
    await page.goto('/');
    // ページの完全ロードを待機
    await page.waitForLoadState('networkidle');
  });

typescripttest('基本的なアクセシビリティチェック', async ({
  page,
}) => {
  // axe-coreによる全体スキャン
  const accessibilityScanResults = await new AxeBuilder({
    page,
  })
    .withTags(['wcag2a', 'wcag2aa', 'wcag21aa'])
    .analyze();

  // 違反がないことを確認
  expect(accessibilityScanResults.violations).toEqual([]);
});

typescripttest('ナビゲーション要素のテスト', async ({ page }) => {
  // ナビゲーション領域に限定したテスト
  const accessibilityScanResults = await new AxeBuilder({
    page,
  })
    .include('[role="navigation"]')
    .include('nav')
    .analyze();

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

typescript  test('メインコンテンツ領域のテスト', async ({ page }) => {
    // メインコンテンツのテスト
    const accessibilityScanResults = await new AxeBuilder({ page })
      .include('main')
      .include('[role="main"]')
      .exclude('.advertisement')
      .analyze();

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

カスタムルールの追加

axe-core のデフォルトルールに加えて、プロジェクト固有の要件に応じたカスタムルールを追加できます。

カスタムルール設定用ヘルパーファイル

tests/utils/accessibility-helper.ts を作成：

typescriptimport { AxeBuilder } from '@axe-core/playwright';
import { Page } from '@playwright/test';

export class AccessibilityHelper {

  static async runComprehensiveCheck(page: Page) {
    return await new AxeBuilder({ page })
      .withTags(['wcag2a', 'wcag2aa', 'wcag21aa', 'best-practice'])
      .withRules(['color-contrast-enhanced']) // AAA基準の色コントラスト
      .exclude('.third-party-widget')
      .analyze();
  }

typescript  static async runFormCheck(page: Page) {
    return await new AxeBuilder({ page })
      .include('form')
      .include('[role="form"]')
      .withTags(['wcag2a', 'wcag2aa'])
      .analyze();
  }

  static async runInteractiveElementCheck(page: Page) {
    return await new AxeBuilder({ page })
      .include('button, a, input, select, textarea')
      .include('[role="button"], [role="link"]')
      .withTags(['wcag2a', 'wcag2aa'])
      .analyze();
  }
}

フォーム要素の詳細テスト

tests/accessibility/forms.spec.ts を作成：

typescriptimport { test, expect } from '@playwright/test';
import { AccessibilityHelper } from '../utils/accessibility-helper';

test.describe('フォーム アクセシビリティテスト', () => {

  test('お問い合わせフォームのテスト', async ({ page }) => {
    await page.goto('/contact');

    // フォーム要素の基本チェック
    const results = await AccessibilityHelper.runFormCheck(page);
    expect(results.violations).toEqual([]);

typescript    // 必須項目の表示確認
    await expect(page.locator('input[required] + [aria-describedby]')).toBeVisible();

    // エラーメッセージの確認
    await page.fill('#email', 'invalid-email');
    await page.click('#submit');

    const errorResults = await AccessibilityHelper.runFormCheck(page);
    expect(errorResults.violations).toEqual([]);
  });

typescript  test('検索フォームのキーボード操作テスト', async ({ page }) => {
    await page.goto('/');

    // キーボードでの操作確認
    await page.press('#search-input', 'Tab');
    await expect(page.locator('#search-button')).toBeFocused();

    // フォーカス状態でのアクセシビリティチェック
    const results = await AccessibilityHelper.runInteractiveElementCheck(page);
    expect(results.violations).toEqual([]);
  });
});

レポート生成とエラー分析

詳細なエラーレポートの生成

テスト失敗時に詳細な分析情報を出力するためのカスタムレポーター関数：

typescript// tests/utils/accessibility-helper.ts に追加

export class AccessibilityHelper {

  static async generateDetailedReport(page: Page, testName: string) {
    const results = await new AxeBuilder({ page }).analyze();

    if (results.violations.length > 0) {
      console.log(`\n=== ${testName} アクセシビリティ違反レポート ===`);

      results.violations.forEach((violation, index) => {
        console.log(`\n${index + 1}. ${violation.help}`);
        console.log(`   重要度: ${violation.impact}`);
        console.log(`   説明: ${violation.description}`);
        console.log(`   修正方法: ${violation.helpUrl}`);

typescript        violation.nodes.forEach((node, nodeIndex) => {
          console.log(`
          要素 ${nodeIndex + 1}:`);
          console.log(`     セレクタ: ${node.target.join(', ')}`);
          console.log(`     HTML: ${node.html}`);

          if (node.failureSummary) {
            console.log(`     エラー詳細: ${node.failureSummary}`);
          }
        });
      });
    }

    return results;
  }
}

テスト結果の可視化

HTML 形式での詳細レポート生成：

typescript// tests/utils/report-generator.ts
import { writeFileSync } from 'fs';

export class ReportGenerator {

  static generateHTMLReport(results: any, testName: string) {
    const timestamp = new Date().toISOString();

    const htmlContent = `
<!DOCTYPE html>
<html lang="ja">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>アクセシビリティテストレポート - ${testName}</title>
    <style>
        body { font-family: Arial, sans-serif; margin: 40px; }
        .violation { border: 1px solid #red; margin: 20px 0; padding: 15px; }
        .impact-critical { border-left: 5px solid #ff0000; }
        .impact-serious { border-left: 5px solid #ff6600; }
        .impact-moderate { border-left: 5px solid #ffcc00; }
        .impact-minor { border-left: 5px solid #00cc00; }
    </style>
</head>
<body>
    <h1>アクセシビリティテストレポート</h1>
    <p>テスト名: ${testName}</p>
    <p>実行日時: ${timestamp}</p>
    <p>違反件数: ${results.violations.length}</p>

typescript    ${results.violations.map((violation: any) => `
        <div class="violation impact-${violation.impact}">
            <h3>${violation.help}</h3>
            <p><strong>重要度:</strong> ${violation.impact}</p>
            <p><strong>説明:</strong> ${violation.description}</p>
            <p><strong>詳細情報:</strong> <a href="${violation.helpUrl}" target="_blank">修正ガイド</a></p>

            <h4>影響を受ける要素:</h4>
            ${violation.nodes.map((node: any) => `
                <div style="margin-left: 20px; border-left: 2px solid #ccc; padding-left: 10px;">
                    <p><strong>セレクタ:</strong> <code>${node.target.join(', ')}</code></p>
                    <p><strong>HTML:</strong> <code>${node.html}</code></p>
                    ${node.failureSummary ? `<p><strong>エラー詳細:</strong> ${node.failureSummary}</p>` : ''}
                </div>
            `).join('')}
        </div>
    `).join('')}

</body>
</html>
    `;

    const filename = `reports/accessibility-${testName}-${Date.now()}.html`;
    writeFileSync(filename, htmlContent);
    console.log(`詳細レポートを生成しました: ${filename}`);
  }
}

継続的改善のためのメトリクス追跡

typescript// tests/utils/metrics-tracker.ts
export class MetricsTracker {
  static trackViolationTrends(results: any) {
    const metrics = {
      timestamp: new Date().toISOString(),
      totalViolations: results.violations.length,
      criticalIssues: results.violations.filter(
        (v: any) => v.impact === 'critical'
      ).length,
      seriousIssues: results.violations.filter(
        (v: any) => v.impact === 'serious'
      ).length,
      moderateIssues: results.violations.filter(
        (v: any) => v.impact === 'moderate'
      ).length,
      minorIssues: results.violations.filter(
        (v: any) => v.impact === 'minor'
      ).length,
      passedRules: results.passes.length,
      testedElements: results.passes.reduce(
        (count: number, pass: any) =>
          count + pass.nodes.length,
        0
      ),
    };

    // JSONファイルに追記してトレンドを追跡
    const fs = require('fs');
    const metricsFile =
      'reports/accessibility-metrics.json';

    let existingMetrics = [];
    if (fs.existsSync(metricsFile)) {
      existingMetrics = JSON.parse(
        fs.readFileSync(metricsFile, 'utf8')
      );
    }

    existingMetrics.push(metrics);
    fs.writeFileSync(
      metricsFile,
      JSON.stringify(existingMetrics, null, 2)
    );

    return metrics;
  }
}