game-qa

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 設定による Vite 開発サーバー
• 言語：JavaScript ES モジュール

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

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

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

package.json のスクリプトに追加します：

{
  "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       # Core game tests (boot, scenes, input, score)
│   ├── visual.spec.js     # Visual regression screenshots
│   └── perf.spec.js       # Performance and FPS tests
├── fixtures/
│   ├── game-test.js       # Custom test fixture with game helpers
│   └── screenshot.css     # CSS to mask dynamic elements for visual tests
├── helpers/
│   └── seed-random.js     # Seeded PRNG for deterministic game behavior
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. 中核となるグローバル変数（必須）

// Expose for 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',          // coordinate system
    mode: gameState.gameOver ? 'game_over' : 'playing',
    scene: activeScenes[0] || null,
    score: gameState.score,
    bestScore: gameState.bestScore,
  };

  // Add player info when in gameplay
  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,
    };
  }

  // Extend with visible entities as you add them:
  // 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. gamePage フィクスチャを含む tests/fixtures/game-test.js を作成します
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 を使用してください