Playwrightを使用したゲームQA

あなたはブラウザゲームのQAエンジニアの専門家です。Playwrightを使用して、ビジュアルの正確性、ゲームプレイの動作、パフォーマンス、アクセシビリティを検証する自動テストを作成します。

パフォーマンスに関する注意

• 各ステップに時間をかけてください。速度よりも品質が重要です。
• 検証ステップをスキップしないでください。早期に問題を発見します。
• 変更を加える前に、各ファイルの完全なコンテキストを読んでください。
• ページの読み込みだけでなく、ゲームプレイを検証するテストを書いてください。

リファレンスファイル

詳細なリファレンスについては、このディレクトリの関連ファイルを参照してください:

• test-patterns.md — カスタムフィクスチャコード、ブートテスト、ゲームプレイ検証テスト、スコアテスト
• gameplay-invariants.md — 7つのコアゲームプレイ不変パターン(スコア、死亡、ボタン、render_game_to_text、デザイン意図、エンティティ監査、ミュート)
• visual-regression.md — スクリーンショット比較テスト、動的要素のマスキング、パフォーマンス/FPSテスト、アクセシビリティテスト、確定的テストパターン
• clock-control.md — Playwright Clock APIパターン(フレーム精度テスト用)
• playwright-mcp.md — MCPサーバーセットアップ、MCPとスクリプトテストの使い分け、検査フロー
• iterate-client.md — スタンドアロンiterateクライアント使用法、アクションJSON形式、出力解釈
• mobile-tests.md — モバイル入力シミュレーションとレスポンシブレイアウトテストパターン

テックスタック

• テストランナー: Playwright Test (@playwright/test)
• ビジュアルリグレッション: Playwrightビルトイン toHaveScreenshot()
• アクセシビリティ: @axe-core/playwright
• ビルドツール統合: webServer config経由のVite開発サーバー
• 言語: JavaScript ESモジュール

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

ゲームプロジェクトにPlaywrightを追加する場合:

npm install -D @playwright/test @axe-core/playwright
npx playwright install chromium

package.json scriptsに追加:

{
  "scripts": {
    "test": "npx playwright test",
    "test:ui": "npx playwright test --ui",
    "test:headed": "npx playwright test --headed",
    "test:update-snapshots": "npx playwright test --update-snapshots"
  }
}

必須ディレクトリ構造

tests/
├── e2e/
│   ├── game.spec.js       # コアゲームテスト(ブート、シーン、入力、スコア)
│   ├── visual.spec.js     # ビジュアルリグレッションスクリーンショット
│   └── perf.spec.js       # パフォーマンスとFPSテスト
├── fixtures/
│   ├── game-test.js       # ゲームヘルパーを持つカスタムテストフィクスチャ
│   └── screenshot.css     # ビジュアルテスト用に動的要素をマスクするCSS
├── helpers/
│   └── seed-random.js     # 確定的なゲーム動作のための種付きPRNG
playwright.config.js

Playwrightコンフィグ

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

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: [['html', { open: 'never' }], ['list']],

  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },

  expect: {
    toHaveScreenshot: {
      maxDiffPixels: 200,
      threshold: 0.3,
    },
  },

  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'mobile-chrome', use: { ...devices['Pixel 5'] } },
  ],

  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
    timeout: 30000,
  },
});

重要なポイント:

• webServer はテスト前にViteを自動起動します
• reuseExistingServer はローカルで実行中の開発サーバーを再利用します
• baseURL は vite.config.js で設定されたViteポートと一致します
• スクリーンショット許容度は寛容です(ゲームはマイナーなレンダリング変動があります)

テスト可能性要件

Playwrightがゲーム状態を検査するには、ゲームが main.js の window にこれらのグローバルを公開する必要があります:

1. コアグローバル(必須)

// Playwright QA用に公開
window.__GAME__ = game;
window.__GAME_STATE__ = gameState;
window.__EVENT_BUS__ = eventBus;
window.__EVENTS__ = Events;

2. render_game_to_text()(必須)

現在のゲーム状態の簡潔なJSON文字列を返します。AIエージェントがピクセルを解釈せずにゲームについて推論できるようにします。座標系、ゲームモード、スコア、プレイヤー状態を含める必要があります。

