手動測試發現 bug,你會截圖、記步驟、附 log,因為你知道沒有證據的缺陷報告等於沒報。自動化測試失敗時一樣需要證據。

Playwright 的 Trace 功能,相當於幫每次失敗自動做好一份完整的重現報告,而且精確到毫秒。

Trace 是什麼

Trace 是測試執行過程的完整側錄。測試失敗時,打開它可以看到四類證據:

圖 1:一份 trace 包含的四類證據
• 時間軸:每一步動作何時發生、花了多久。
• 每步截圖:失敗前每個瞬間畫面長什麼樣。
• 網路請求:背後的 API 被呼叫了什麼、回了什麼,有沒有 500 錯誤。
• Console 訊息:網頁前端有沒有噴錯。

換句話說,你手動重現 bug 時想蒐集的那些東西,它全部自動收好了。

四類證據各自什麼時候救你
• 時間軸:某一步花了 28 秒才過,雖然沒失敗,但你發現了效能異常的前兆。
• 截圖:測試說找不到按鈕,截圖一看,畫面被一個從沒見過的公告彈窗蓋住了。三秒破案。
• 網路請求:畫面只顯示「發生錯誤」,網路面板裡那條回 500 的請求,直接指出是哪支 API 掛了。
• Console:畫面看起來只是沒反應,console 裡的 JavaScript 錯誤說明了前端根本炸了。

什麼時候才會錄到 trace

這一節先講清楚,可以少踩一個很常見的坑:報告打開了,卻找不到 trace。原因通常是那次執行根本沒錄。
錄製時機由設定檔的 trace 選項決定,常見有這幾種值:

// playwright.config.js
use: { trace: 'on-first-retry' },
// 'off'                 完全不錄
// 'on'                  每次都錄(檔案大,適合除錯)
// 'retain-on-failure'   全部都錄,只留下失敗的那些
// 'on-first-retry'      第一次失敗不錄,重試時才錄(專案初始化的預設值)

on-first-retry 兼顧效能,平常很夠用。但它有個副作用:本機執行預設不重試,所以第一次失敗就結束了,那次執行不會留下 trace。

所以本節先記住一件事:想要保證錄到 trace,執行時加上 --trace on。後面的實作會用到這個參數,到時候不用回頭改設定檔。

不確定自己專案目前是哪個設定,可以請 Claude Code 讀設定檔解釋給你聽。

怎麼打開 trace report

你可能已經注意到:本機跑測試,有失敗時報告常常會「自己跳出來」。控制它的是 html 報告的 open 選項,三種值:

// playwright.config.js
reporter: [['html', { open: 'on-failure' }]],
// 'on-failure'  有測試失敗才自動打開(Playwright 預設)
// 'always'      每次跑完都自動打開
// 'never'       從不自動打開,要看就自己下指令

預設是 on-failure,所以綠燈時安安靜靜、紅燈時報告自己跳出來提醒你——這個預設對日常很合理,通常不用動。報告沒自動開、或想回頭看上一次的,自己下:

npx playwright show-report

報告打開後,點進失敗的測試是「詳情頁」:列著 Errors、Test Steps、Attachments。

圖 3: trace report 內容

打開 Trace Viewer 的三條路

路一,從報告點進去:就是上面那三個動作——開報告、進詳情頁、點 Traces 區塊的縮圖。日常最順的一條,九成時間走這裡。

圖 4: 從trace report 去看 trace

路二,用指令直接開檔案。trace 錄下來其實是一個 zip 檔,放在專案的 test-results 資料夾裡、以該測試命名的子資料夾下。指令直接開它:

npx playwright show-trace test-results/<測試資料夾>/trace.zip

路徑懶得找就別找,一句話的事:「幫我打開剛才失敗那個測試的 trace」,Claude Code 會自己定位檔案執行。這條路適合報告已經關掉、或想直接指定某一份 trace 的時候。

路三,網頁版:打開 trace.playwright.dev,把 trace.zip 拖進去就能看,完整功能,而且對方電腦什麼都不用裝。這條路的主要用途是給別人看——附在缺陷單裡的 trace,開發者就是用它打開的。

