TEST_PLAN — 測試計畫

<!-- SDLC QA — Layer 4：Test Plan Document -->

Document Control

Change Log

1. Overview

1.1 測試目標

本測試計畫涵蓋三公遊戲（Sam Gong 3-Card Poker）線上多人平台的全面品質驗證，確保：

1. 遊戲邏輯正確性：HandEvaluator、SettlementEngine、BankerRotation 等核心模組結果可靠
2. 防沉迷合規性：符合台灣法規對成人（2h 提醒）與未成年（2h 硬停）的要求
3. 安全性：JWT 驗證、Rate Limit、SQL Injection 防護、封號即時踢出等機制有效
4. 效能達標：500 CCU 下 P95 WS 延遲 ≤ 100ms，SLA ≥ 99.5%/月
5. 業務驗收：所有 PRD 驗收標準（Acceptance Criteria）通過 UAT

1.2 覆蓋率要求

CI 命令：

jest --coverage --coverageThreshold='{"global":{"lines":80,"branches":80,"functions":80,"statements":80}}'

1.3 測試環境概覽

2. Test Strategy

2.1 測試層次架構

┌─────────────────────────────────────────────────────┐
│  UAT（User Acceptance Testing）                      │
│  業務驗收、端到端場景、真實使用者操作流程              │
├─────────────────────────────────────────────────────┤
│  Performance Tests（效能測試）                        │
│  k6 WS 負載、壓力、尖峰、耐久測試                     │
├─────────────────────────────────────────────────────┤
│  E2E Tests（端到端測試）                              │
│  多玩家真實房間、完整遊戲週期、滲透測試                │
├─────────────────────────────────────────────────────┤
│  Integration Tests（整合測試）                        │
│  @colyseus/testing Room 測試、REST API 整合、DB 測試  │
├─────────────────────────────────────────────────────┤
│  Unit Tests（單元測試）                               │
│  Jest、純函數、各模組獨立測試                          │
└─────────────────────────────────────────────────────┘

2.2 各層測試策略

2.3 測試資料策略

• Fixtures：tests/fixtures/ TypeScript seed scripts，預置測試帳號與廳別
• Mock：
• Redis：ioredis-mock（單元測試），真實 Redis 容器（整合測試）
• PostgreSQL：pg-mem（單元測試），testcontainers（整合測試）
• OTP SMS：固定 OTP Code（環境變數 TEST_OTP_BYPASS_CODE）
• 清理：每次測試後執行清理 script 還原狀態

3. Unit Test Plan

工具：Jest 29.x + ts-jest + @colyseus/testing

執行命令：npm run test:unit

測試目錄：tests/unit/

3.1 HandEvaluator Tests

模組：server/src/game/HandEvaluator.ts

描述：測試 3 張牌點數計算（mod 10）、三公判定、D8 同點比牌（花色、牌值）邏輯。

測試向量格式：TC-ID | 描述 | 輸入（3 張牌）| 預期輸出 | 優先級

3.1.1 基本點數計算（calculate）

3.1.2 D8 同點比牌（tiebreak）

3.1.3 compare（閒家 vs 莊家）

3.2 SettlementEngine Tests

模組：server/src/game/SettlementEngine.ts

描述：測試三步驟結算邏輯、Rake 計算、莊家破產先到先得、全員棄牌、籌碼守恆。

3.3 BankerRotation Tests

模組：server/src/game/BankerRotation.ts

描述：測試首莊決定、順時針輪莊、跳過不合格莊家、環繞邊界。

3.4 AntiAddictionManager Tests

模組：server/src/game/AntiAddictionManager.ts

描述：測試成人 2h 提醒、未成年 2h 硬停、Write-Through 機制、UTC+8 午夜重置。

3.5 TutorialScriptEngine Tests

模組：server/src/game/TutorialScriptEngine.ts

描述：測試教學固定劇本載入、三局腳本正確性、牌張唯一性。