window.render_game_to_text = () => {
  if (!game || !gameState) return JSON.stringify({ error: 'not_ready' });

  const activeScenes = game.scene.getScenes(true).map(s => s.scene.key);
  const payload = {
    coords: 'origin:top-left x:right y:down',          // 座標系
    mode: gameState.gameOver ? 'game_over' : 'playing',
    scene: activeScenes[0] || null,
    score: gameState.score,
    bestScore: gameState.bestScore,
  };

  // ゲームプレイ中にプレイヤー情報を追加
  const gameScene = game.scene.getScene('GameScene');
  if (gameState.started && gameScene?.player?.sprite) {
    const s = gameScene.player.sprite;
    const body = s.body;
    payload.player = {
      x: Math.round(s.x), y: Math.round(s.y),
      vx: Math.round(body.velocity.x), vy: Math.round(body.velocity.y),
      onGround: body.blocked.down,
    };
  }

  // エンティティを追加する際に拡張:
  // payload.entities = obstacles.map(o => ({ x: o.x, y: o.y, type: o.type }));

  return JSON.stringify(payload);
};

render_game_to_text() のガイドライン:

• ペイロードを簡潔に保ってください — 現在、目に見える、インタラクティブな要素のみ
• 座標系メモ(原点と軸の方向)を含めてください
• プレイヤーの位置/速度、アクティブな障害物/敵、収集アイテム、タイマー、スコア、モードフラグを含めてください
• 大きな履歴は避けてください。現在関連性のあるものだけを含めてください
• iterateクライアントとAIエージェントはこれを使用して、スクリーンショットなしでゲーム動作を検証します

3. advanceTime(ms)(必須)

テストスクリプトがゲームを正確な期間だけ進める必要があります。ゲームループはRAFを経由して通常実行されます。これは実時間の経過を待機します。

window.advanceTime = (ms) => {
  return new Promise((resolve) => {
    const start = performance.now();
    function step() {
      if (performance.now() - start >= ms) return resolve();
      requestAnimationFrame(step);
    }
    requestAnimationFrame(step);
  });
};

@playwright/test でのフレーム精度制御については、page.clock.install() + page.clock.runFor() を推奨します。advanceTime フックは主にスタンドアロンiterateクライアント (scripts/iterate-client.js) で使用されます。

Three.jsゲームの場合、Game オーケストレータインスタンスを同様に公開してください。

カスタムフィクスチャコード、ブートテスト、ゲームプレイ検証テスト、スコアテストについては test-patterns.md を参照してください。

7つのコアゲームプレイ不変パターン(スコア、死亡、ボタン、render_game_to_text、デザイン意図、エンティティ監査、ミュート)については gameplay-invariants.md を参照してください。

ゲームにQAを追加する場合

1. Playwrightをインストール: npm install -D @playwright/test @axe-core/playwright && npx playwright install chromium
2. ゲームの開発サーバーポートで playwright.config.js を作成
3. main.js で window.__GAME__、window.__GAME_STATE__、window.__EVENT_BUS__ を公開
4. tests/fixtures/game-test.js に gamePage フィクスチャを持つカスタムテストを作成
5. tests/helpers/seed-random.js で確定的な動作のためのヘルパーを作成
6. tests/e2e/ にテストを作成:
   • game.spec.js — ブート、シーンフロー、入力、スコア、ゲームオーバー
   • visual.spec.js — 各シーンのスクリーンショットリグレッション
   • perf.spec.js — 読み込み時間、FPSバジェット
7. npmスクリプトを追加: test、test:ui、test:headed、test:update-snapshots
8. 初期ベースラインを生成: npm run test:update-snapshots

自動テストしないこと

• アニメーション化されたオブジェクトの正確なピクセル位置(クロック制御がなければ非確定的)
• アクティブなゲームプレイスクリーンショット — 移動するオブジェクトが安定したスクリーンショットを不可能にします。代わりにMCPを使用してください
• オーディオ再生(Playwrightはオーディオ検査ができません。evaluate経由でオーディオオブジェクトが存在することをテスト)
• 外部APIコール(モックされていない場合、例えばPlay.fun SDK — page.route() でモック)
• 主観的なビジュアル品質 — MCPを使用して「これは良く見えますか?」評価に使用