所有文章

測試全綠、遊戲全壞:Dodgeball Game 的完整 Post-Mortem

·29 min read
Game Development
Testing
Specification
Phaser
TypeScript
Post-Mortem

序章:測試驗收的盲區

2026 年 5 月,一個以 Phaser + TypeScript 開發的俯視角躲避球遊戲完成部署。12 個 Phase 線性開發,歷經 11 個月;所有單元測試通過;E2E 自動化測試 100% 覆蓋;兩輪人工 Smoke Test 核准;老闆拿到可部署的遊戲。

老闆打開遊戲,玩了 30 秒。

遊戲立刻停止。列出三個致命問題:

  1. 場上球幾乎全在敵方手中,我方無法有效控制球權
  2. 我的隊友沒有任何行動——螢幕上有三個友方角色,全都站著不動
  3. 看不到任何角色的血量

這些都是核心遊戲機制。這些都應該在 Phase 4(Classes, Skills & HUD)完成時就被發現。

或者至少在 Phase 5(Enemy AI)時被發現。

或者至遲在 Phase 11 發布前被發現。

但它們都沒有被發現。一個分布式的問題,在測試的每一層都通過了,直到一雙人類的眼睛看著遊戲玩起來才暴露。

這篇文章要回答:錯誤最早在哪裡發生?為什麼沒被中途發現?如何避免?


第一段:Spec 撰寫期的隱形決策

所有故事始於一份文件。

spec.md 是以 GDD(Game Design Document)風格撰寫的。它回答了 Game Design 的問題:「這個遊戲有什麼功能?」

  • 角色有血量,血量歸零時死亡
  • 玩家可以撿起球、投向敵人或隊友
  • 未被操控的角色由 AI 自動行動
  • 每個技能都有冷卻時間和效果判定邏輯

但它沒有回答 Product Requirements 的問題:「玩家坐在螢幕前應該看到什麼、感受到什麼?」

GDD 說「血條系統(玩家 & 敵人)」。

PRD 應該說:

玩家在任何時刻都能看到所有存活角色的 HP,以紅色血條呈現,位置在角色頭上方 20px,寬度 50px,血條末端繪製百分比數字(純白色、14pt),受擊後 0.1 秒內更新;血量歸零時血條消失,角色播放死亡動畫。

兩者看起來說的是同一件事。但前者是函數簽名,後者是使用者體驗規格。前者告訴工程師「實現這個功能」,後者告訴工程師「去驗證玩家能看到什麼」。

沒有人在 spec 定稿後問:「這份文件的讀者是誰?」

GDD 被默默當成了 PRD。這個決策沒有被 explicitly 做出,只是默認發生了。

另一個隱形結構化問題:spec.md 的 Key Mechanics Checklist 有 20 個項目。格式上它們看起來像驗收標準:

- [ ] 血條系統(玩家 & 敵人)
- [ ] 球的物理與碰撞判定
- [ ] 角色 AI(敵人)
- [ ] ...

Checkbox 格式自帶「驗收清單」的視覺暗示。但措辭全是功能名稱(feature list),不是驗收條件(acceptance criteria)。

一份有 checkbox 的清單,讀起來就像可以被 tick off 的標準。實際上每一個都是模糊的。這個視覺欺騙在後續的 impl-plan 設計中造成了漣漪。

第三個遺漏:關於我方隊友 AI,整份 spec 只有一句話:

未被操控的角色由 AI 自動行動

藏在「Character Switching」的說明段落裡,沒有進入 Key Mechanics Checklist,沒有任何行為規格定義。沒有人規定 AI 應該在什麼時機移動、什麼時機投球、如何決定目標。

這就像在建築規格裡說「房子應該是安全的」然後假設結構工程師會自動推導出梁的規格。


第二段:impl-plan 的結構化失敗

impl-plan.md 本應修正 spec 的缺陷,但它反而強化了問題。

HTML Overlay 與測試橋接層的邊界模糊

impl-plan 詳細定義了一套「HTML Overlay」系統,作為 Playwright E2E 測試與遊戲邏輯的橋接層:

<div class="overlay-item" data-testid="char-hp-{id}" data-value="75" data-max="100"></div>
<div class="overlay-item" data-testid="skill-cooldown-{id}" data-value="3000"></div>

規範裡列了 15 個 data-attribute 的契約,每一個都清晰定義了:存在條件、值的單位、更新時機。這是優秀的測試規範。

但規範裡沒有說明:這是測試橋接層,不是 HUD 實作。

結果:

  • GameScene.ts 的 createOverlayElements() 方法產生了這些 <div>,但沒有寬度、高度、背景色、邊框
  • GameUIScene.ts 只有一行佔位符文字 this.add.text(640, 20, 'HUD', ...),沒有任何具體的血條、冷卻指示、分數顯示
  • 這些空殼通過了所有 Playwright E2E 測試

為什麼能通過?因為 Playwright 測試只驗證了 data-attribute 是否存在,值是否正確:

await expect(page.locator('[data-testid="char-hp-0"]')).toHaveAttribute('data-value', '75');

這測試了資料——沒有測試呈現。

impl-plan 在列出「HTML Overlay 規範」時,應該加上一行警語:

本規範定義資料層契約,供測試驗證邏輯正確性。HTML Overlay 不等於 HUD 實作。HUD 實作應在 GameUIScene 中將這些資料值轉化為玩家可見的視覺元素(血條、冷卻條、分數面板)。測試通過 ≠ UI 完整。

沒有人寫這一行。Playwright 測試綠了,每個人都認為「HUD 完成」了。

Phase 線性排列的可玩性危機

impl-plan 定義了 12 個 Phase(Phase 0–11),嚴格線性依賴。可玩性所需的核心元素分散在多個 Phase 中:

Phase內容可玩性影響
2Basic Game Loop角色能移動
3Ball System能撿球
4Classes, Skills & HUD應該看到血條
5Enemy AI敵人會移動
6Game Flow有勝負判定

Phase 4 完成後,理論上遊戲應該「第一次可玩」——能移動、能投球、能看到傷害、能看到血條。

但 impl-plan 沒有定義任何一個 Phase 為「最小可玩里程碑」。每個 Phase 的 DoD(Definition of Done)都是獨立的工程指標,沒有一個要求「此時遊戲必須完整可玩」。

結果:Phase 4 完成時,遊戲在工程意義上是「完成」的(所有邏輯通過測試),但在玩家意義上是「殘廢」的(看不到血條)。

沒有任何地方說「這不算完成」。

DoD 設計為工具清單

每個 Phase 的統一 DoD:

  1. npm run typecheck 通過
  2. npm run test:unit 通過,覆蓋率 > 80%
  3. npm run test:e2e 通過
  4. npm run build 通過
  5. 人工 Smoke Test

前四項都是工程工具的輸出。第五項「人工 Smoke Test」沒有對應清單——就一個空的類別。

這就像一個飯店的清潔 checklist:

  • 廁所刷子掃過沒有(機械驗證)
  • 地板吸塵過沒有(機械驗證)
  • 床鋪整理過沒有(機械驗證)
  • 人工檢查(……檢查什麼?)

如果「人工檢查」沒有明確的項目清單,它實際上沒有約束力。檢查人員可以走進房間、看一眼、打個勾,從沒讀任何清單項。


第三段:Phase 4 的失落機會

Phase 4(Classes, Skills & HUD)是遊戲開發中第一次「應該有 UI」的時刻。

交付物列表:

  • CharacterClass.ts ✅
  • Skill.ts 和五個具體技能類別 ✅
  • GameUIScene.ts 骨架 ✅
  • HTML Overlay 的 data-attribute ✅
  • Playwright E2E 測試 60+ 條 ✅

Code Review 通過,所有測試綠燈。PR 被 Merge。

沒有人問:「現在打開遊戲,能看到血條嗎?」

如果有人問,答案會是「不能」。GameUIScene.ts 只有一行佔位符。

但沒有人問。因為 Smoke Test 沒有一條明確說「驗證血條可見」。

為什麼沒人問?

工程師本能上信任自動化測試。Playwright 測試驗證了 data-testid="char-hp-0" 存在,且值正確;邏輯層面 HP 運作正常。從工程角度,「HUD 完成」這個說法沒有邏輯漏洞。

