你用過快照測試嗎？改了畫面，測試紅了；你跑一次更新快照的指令，全部變回綠的。

那一次更新，存進去的標準答案，你打開看過嗎？

快照測試：把報表存成標準答案

usage 是我做的開源小工具，顯示 Claude Code、Codex 等 AI 工具用了多少 token、花了多少錢。它可以產生一份網頁報表。

Claude Code 和 Codex 也是我開發 usage 的幫手：常由 Claude Code 把工作單派給 Codex 去做，做完再由 Claude Code 驗收。

報表有一組快照測試（snapshot test）。做法是：拿一份固定的假資料產生整份報表，把報表的原始碼（HTML）存成一個檔，當作標準答案。之後每次跑測試，都用同一份假資料再產生一次，跟標準答案一字一字比對，有一個字不同就紅。

改了報表的畫面，標準答案當然對不上。這時候要重新產生一次，把新的報表存成新的標準答案。

新圖表加進來，標準答案跟著更新

9 月 5 日傍晚，Claude Code 把一張工作單（交給 AI 的任務說明）派給 Codex：報表加一塊「Token 組成」，用一條長條，把用掉的 token 分成輸入、輸出、快取寫入、快取讀取四段，每段標百分比。

工作單也料到快照會紅，寫明要重新產生快照，不准為了變綠去刪測試或改檢查。

Codex 做完了，快照也更新了，標準答案多了這一塊。Claude Code 驗收後回報全套 1935 個測試通過，改動 commit 了。

標準答案裡，那條長條是空的

這是 Codex 更新快照時，存進標準答案的「Token 組成」：

長條是一條空的灰色，一個百分比都沒有。

原因在那份固定的假資料。新圖表要讀四個新的數字：輸入、輸出、快取寫入、快取讀取各用了多少 token。假資料是這個功能出現之前寫的，沒有這四個數字。程式遇到缺的數字就當成 0，四段加起來是 0，長條一段都畫不出來，百分比也一個都不會印。

重新產生快照的時候，程式畫出什麼，就存什麼。空的長條，就這樣變成了標準答案。

把百分比改錯十倍，1935 個測試照樣全過

事後，我把那一版程式拿出來做了一個實驗：把長條上百分比的算法故意改壞，每一段都變成原本的十分之一。

改完跑全套測試：

1935 passed, 5 skipped, 1 warning in 19.28s

一個都沒紅。假資料的四個數字是 0，長條本來就畫不出來，算法算對算錯，標準答案都是那一條空的。

接著我把算法改回正確的，只多做一件事：替假資料補上那四個數字，圖表的程式一行都不動，重新產生一次標準答案。這次標準答案裡的長條有了四段，也印出了百分比。

再做一次同樣的破壞，這次只跑快照測試，馬上紅了兩個：

FAILED tests/test_html_report_snapshot.py::test_generate_html_matches_golden_snapshot[full_zh_tw-data0-zh-TW]
FAILED tests/test_html_report_snapshot.py::test_generate_html_matches_golden_snapshot[full_en-data1-en]
2 failed, 25 passed in 0.11s

同一份程式、同一個破壞，差別只在假資料有沒有那四個數字。

圖表畫壞了，是人看出來的

那天這張圖的問題，不是測試抓到的。

新版一打開，我傳了一張截圖給 Claude Code：「上面的圖示我看不懂要表示什麼」。它的回覆是：「你看不懂是對的，那張圖確實沒在表達任何東西。」

當天那張截圖沒有留下來。我用那一版程式，配上 Claude Code 當天回報的四個真實用量數字，重畫一次，長這樣：

快取讀取佔了 93.8%，其他三段被擠成細縫，百分比印在色塊裡面，塞不下，疊成一團。

Claude Code 回頭改圖表的時候，才發現快照裡這一塊是空的。它的說法是：

Codex 那版就這樣過關了，我也放行了。

這裡的「我」是 Claude Code。

最後的修正，把長條換成一列一列的排行，也替假資料補上了那四個數字。出問題的那一版沒有單獨發出去，第一個帶著新圖表的版本，已經是修好的。

要注意的是：就算快照有蓋到這一塊，標準答案本來就有的疊字，也不會讓測試變紅。快照只管這次產生的報表跟標準答案一不一樣，不管畫出來好不好讀。這種問題，還是要有人打開報表看一眼。

翻出你專案裡的快照

可以做兩件事。

第一，找到你專案裡的快照檔。常見的名字有 __snapshots__、*.snap、golden、fixtures。

第二，下次更新快照之後，先別急著 commit，看一下這次快照多了什麼：

git diff -- '*.snap' '**/__snapshots__/**' 'tests/fixtures/**'

路徑換成你專案裡放快照的地方。新加的功能，在多出來的那幾行裡看得到它該有的內容嗎？還是只有標題、空的外框、代表沒資料的「—」？

如果只有外框，先查假資料是不是少了新功能要的東西。補上假資料，再把新功能故意改壞一次，確認快照會紅。

今天可以帶走的

工作單（交給 AI 的任務說明）裡有一格「做完怎麼算對」，Day 4、Day 8 到 Day 18 各在這格加了幾行。今天再加一行：

做完怎麼算對：
- （Day 4、Day 8 到 Day 18 加的幾行）
- 有更新快照的改動：回報要貼出快照多出來的那幾行；新功能在快照裡要看得到數字；把新功能故意改壞一次，快照要紅；新畫面用真實資料打開看一次

今天的快照，是檢查有在跑、看到的卻是空的。明天看另一種：檢查有在跑，也看到了，只是它只數一件事。usage 的 README 有五種語言，v0.30.0 的日文版少了新功能 Grok 的整條說明，同步檢查照樣通過。隔天補上的那次改動，說明寫的原因是「CI 沒在檢查這三份」，這句是錯的。

參考資料

• usage 專案：https://github.com/aqua5230/usage
• 9 月 5 日加上 Token 組成的改動：https://github.com/aqua5230/usage/commit/91d9d2a
• 同一天補上假資料、改用排行列的修正：https://github.com/aqua5230/usage/commit/feb84cd