圖 5: 從網頁版去看 trace

看 trace 是要來分析問題的

圖 6:從打開 trace 到做出判斷

分析的終點是一個判斷:這是產品的 bug,還是測試的 bug?

情況一 產品問題: 截圖顯示錯誤頁,網路面板有一條回 500 的請求。這是產品問題。拿著 trace 去報缺陷,證據齊全到開發者說不出「無法重現」。

情況二測試問題: 畫面一切正常,只是元素的文字改了,測試還在找舊文字。這是測試的問題,回頭修測試。

這個判斷是測試人員的核心價值,AI 可以協助,但不該代替你拍板。實務上的好用法,是先自己看過 trace,再把觀察丟給 Claude Code 一起研判

實作:親手用 trace 破案

步驟 1:請 Claude Code 寫一個會失敗的測試
先製造一個會失敗的測試,在 TodoMVC 上就能做,而且這個失敗很有代表性。請 Claude Code 寫:
你可以這樣對 Claude Code 說:
在 TodoMVC 寫一個測試:新增兩筆待辦,然後點「Clear completed」按鈕清除已完成項目,驗證清單仍有 2 筆。

步驟 2:帶著錄 trace 執行
跑之前先做一件事:這次要「帶著錄 trace」執行,不然預設設定下第一次失敗不會錄,你會在報告裡找不到 trace。指令加一個參數:

npx playwright test --trace on

步驟 3:打開報告,進到詳情頁
這次執行必紅:點 Clear completed 那步逾時,報告會自動跳出來(第三節的 on-failure)。點進失敗的測試,詳情頁上先看到兩個線索:
● Errors:錯誤訊息與 call log 摘要。
● Test Steps:每步清單,紅色那步等了將近 30 秒。
這些已經是線索,但還不是完整現場。

步驟 4:進 Trace Viewer
在詳情頁往下捲,找到 Traces 區塊,點裡面的縮圖。畫面大致長這樣:

圖 7:本案的 Trace Viewer 畫面(示意),四個區塊各司其職

步驟 5:對照編號辦案
• ① 時間軸先看顏色: 出事的就是那步會是紅色,點它。
• ② 動作清單裡,紅色那步 click 'Clear completed' 耗時 30.0s(你的執行狀況可能不是這樣)。前面每步都 0.1 秒,它獨自等了三十秒才放棄——等好等滿的意思。
• ③ 當下截圖是破案關鍵:兩筆待辦好好地躺在清單上,但看清單底部——根本沒有 Clear completed 這顆按鈕。
• ④ Call Log : 解釋 Playwright 在這三十秒裡反覆做了什麼。

證據齊了,破案:Clear completed 這顆按鈕,只有在「至少有一筆已完成項目」時才會出現。我們的流程新增了兩筆,但忘了先勾任何一筆完成,按鈕自然不存在。這不是產品 bug,是測試流程漏了一步——修法是在點按鈕前補上「勾第一筆完成」。

回頭看,破案的關鍵證據就是那張截圖:不用讀任何程式,看畫面就知道按鈕不在,再想一步就知道為什麼不在。這是 trace 對不寫程式的人特別友善的地方——證據是視覺的,而「從畫面推理」正是你做了很多年的事。

之後在 CI 上,trace 是唯一的現場

本機失敗,你還能重跑一次盯著看。但是如果放上 CI(或是雲端自動執行)之後,失敗發生在你看不到的機器上,常常也無法重現,尤其是十次掛一次的那種。到時候,trace 就是唯一的犯罪現場。現在養成看 trace 的習慣,到時候會很慶幸。

今天的練習
• 把 TodoMVC 的測試故意弄壞(第 3 篇的老招),跑完打開 show-report,找到 trace,逛五分鐘。
• 在時間軸上找出失敗的那一步,看看當時的截圖和網路面板。
• 把你的觀察整理成兩三句話,丟給 Claude Code 請它一起判讀,練習「先看再問」的節奏。