只是漏洞不在邏輯層,在呈現層。

呈現層的驗證不能自動化到「寫一行程式碼就完成」的程度——必須有人實際看著遊戲,用眼睛確認有視覺反饋。這件事不能被 checklist 化、不能被工具化、不能在 CI pipeline 中執行。

所以它被遺漏了。


第四段:Phase 5 的第二個隱形決策

Phase 5(Enemy AI & Level 1 + Bot API)埋下了第二個核心問題。

AISystem 的架構邊界

GameScene.ts 的初始化代碼:

this.aiSystem = new AISystem();
// ...
this.aiSystem.update(delta, this.enemies, this.combatSystem.balls, this.players, this.combatSystem);

this.enemies 進入 AI 邏輯;this.players 只作為「目標資訊」傳入。沒有任何地方對 this.players 執行 AI 決策。

AISystem 的類名和結構,從設計上就只是「敵人 AI」。我方隊友 AI 沒有對應的系統實現。

為什麼?資源排擠

Phase 5 同時引入了「Bot API」——一套 window.__debug.bot 的自動化接口,讓 Playwright E2E 測試可以「玩遊戲」:

await page.evaluate(() => {
  window.__debug.bot.selectCharacter(0);
  window.__debug.bot.moveTowards({ x: 100, y: 100 });
  window.__debug.bot.pickupBall();
  window.__debug.bot.throwBallAt({ x: 200, y: 200 });
});

Bot API 的工程投入——設計 API 介面、實現每一個操作的邏輯、整合進遊戲迴圈——大約佔用了 Phase 5 工期的 60%。

我方隊友 AI 的實作被往後推遲。然後在往後推遲的過程中,逐漸被遺忘。Phase 6–11 沒有任何 Phase 明確要求「實現我方隊友 AI」。它不在 Checklist 裡,不在 DoD 裡。

資源競爭默默發生。沒有人在規劃會議上說「我們決定優先做 Bot API,把隊友 AI 往後推」。它只是發生了。

Bot 勝利 ≠ 遊戲可玩

Phase 5 完成時,Bot 能從頭玩到尾,贏得遊戲。所有 E2E 測試通過,讓人們認為「遊戲工作正常」。

但 Bot 不需要看血條——它直接讀取 data-attribute。Bot 不需要隊友支持——它自己控制了我方的兩個其他角色。Bot 不需要任何視覺反饋——它按照邏輯序列操作。

Bot 贏了遊戲,這在工程上意味著:邏輯層完整。

但這 ≠ 遊戲可玩。


第五段:Phase 6–11 的問題積累

每個後續 Phase 都在既有的缺陷基礎上疊加。

Phase名稱新增功能遺留問題
6Game Flow場景切換、勝負判定玩家仍看不到 HUD;敵人單方面優勢
7Progression升級系統、角色進度進度條看不見;隊友仍不動
8Advanced ContentBoss、Level 2–4AI 失衡加倍;新敵人更容易贏
9UI Polish「UI 優化」實際優化的是 data-testid 準確度,不是可見 UI
10Settings & i18n設定菜單、多語系新增可見菜單,但遊戲本體仍殘廢
11Co-op & Deployment雙人模式、上線整個有缺陷的遊戲被部署上線

每個 Phase 完成時,開發團隊看到的是 ✅ ✅ ✅ 的檢查清單。每一個都綠燈。

這些綠燈有麻痹作用。

當第 6 個、第 7 個、第 8 個 Phase 都通過時,人們開始相信「系統運作」。懷疑開始消退。對既有問題的警惕性開始下降——「如果這個真的有問題,早就會被前面的 Phase 抓出來」。

技術債被測試綠燈覆蓋。測試綠燈讓人不再質疑。

Phase 9 的視覺欺騙

Phase 9 的名稱是「UI Polish」。這聽起來像「我們現在要優化已有的 UI」。

實際上,此時遊戲根本沒有可見的 UI——只有被 data-attribute 標記的空白 div。Phase 9 「優化」的是什麼?

