configure-ux-testing

/configure:ux-testing

UX テストインフラストラクチャを確認して設定します。E2E、アクセシビリティ、ビジュアルリグレッションテストの主要ツールとして Playwright を使用します。

このスキルを使用する場面

次の場合にこのスキルを使用します…	次の場合は別の方法を使用します…
プロジェクトに Playwright E2E テストインフラストラクチャをセットアップする	既存の Playwright テストを実行する（bun test:e2e または test-runner エージェントを使用）
プロジェクトに axe-core を使ったアクセシビリティテストを追加する	公開中のサイトで手動のアクセシビリティ監査を実施する
スクリーンショットアサーションを使ったビジュアルリグレッションテストを設定する	特定の失敗した E2E テストをデバッグする（system-debugging エージェントを使用）
Claude のブラウザー自動化用に Playwright CLI または MCP をセットアップする	個別のテストケースを作成する（playwright-testing スキルを使用）
E2E およびアクセシビリティテストを実行する CI/CD ワークフローを作成する	単体テストまたは統合テストを設定する（/configure:tests を使用）

コンテキスト

• パッケージマネージャー：!find . -maxdepth 1 \( -name 'package.json' -o -name 'bun.lock' -o -name 'bun.lockb' \)
• Playwright 設定：!find . -maxdepth 1 -name 'playwright.config.*'
• Playwright のインストール状況：!find . -maxdepth 1 -name 'package.json' -exec grep -l '@playwright/test' {} +
• Axe-core のインストール状況：!find . -maxdepth 1 -name 'package.json' -exec grep -l '@axe-core/playwright' {} +
• E2E テストディレクトリ：!find . -maxdepth 2 -type d \( -name 'e2e' -o -name 'tests' \)
• ビジュアルスナップショット：!find . -maxdepth 4 -type d -name '__snapshots__'
• MCP 設定：!find . -maxdepth 1 -name '.mcp.json'
• CI ワークフロー：!find . -path '*/.github/workflows/*' -maxdepth 3 -name 'e2e*'

UX テストスタック：

• Playwright - クロスブラウザー E2E テスト（主要ツール）
• axe-core - 自動アクセシビリティテスト（WCAG 準拠）
• Playwright screenshots - ビジュアルリグレッションテスト
• Playwright CLI - CLI によるブラウザー自動化（シェルにアクセスできる AI エージェントに推奨）
• Playwright MCP - MCP によるブラウザー自動化（サンドボックス環境での代替手段）

パラメーター

コマンド引数から解析します。

• --check-only：修正案を提示せず、ステータスを報告します
• --fix：確認を求めずにすべての修正を自動適用します
• --a11y：アクセシビリティテストの設定に重点を置きます
• --visual：ビジュアルリグレッションテストの設定に重点を置きます

実行

この UX テスト設定チェックを実行します。

ステップ 1：ツールの最新バージョンを取得する

設定前に最新バージョンを確認します。

1. @playwright/test：playwright.dev または npm を確認します
2. @axe-core/playwright：npm を確認します
3. @playwright/cli：npm を確認します
4. playwright MCP：npm を確認します

WebSearch または WebFetch を使用して最新バージョンを確認します。

ステップ 2：既存の UX テストインフラストラクチャを検出する

検出スクリプトを実行して、Playwright／axe-core のシグナル （package.json の依存関係と設定の glob）、e2e ディレクトリ、__snapshots__、e2e ワークフロー、 および playwright MCP サーバーのエントリーをプロジェクト内で検索します。

bash "${CLAUDE_SKILL_DIR}/scripts/configure-ux-testing.sh" --home-dir "$HOME" --project-dir "$(pwd)"

出力から STATUS= と ISSUES: ブロックを解析します。KEY=VALUE の行には、 PLAYWRIGHT_CONFIG、PLAYWRIGHT_DEP、AXE_CORE_DEP、E2E_DIR、 VISUAL_SNAPSHOTS、E2E_WORKFLOW、PLAYWRIGHT_MCP と、集計値の PLAYWRIGHT_DETECTED／UX_SIGNALS_PRESENT が出力されます。

ステップ 3：準拠レポートを生成する

Playwright のコア、アクセシビリティテスト、ビジュアルリグレッション、MCP 統合のステータスを示す、書式付きの準拠レポートを出力します。

--check-only が指定されている場合は、ここで終了します。

準拠レポートの形式については、REFERENCE.md を参照してください。

ステップ 4：依存関係をインストールする（--fix が指定されている場合、またはユーザーが確認した場合）

# Core Playwright
bun add --dev @playwright/test

# Accessibility testing
bun add --dev @axe-core/playwright

# Install browsers
bunx playwright install

ステップ 5：Playwright の設定を作成する

playwright.config.ts を作成し、以下を設定します。

• デスクトップブラウザのプロジェクト（Chromium、Firefox、WebKit）
• モバイルビューポートのプロジェクト（Pixel 5、iPhone 13）
• 専用の a11y テストプロジェクト（Chromium のみ）
• ローカル開発用の WebServer 自動起動
• 失敗時のトレース／スクリーンショット／動画の設定
• CI 用の JSON および JUnit レポーター

playwright.config.ts の完全なテンプレートについては、REFERENCE.md を参照してください。

ステップ 6：アクセシビリティテスト用ヘルパーを作成する