3.6 DeckManager Tests

模組：server/src/game/DeckManager.ts

3.7 Rate Limit Tests

模組：server/src/middleware/rateLimit.ts

4. Integration Test Plan

工具：Jest + @colyseus/testing + testcontainers

執行命令：npm run test:integration

測試目錄：tests/integration/

前提條件：Docker 運行中（PostgreSQL + Redis 容器自動啟動）

4.1 Room Lifecycle Tests

工具：@colyseus/testing — ColyseusTestServer.create(SamGongRoom)

4.2 Game Flow Tests

描述：完整遊戲流程從 onCreate 到 settled phase 的整合測試。

4.3 WebSocket Message Tests

描述：所有 Client → Server 訊息類型的整合驗證。

4.4 REST API Integration Tests

描述：對 Express REST API 端點的整合測試（真實 DB + Redis）。

5. E2E Test Plan

工具：Jest + Colyseus Client SDK + 真實 Staging 環境

執行命令：npm run test:e2e

測試目錄：tests/e2e/

前提條件：Staging 環境部署完成，Fixtures 資料已載入

5.1 Happy Path：正常遊戲流程

5.2 Edge Cases：邊界情境

5.3 Security Tests：滲透測試場景

6. Performance Test Plan

工具：k6 + @colyseus/loadtest

執行命令：npm run test:perf

測試目錄：tests/performance/

前提條件：Staging 環境 k8s 部署（≥ 2 Colyseus Pod）

6.1 Load Test：500 CCU

目標：驗證 NFR-02（P95 WS 延遲 ≤ 100ms，500 CCU）

// tests/performance/ws-load.js
import ws from 'k6/ws';
import { check } from 'k6';

export let options = {
  vus: 500,          // 500 Virtual Users = 500 CCU
  duration: '10m',   // 持續 10 分鐘
  thresholds: {
    'ws_connecting': ['p(95)<1000'],       // WS 建立 ≤ 1s
    'ws_msgs_received': ['p(95)<100'],     // 收到訊息 P95 ≤ 100ms
    'ws_session_duration': ['p(95)<15000'], // 會話持續
  },
};

6.2 Stress Test：逐步增加至失效點

目標：找出系統極限，驗證 HPA 自動擴展行為

export let options = {
  stages: [
    { duration: '5m', target: 200 },   // 爬升至 200 CCU
    { duration: '5m', target: 500 },   // 爬升至 500 CCU
    { duration: '5m', target: 1000 },  // 爬升至 1,000 CCU
    { duration: '5m', target: 2000 },  // 爬升至 2,000 CCU（目標上限）
    { duration: '5m', target: 0 },     // 冷卻
  ],
};

6.3 Spike Test：瞬間湧入

目標：驗證突發流量下系統穩定性（如遊戲事件、社群擴散）

export let options = {
  stages: [
    { duration: '1m', target: 100 },   // 正常負載
    { duration: '30s', target: 800 },  // 瞬間湧入（8x）
    { duration: '3m', target: 800 },   // 維持高峰
    { duration: '1m', target: 100 },   // 回落
  ],
};

6.4 Endurance Test：長時間穩定性

目標：驗證 SLA 99.5%/月（error budget ≤ 3.65h/月），記憶體洩漏偵測

export let options = {
  vus: 300,            // 300 CCU 穩態
  duration: '4h',      // 4 小時耐久測試
};

6.5 DB Failover Test

目標：驗證 NFR-18（PostgreSQL Failover ≤ 5 分鐘）

7. UAT（User Acceptance Testing）

負責人：QA Lead + Product Owner

執行環境：Staging 環境（接近生產配置）

參考文件：PRD AC（Acceptance Criteria），BRD 業務需求

7.1 遊戲核心功能驗收

7.2 防沉迷功能驗收

7.3 合規功能驗收

7.4 社交功能驗收

7.5 教學功能驗收

8. Test Environment