Playwright 測試對 data-attribute 的驗證更加嚴格。HTML Overlay 的更新邏輯被重構,以確保 data 值總是同步。

看起來像 UI 優化,實際上是測試合規性的提升。

沒有人說「我們實際上還沒有可見 UI」。


第六段:為什麼直到試玩才被發現

完全的一致性在於:整個開發週期中,「玩遊戲」從來不是正式的驗收動作。

Vercel 部署通過 ✅ 所有 Pipeline 檢查通過 ✅ Smoke Test 簽名確認 ✅ 一個月的線性開發,每個 Phase 都過了 ✅

直到有人——不是開發者、不是 QA、只是一個沒有背景知識的遊戲玩家——打開遊戲。

這個人用對待一般遊戲的方式對待它:玩。

30 秒內三個問題浮出。


根因分析:10 點

實作與流程層面

1. 測試契約被誤認為 UI 實作

HTML data-attribute overlay 是測試橋接層。它存在的目的是讓 Playwright 有一個穩定的 hook 來讀取遊戲狀態。但在 impl-plan 中,它與「HUD 實作」沒有清晰邊界。

結果:Playwright 能讀到血量值 = HUD 完成 ✅

這個等式在工程邏輯上清晰,但在使用者體驗上是錯誤的。

2. DoD 缺乏玩家視角的驗收標準

五項統一 DoD,全部以工程工具結果為準。沒有任何一項說「玩家應該能看到 X」。

「人工 Smoke Test」唯一提到玩家視角,但沒有對應的檢查清單。它看起來像約束,實際上是開放的。

3. AISystem 設計邊界只涵蓋敵人

我方隊友 AI 從未被任何 Phase 的 DoD 明確要求。它不是執行疏失,是架構設計的邊界設定。AISystem 的名稱和實現,都指向「敵人 AI 系統」。

4. Phase 線性排列,可玩性被推遲到末端

可玩性必要元素(移動、投球、傷害、血量、勝負、視覺反饋、隊友協助)分散在 Phase 2–6。沒有任何一個 Phase 的 DoD 要求「此時遊戲必須完整可玩」。

可玩性變成了一個涌現特性(emergent property),而不是一個明確的需求。涌現特性沒有被設計,沒有被驗收。

5. Event Bus 的訂閱端沒有測試覆蓋

許多遊戲機制通過 Event 實現。例如 Taunt 技能發射 SKILL_ACTIVATED 事件,應該有音效訂閱、動畫訂閱、HUD 訂閱。

發射端有單元測試覆蓋。訂閱端沒有。

如果沒有訂閱者,事件進入虛空,無聲失敗。測試不會告訴你「沒人監聽」。

6. Bot API 投入排擠了隊友 AI 的實作資源

資源有限。Phase 5 選擇投入 Bot API 而不是隊友 AI,這是一個策略決定。但決定沒有被明確討論,沒有被紀錄。

兩個系統的優先序只是默默地被 Phase 時程排成了顯著的差異。


Spec 層面

7. GDD 被直接當作 PRD,缺少需求轉譯步驟

「遊戲有血條」(GDD 層面的事實)需要轉譯為「玩家看到紅色血條,位置在角色頭上,實時更新」(PRD 層面的可驗證需求)。

這個轉譯步驟沒有發生。工程師收到 GDD,直接開始實作。缺少的那一步,正好是「視覺呈現需求」和「AI 行為規格」落空的地方。

8. Spec 對「呈現層」與「邏輯層」未做區分

Key Mechanics Checklist 全是功能描述。沒有一項明確指向呈現層。

「血條系統」VS.「血條系統 + 玩家可見的血條視覺呈現」——兩句話說的同一件事,但後者把前者清楚地劈成了兩層。

Spec 沒有做這個劈分。實作就沒有明確的目標。

9. Key Mechanics Checklist 的格式造成誤導

Checkbox 列表看起來像驗收清單。但措辭是模糊的(feature list),不是明確的(acceptance criteria)。

讀 spec 的人看到 20 個 checkbox,本能上認為它們代表了 20 個驗收標準。實際上,每一個都需要被細化。

