Test Plan — Ladder Room Online

Version: v1.0

Date: 2026-04-21

Based on: PRD v1.0, EDD v2.0, API v2.1

Author: AI QA Agent（devsop-autodev STEP-14）

§1 Test Strategy Overview

§1.1 測試目標

確保 Ladder Room Online 在上線前達到以下品質閘門：

• P0 User Story Happy Path E2E 全數通過
• 後端單元測試覆蓋率 ≥ 80%（Vitest coverage）
• 前端單元測試覆蓋率 ≥ 70%
• shared 套件覆蓋率 ≥ 90%
• 1,000 次 seed 自動化驗證 100% bijection 通過
• k6 壓測：100 房間 × 50 人 WebSocket 並發成功率 ≥ 99.5%
• Lighthouse CI：FCP < 1.5s，LCP < 2.5s，CLS < 0.1
• 現有 171 個 Vitest 通過測試在遷移後全數維持通過

§1.2 測試層次金字塔

           ┌─────────────────────────────┐
           │        E2E (Playwright)      │ 10%
           │  完整遊戲流程 × 多瀏覽器       │
           ├─────────────────────────────┤
           │   Performance (k6/Autocannon)│ 5%
           │   WS 並發壓測 × Lighthouse   │
           ├─────────────────────────────┤
           │  Integration (Vitest+TC)     │ 20%
           │  REST API × WS × Redis 真機  │
           ├─────────────────────────────┤
           │      Unit (Vitest)           │ 65%
           │  純函式 × 狀態機 × UI 邏輯   │
           └─────────────────────────────┘

§2 Unit Test Plan

§2.1 packages/shared

測試檔案位置： packages/shared/src/tests/

§2.1.1 PRNG 模組（mulberry32, djb2, fisherYates）

§2.1.2 GenerateLadder — seed determinism

§2.1.3 GenerateLadder — rowCount clamping

§2.1.4 GenerateLadder — segment validity

§2.1.5 GenerateLadder — bar density

§2.1.6 ComputeResults — 路徑計算與 bijection

§2.1.7 ValidateGameStart

§2.2 packages/server

測試檔案位置： packages/server/src/tests/

§2.2.1 RoomRepository（mock Redis）

§2.2.2 RoomService — business logic

§2.2.3 GameService — state transitions

§2.2.4 WebSocket handler — message routing

§2.2.5 Security — seed 防洩漏

§2.3 packages/client

測試檔案位置： packages/client/src/tests/

§2.3.1 LocalStorageService

§2.3.2 Canvas renderer（mock canvas 2D context）

§2.3.3 WS client 重連策略

§2.3.4 URL 與 localStorage 預填邏輯

§3 Integration Test Plan

測試框架： Vitest + testcontainers（真實 Redis Docker 容器）

測試檔案位置： packages/server/src/tests/integration/

§3.1 REST API Integration

POST /api/rooms → GET /api/rooms/:code 完整 round-trip

錯誤情境 REST Integration

Redis 原子操作 Integration

§3.2 WebSocket Integration

連線 → JOIN_ROOM → ROOM_UPDATE 流程

START_GAME → GAME_STARTED 流程

REVEAL_ONE → REVEAL_RESULT 流程

斷線/重連 WebSocket Integration

§4 E2E Test Plan（Playwright）

測試框架： Playwright 1.x（Headless Chrome）

測試環境： Local（Docker Compose 或 K8s Rancher Desktop）

測試檔案位置： packages/e2e/tests/（或 packages/server/e2e/）

§4.1 完整遊戲流程（2 個玩家，Happy Path P0）

// 對應所有 P0 User Story 的核心流程
test('complete game flow: 2 players', async ({ browser }) => {
  // Arrange: 開啟兩個獨立 browser context
  const hostCtx = await browser.newContext();
  const playerCtx = await browser.newContext();
  const hostPage = await hostCtx.newPage();
  const playerPage = await playerCtx.newPage();

  // Act + Assert: 依序驗證每個 Step
});

§4.2 一鍵全揭流程（P0）

§4.3 踢除玩家流程（P1）

§4.4 斷線重連流程（P1）

§4.5 50 人房間上限（P0）

§4.6 路徑揭示動畫完成確認

§4.7 自動揭曉模式（P1）

§4.8 多瀏覽器相容性（P1）

• Chrome 110+、Firefox 110+、Safari 15+（Playwright 跨瀏覽器執行）
• 最小 320px 寬度 viewport：無水平 overflow
• iOS Safari 15+ 模擬（Playwright mobile）

§5 Performance Test Plan

§5.1 WS 並發壓測（k6）

工具： k6（WebSocket 支援）