8.1 docker-compose.test.yml

# tests/docker-compose.test.yml
version: '3.9'

services:
  postgres-test:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: sam_gong_test
      POSTGRES_USER: test_user
      POSTGRES_PASSWORD: test_password
    ports:
      - "5433:5432"  # 避免與 local dev DB 衝突
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U test_user -d sam_gong_test"]
      interval: 5s
      timeout: 5s
      retries: 10

  redis-test:
    image: redis:7-alpine
    ports:
      - "6380:6379"  # 避免與 local Redis 衝突
    command: redis-server --save "" --appendonly no  # 測試環境無需持久化
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 10

  colyseus-test:
    build:
      context: ../server
      dockerfile: Dockerfile.test
    environment:
      NODE_ENV: test
      DATABASE_URL: postgresql://test_user:test_password@postgres-test:5432/sam_gong_test
      REDIS_URL: redis://redis-test:6379
      JWT_PRIVATE_KEY: ${TEST_JWT_PRIVATE_KEY}
      JWT_PUBLIC_KEY: ${TEST_JWT_PUBLIC_KEY}
      TEST_OTP_BYPASS_CODE: "123456"
    depends_on:
      postgres-test:
        condition: service_healthy
      redis-test:
        condition: service_healthy
    ports:
      - "2568:2567"  # Colyseus WS（測試端口）
      - "3002:3000"  # REST API（測試端口）

8.2 測試資料庫管理

Schema 遷移：測試前執行 npm run db:migrate:test（node-pg-migrate + 測試 DB）

資料清理：每個 describe block 的 afterEach 執行 TRUNCATE（保留 Schema，清空資料）

Fixtures 腳本：

// tests/fixtures/seed.ts
export async function seedTestData(db: Pool) {
  // 基本測試帳號
  await db.query(`
    INSERT INTO users (id, display_name, chip_balance, age_verified, is_minor)
    VALUES
      ('test-player-1', '測試玩家1', 50000, true, false),
      ('test-player-2', '測試玩家2', 50000, true, false),
      ('test-minor-1', '未成年玩家', 10000, true, true),
      ('test-banker-1', '測試莊家', 100000, true, false)
    ON CONFLICT (id) DO UPDATE SET chip_balance = EXCLUDED.chip_balance;
  `);
}

export async function cleanupTestData(db: Pool) {
  await db.query(`TRUNCATE chip_transactions, game_sessions, game_rooms,
                           daily_tasks, leaderboard_weekly, player_reports,
                           chat_messages, refresh_tokens RESTART IDENTITY CASCADE`);
}

8.3 環境變數（測試環境）

# .env.test
NODE_ENV=test
DATABASE_URL=postgresql://test_user:test_password@localhost:5433/sam_gong_test
REDIS_URL=redis://localhost:6380
TEST_OTP_BYPASS_CODE=123456
JWT_PRIVATE_KEY=<test RSA private key>
JWT_PUBLIC_KEY=<test RSA public key>
SYSTEM_ACCOUNT_UUID=00000000-0000-0000-0000-000000000001
RESCUE_CHIP_THRESHOLD=500
RESCUE_CHIP_AMOUNT=1000

8.4 Mock 策略詳細配置

9. Test Coverage Requirements

9.1 覆蓋率目標

9.2 CI 門控設定

// jest.config.ts
{
  "coverageThreshold": {
    "global": {
      "lines": 80,
      "branches": 80,
      "functions": 80,
      "statements": 80
    },
    "./server/src/game/HandEvaluator.ts": {
      "lines": 90,
      "branches": 90,
      "functions": 90
    },
    "./server/src/game/SettlementEngine.ts": {
      "lines": 90,
      "branches": 90,
      "functions": 90
    }
  }
}

9.3 CI Pipeline 測試階段

# .github/workflows/ci.yml 測試相關步驟