這個細化沒有發生。checkbox 被直接當成了實作指導。

10. AI 行為規格的缺失是 Spec 層面的範疇遺漏

「未被操控的角色由 AI 自動行動」——整份 spec 只有這一句關於我方隊友 AI。而且藏在 Switching 的說明段落裡。

沒有:什麼時機移動、什麼時機投球、如何選擇目標、冷卻時間、優先序。

這不是工程疏失,是規格的本體缺陷。工程師沒有源頭需求,所以什麼都實作不了。


完整根因鏈

GDD 未轉譯為 PRD(根因 7)
  ↓
呈現層需求 & AI 行為規格缺席(根因 8、10)
  ↓
impl-plan 的 DoD 設計者無明確依據定義玩家視角的驗收標準(根因 2、3、9)
  ↓
測試只覆蓋邏輯層,呈現層與 AI 行為沒有測試鉤點(根因 1、5)
  ↓
視覺呈現與隊友 AI 被系統性地遺漏(根因 4、6)
  ↓
所有自動化檢查通過,直到人類玩家看一眼

預防機制

第一優先(高影響、低成本)

1.1 Spec 完成後強制進行「工程讀寫對齊」

PM + 架構師,對照一遍 spec。具體流程:

  • PM 說一個功能:「角色有血條系統」
  • 架構師回問:「玩家看到什麼?在哪裡?什麼條件更新?」
  • PM 說出詳細需求,或意識到自己沒有想清楚
  • 結果記錄在「需求理解差異表」

上限 2 小時,通常 1 小時足夠。成本極低,影響極高。

1.2 Spec 加入固定區塊:呈現層需求清單 & AI 行為規格清單

呈現層需求清單:

## 呈現層需求
 
- HP Bar:所有存活角色頭上 20px,紅色,寬 50px,實時反映血量百分比;數字顯示右側
- Skill Cooldown:HUD 左下角,四個技能圖標排列,灰色遮罩表示冷卻中,覆蓋百分比
- ...

AI 行為規格清單:

## 我方隊友 AI 行為規格
 
- 移動目標:靠近距離自己最近的球,或如果無球,靠近距離隊友最遠的敵人
- 投球目標:視線範圍內距離最近的敵人,如無敵人則不投
- ...

強制這兩個區塊存在,將「呈現」和「行為」從模糊的 GDD 明確化。

1.3 Key Mechanics Checklist 改格式

從:

- [ ] 血條系統(玩家 & 敵人)

改為:

- [ ] 血條系統|驗收:場上每名存活角色頭頂可見紅色血條,受擊後 0.1s 內實時更新;歸零時消失

驗收條件要么說「玩家能看到 X」,要么說「邏輯驗證 X」。Checklist 從 feature list 變成 acceptance criteria。


第二優先(高影響、需紀律)

2.1 impl-plan 強制設立「最小可玩性里程碑 Phase」

一個明確的 Phase(例如 Phase 4a),DoD 包括:

  1. 角色能移動
  2. 能撿起球
  3. 能投向敵人
  4. 敵人受擊並失血
  5. 玩家能看到敵人血量變化
  6. 勝負判定(最後一人存活)

六件事同時成立。人工試玩 5 分鐘,確認遊戲能完整玩一局。

這會讓「可玩性」從涌現特性變成顯式需求。

2.2 每個 Phase 的 DoD 加入「玩家感知驗收清單」

3–5 條清單,格式統一:「以玩家身份、不開 DevTools,能否觀察到 X?」

例如 Phase 4 的 DoD 加上:

- [ ] 人工試玩 3 分鐘:確認能看到敵人血量即時變化
- [ ] 人工試玩 3 分鐘:確認能看到技能冷卻倒數
- [ ] 人工試玩:確認被击中時有清晰的視覺或音效反饋

這些項目無法自動化,必須有人執行。但明確列出,就不能被遺漏。

2.3 HTML Overlay 規範明確標注層級

impl-plan 的 HTML Overlay 章節加入警語:

## HTML Overlay 規範
 
⚠️ **本規範定義資料層契約,供測試驗證遊戲邏輯。**
**HTML Overlay 元素本身不可見;這些資料需在 GameUIScene 中轉化為玩家可見的視覺元素。**
 