目標環境： Local K8s（Rancher Desktop）或 Staging

測試腳本： k6/ws-load-test.js

// 目標：100 房間 × 50 人 × 完整遊戲流程
export const options = {
  scenarios: {
    ws_game_load: {
      executor: 'ramping-vus',
      startVUs: 0,
      stages: [
        { duration: '1m', target: 5000 },  // 5,000 WS 連線
        { duration: '3m', target: 5000 },  // 穩定壓測
        { duration: '1m', target: 0 },
      ],
    },
  },
  thresholds: {
    'ws_connecting': ['p(95)<1500'],    // WS 握手 P95 < 1.5s
    'ws_msgs_received': ['rate>0.995'], // 訊息接收成功率 > 99.5%
    'http_req_failed': ['rate<0.005'],  // HTTP 失敗率 < 0.5%
  },
};

§5.2 HTTP API 壓測（Autocannon）

工具： Autocannon

目標： POST /api/rooms、POST /api/rooms/:code/players

# 建立房間壓測
autocannon -c 50 -d 30 -m POST -H 'Content-Type:application/json' \
  -b '{"hostNickname":"Host","winnerCount":1}' \
  http://ladder.local/api/rooms

# 目標：P99 < 2s，成功率 > 99.5%

§5.3 前端效能壓測（Lighthouse CI）

工具： Lighthouse CI（@lhci/cli）

觸發時機： 每次 PR（GitHub Actions）

設定檔： lighthouserc.js

module.exports = {
  ci: {
    collect: { url: ['http://ladder.local/'], numberOfRuns: 3 },
    assert: {
      assertions: {
        'first-contentful-paint': ['warn', { maxNumericValue: 1500 }],
        'largest-contentful-paint': ['error', { maxNumericValue: 2500 }],
        'cumulative-layout-shift': ['error', { maxNumericValue: 0.1 }],
        'total-blocking-time': ['warn', { maxNumericValue: 200 }],
      },
    },
  },
};

§5.4 Canvas FPS 壓測

§6 UAT Scenarios

每個 P0 User Story 對應至少 1 個 UAT 情境，由 QA / Product 人工驗證。

UAT 通過標準： 所有 P0 UAT 全數通過，P1 UAT 通過率 ≥ 90%

§7 Test Coverage Targets

§7.1 CI 覆蓋率閘門設定

vitest.config.ts：

export default defineConfig({
  test: {
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html'],
      thresholds: {
        // packages/shared
        lines: 90,
        functions: 90,
        branches: 85,
        statements: 90,
      },
    },
  },
});

GitHub Actions 閘門：

- name: Unit + Integration Test with Coverage
  run: npx vitest --coverage --reporter=json
- name: Assert coverage >= 80% (server)
  run: node scripts/check-coverage.js packages/server 80
- name: Assert coverage >= 90% (shared)
  run: node scripts/check-coverage.js packages/shared 90

§8 Migration Baseline（重要！）

§8.1 現有測試基準

截至 2026-04-21，現有 Vitest 測試：171 個全數通過（來源：EDD §12.4）

參考快照：docs/MIGRATION_CODE_SNAPSHOT.md

遷移後必須維持以下條件：

1. 所有 171 個現有測試繼續通過（不得因重構導致退化）
2. 新增測試不得降低現有覆蓋率
3. 遷移步驟：先跑 npx vitest run 確認基準 171 通過 → 實施變更 → 再跑確認仍 171+ 通過

§8.2 Migration 測試執行順序

# Step 1: 確認遷移前基準
npx vitest run --reporter=json | grep "Tests " # 應顯示 171 passed

# Step 2: 執行遷移（程式碼變更）

# Step 3: 確認遷移後基準維持
npx vitest run --reporter=json | grep "Tests " # 應顯示 ≥ 171 passed，0 failed

# Step 4: 新增測試（本 Test Plan 定義的新 cases）
npx vitest run --coverage

§8.3 不可破壞的現有測試類別（依 MIGRATION_CODE_SNAPSHOT）

• PRNG 模組現有測試（djb2、Mulberry32、Fisher-Yates）
• GenerateLadder 現有快照測試
• ComputeResults 現有 bijection 測試
• RoomRepository mock Redis 現有 CRUD 測試
• 所有已通過的 WS handler 測試

§9 Test Environments

§9.1 Local — Unit & Integration

§9.2 Local — E2E（Playwright + K8s）

§9.3 Local — Performance（k6）

§9.4 CI（GitHub Actions）

TEST_PLAN 版本：v1.0

生成時間：2026-04-21（devsop-autodev STEP-14）

基於 PRD v1.0 + EDD v2.0 + API v2.1