jobs:
  test:
    runs-on: ubuntu-22.04
    services:
      postgres:
        image: postgres:16
        env: { POSTGRES_DB: sam_gong_test, POSTGRES_USER: test, POSTGRES_PASSWORD: test }
        options: --health-cmd pg_isready
      redis:
        image: redis:7
        options: --health-cmd "redis-cli ping"

    steps:
      - name: Lint（含 Client bundle 關鍵字掃描）
        run: npm run lint

      - name: TypeScript 型別檢查
        run: npm run type-check

      - name: Unit Tests（含覆蓋率）
        run: npm run test:unit -- --coverage

      - name: Integration Tests
        run: npm run test:integration
        env:
          DATABASE_URL: postgresql://test:test@localhost:5432/sam_gong_test
          REDIS_URL: redis://localhost:6379

      - name: 覆蓋率上傳（Codecov）
        uses: codecov/codecov-action@v3

      - name: Semgrep SAST（含 SQL Injection 規則）
        run: semgrep --config rules/sql-injection.yaml --config p/security-audit

      - name: HandEvaluator 向量數驗證（≥ 200）
        run: node scripts/verify-test-vectors.js

9.4 測試覆蓋率排除項目

下列項目不計入覆蓋率要求（排除理由：純配置、型別定義、生成代碼）：

// jest.config.ts coveragePathIgnorePatterns
[
  "node_modules",
  "tests/",
  "src/types/",         // TypeScript 型別定義文件
  "src/config/",        // 純配置檔案
  "src/migrations/",    // DB Migration 腳本
  "src/seeds/",         // 測試資料 Seed
]

10. Test Schedule & Milestones

10.1 測試時程

10.2 測試里程碑 Pass 條件

10.3 測試退出條件（Exit Criteria）

以下任一情況發生，暫停測試並通知開發：

1. P0 優先級測試案例失敗（不允許帶已知 P0 缺陷上線）
2. 覆蓋率低於 80%（阻擋 PR 合併）
3. 效能測試 P95 > 100ms（需效能優化後重測）
4. 籌碼守恆驗證失敗（sum(net_chips) + rake ≠ 0）
5. 安全測試：SQL Injection 或手牌洩漏測試失敗

Appendix A：測試工具版本清單

Appendix B：關鍵測試向量（HandEvaluator 精選）

以下為 200+ 測試向量集的代表性樣本（完整向量集位於 tests/fixtures/hand-evaluator-vectors.json）：

// tests/fixtures/hand-evaluator-vectors.ts
export const HAND_EVALUATOR_VECTORS = [
  // 三公（Sam Gong）— 所有組合（J/Q/K/10 各 4 花色）
  { cards: [{suit:'spade',value:'J'},{suit:'heart',value:'Q'},{suit:'diamond',value:'K'}],
    expected: { points:0, is_sam_gong:true, hand_type:'sam_gong' }},
  { cards: [{suit:'club',value:'10'},{suit:'spade',value:'Q'},{suit:'heart',value:'K'}],
    expected: { points:0, is_sam_gong:true, hand_type:'sam_gong' }},
  // 9點
  { cards: [{suit:'spade',value:'9'},{suit:'heart',value:'K'},{suit:'diamond',value:'J'}],
    expected: { points:9, is_sam_gong:false, hand_type:'9' }},
  { cards: [{suit:'spade',value:'A'},{suit:'heart',value:'8'},{suit:'diamond',value:'K'}],
    expected: { points:9, is_sam_gong:false, hand_type:'9' }},
  // 8點
  { cards: [{suit:'spade',value:'8'},{suit:'heart',value:'K'},{suit:'diamond',value:'J'}],
    expected: { points:8, is_sam_gong:false, hand_type:'8' }},
  // ... 完整 200 個向量見 tests/fixtures/hand-evaluator-vectors.json
];

文件生成：/devsop-autodev STEP-14（2026-04-22）

下次審查：Alpha 測試完成後（2026-06-21）