測試通過 data-attribute ✅ ≠ UI 實作完成 ❌
 
[具體 data-attribute 規格...]

這一行能防止「HTML Overlay = HUD」的誤解。


第三優先(可漸進建立)

3.1 Event Bus 規範:emit 必須配套訂閱測試

每個事件定義時,強制說明預期訂閱者及其行為:

/**
 * 技能發動事件
 * @event SKILL_ACTIVATED
 * @param skillId - 技能 ID
 * 
 * 訂閱者:
 * - CombatSystem:處理傷害計算
 * - AudioSystem:播放技能音效
 * - AnimationSystem:播放技能動畫
 * - HUDSystem:更新冷卻顯示
 */
this.events.emit('SKILL_ACTIVATED', skillId);

每個訂閱者都對應一條測試,測試命題為「given 事件 X 被發射,then 目標系統狀態應為 Y」。

3.2 Phase 規劃時資源分配顯性化

開發計劃會議上,功能實作與測試輔助工具(如 Bot API)的資源競爭要被顯性討論:

Phase 5:Enemy AI & Level 1 + Bot API
 
時程分配:
- 敵人 AI 實現:40% (2.4 days)
- Level 1 設計與資源:20% (1.2 days)
- Bot API:40% (2.4 days)
 
決策:優先完成 Bot API,因為它能加速後續 Phase 的 E2E 測試編寫。
隊友 AI 推遲至 Phase 6–7。
 
後續追蹤:確保隊友 AI 被排入相應 Phase 的 DoD。

資源競爭不會消失,但至少能被明確討論、記錄、追蹤。


長期方向

將 GDD 和 PRD 分成兩份文件

  • GDD.md:遊戲有什麼功能
  • PRD.md:玩家體驗是什麼、如何驗收

中間有一次正式的「需求細化會議」作為轉換節點。

引入定期 Playtest

每完成一個重要 Phase(例如 4、6、8),邀請非開發成員(PM、設計、朋友)花 30 分鐘實際操作遊戲。不要求他們給出結構性反饋,只要求記錄「第一印象問題」。

第一印象是最誠實的使用者體驗信號。


核心教訓

測試驗收的對象決定了什麼問題會被發現。

驗收標準的隱性讀者是 CI 系統。

CI 系統看不到的東西就不會被驗收。

具體來說:

  • 資料正確 ≠ 資訊可見 — 資料層可以通過所有邏輯測試,但呈現層可以保持空白
  • 資訊可見 ≠ 體驗成立 — 血條存在,但位置、尺寸、更新頻率可能讓玩家無法快速反應
  • Bot 能完成遊戲 ≠ 人類玩家能享受 — 自動化腳本不需要視覺反饋、不需要隊友協助、不需要任何人類直覺
  • 「所有測試通過」和「遊戲好玩」是完全不同的命題 — 一個在工程空間中(邏輯層),一個在使用者空間中(感知層)

Dodgeball Game 的故事就是這個邊界的一個完美案例。工程上滿分,使用者上不及格。

在兩個空間都要通過,需要有意識地在需求層面做出區分,在驗收標準中都有對應。


後記

這不是一篇譴責故事。每一個失誤點都是合理的局部決策:

  • GDD 本身沒有問題,問題是拿它當了 PRD
  • HTML Overlay 規範很有用,問題是沒說清楚它的邊界
  • Bot API 的投入是值得的,問題是排擠隊友 AI 的決策沒被明確化
  • Phase 線性開發很常見,問題是沒有一個里程碑強制「遊戲必須可玩」

局部合理,全局失敗。這是複雜系統常見的失敗模式。

預防機制也都不複雜——幾個會議、幾個文件區塊、一個 Playtest 環節。都在成本承受範圍內。

但實施需要一個關鍵的轉變:把驗收的地點從 CI pipeline 移到人類的眼睛和手指。

讓 CI 保留它最擅長的事:邏輯驗證。

留出明確的空間給:呈現層驗證、體驗驗證、直觀感受。

兩層都要綠燈,遊戲才算完成。