tests/e2e/helpers/a11y.ts を作成し、以下を用意します。

• expectNoA11yViolations(page, options) - WCAG 違反がないことをアサートします
• getA11yReport(page, options) - 詳細な a11y レポートを生成します
• 設定可能な WCAG レベル（wcag2a、wcag2aa、wcag21aa、wcag22aa）
• ルールの対象指定／除外のサポート
• 書式設定された違反の出力

a11y ヘルパーの完全なコードについては、REFERENCE.md を参照してください。

ステップ 7：テストファイルのサンプルを作成する

テストのサンプルを作成します。

1. tests/e2e/homepage.a11y.spec.ts - ホームページのアクセシビリティテスト（WCAG 2.1 AA の違反、操作後のチェック、完全なレポート）
2. tests/e2e/visual.spec.ts - ビジュアルリグレッションテスト（ページ全体のスクリーンショット、コンポーネントのスクリーンショット、レスポンシブレイアウト、ダークモード）

テストファイルの完全なサンプルについては、REFERENCE.md を参照してください。

ステップ 8：npm スクリプトを追加する

package.json を更新し、テスト用スクリプトを追加します。

{
  "scripts": {
    "test:e2e": "playwright test",
    "test:e2e:headed": "playwright test --headed",
    "test:e2e:debug": "playwright test --debug",
    "test:e2e:ui": "playwright test --ui",
    "test:a11y": "playwright test --project=a11y",
    "test:visual": "playwright test visual.spec.ts",
    "test:visual:update": "playwright test visual.spec.ts --update-snapshots",
    "playwright:codegen": "playwright codegen http://localhost:3000",
    "playwright:report": "playwright show-report"
  }
}

ステップ 9：ブラウザー自動化を設定する（任意）

エージェントの環境に応じて、適切なブラウザー自動化の方法を選択します。

オプション A：Playwright CLI（シェルアクセスが利用できる場合に推奨）

Playwright CLI（@playwright/cli）は、AI エージェントのブラウザー自動化において、MCP よりもトークン効率が 4～10 倍高くなります（タスクあたり約 27K 対約 114K トークン）。スナップショットとスクリーンショットはコンテキストに挿入されず、ディスクに保存されます。

# Global install
npm install -g @playwright/cli@latest

# Or project-local
bun add --dev @playwright/cli

これにより、Claude は CLI コマンドを使って、ページの移動、スクリーンショットの撮影、フォームへの入力、要素のクリック、ページスナップショットの取得を行えます。コマンドのリファレンスについては、playwright-cli スキルを参照してください。

オプション B：Playwright MCP（シェルアクセスのないサンドボックス環境向け）

シェルアクセスのない環境（Claude Desktop、ブラウザーベースのエージェント）で実行する場合は、MCP を使用します。

{
  "mcpServers": {
    "playwright": {
      "command": "bunx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

ステップ 10：CI/CD ワークフローを作成する

.github/workflows/e2e.yml を作成し、以下の並列ジョブを設定します。

• E2E テスト（すべてのブラウザー）
• アクセシビリティテスト（Chromium のみ）
• レポートと失敗時のスクリーンショットのアーティファクトアップロード

CI ワークフローの完全なテンプレートについては、REFERENCE.md を参照してください。

ステップ 11：標準の追跡情報を更新する

.project-standards.yaml を更新します。

components:
  ux_testing: "2025.1"
  ux_testing_framework: "playwright"
  ux_testing_a11y: true
  ux_testing_a11y_level: "wcag21aa"
  ux_testing_visual: true
  ux_testing_cli: true
  ux_testing_mcp: false

ステップ 12：設定結果を報告する

適用した設定、追加したスクリプト、CI/CD のセットアップを要約して出力します。開発サーバーの起動、テストの実行、スナップショットの更新、インタラクティブ UI の起動に関する次の手順も含めてください。

結果レポートの形式については、REFERENCE.md を参照してください。

エージェント向け最適化

コンテキスト	コマンド
コンプライアンスの簡易チェック	/configure:ux-testing --check-only
すべての問題を自動修正	/configure:ux-testing --fix
アクセシビリティのみを対象	/configure:ux-testing --a11y
ビジュアルリグレッションのみを対象	/configure:ux-testing --visual
E2E テストを簡潔に実行	bunx playwright test --reporter=line
a11y テストのみを実行	bunx playwright test --project=a11y --reporter=dot

フラグ

フラグ	説明
--check-only	修正を提案せずにステータスを報告します
--fix	確認を求めずにすべての修正を自動で適用します
--a11y	アクセシビリティテストの設定に重点を置きます
--visual	ビジュアルリグレッションテストの設定に重点を置きます

エラー処理

• パッケージマネージャーが見つからない：依存関係をインストールできないため、手動での手順を提示します
• 開発サーバーが設定されていない：baseURL を手動で設定するよう警告します
• ブラウザーがインストールされていない：bunx playwright install の実行を促します
• 既存の設定が競合する：ユーザーの設定を保持し、マージを提案します

関連項目

• /configure:tests - 単体テストと統合テストの設定
• /configure:all - すべてのコンプライアンスチェックを実行
• スキル：playwright-testing、playwright-cli、accessibility-implementation
• エージェント：UX デザインの実装には ux-implementation
• Playwright のドキュメント：https://playwright.dev
• axe-core のドキュメント：https://www.deque.com/axe