建立 2026-09-15 更新 2026-09-15

Trace Viewer 追蹤除錯

Trace Viewer 是 Playwright 最強大的除錯工具：把整個測試執行過程（每一步操作、對應的截圖、DOM 快照、網路請求、主控台輸出）完整記錄下來，之後可以離線回放，特別適合排查 CI 環境上才會出現、本機難以重現的失敗。

開啟 Trace 記錄

在 playwright.config.ts 設定何時記錄 Trace：

export default defineConfig({
  use: {
    trace: 'on-first-retry', // 建議：只在第一次重試失敗時記錄
  },
});

trace 選項的常見值：

也可以在指令列臨時開啟，不修改設定檔：

npx playwright test --trace on

檢視 Trace

測試結束後，Trace 檔案（.zip）會存放在 test-results/ 資料夾，可透過 HTML 報表點擊「Trace」連結開啟，或用指令直接開啟：

npx playwright show-trace test-results/.../trace.zip

Trace Viewer 介面包含：

• 操作時間軸：像播放器一樣，可以逐步或拖曳檢視每一個操作發生當下的畫面截圖（Before／After）。
• DOM 快照：不只是截圖，而是真正的 DOM 結構，滑鼠可以在快照上互動、檢查元素。
• Network 分頁：該操作前後發出的所有網路請求與回應內容。
• Console 分頁：瀏覽器主控台的訊息與錯誤堆疊。
• Source 分頁：對應的測試原始碼，並標示目前回放到哪一行。

線上版 Trace Viewer

不需要在本機開啟終端機，也可以把 Trace 檔案直接拖曳到 trace.playwright.dev 網頁版檢視，這對於 CI 產生的 Trace 檔案特別方便，下載下來就能立刻分析，不需要額外安裝。

實務排查流程

1. CI 測試失敗時，先從 HTML 報表下載失敗測試對應的 Trace 檔案。
2. 用 Trace Viewer 找到第一個「非預期」的畫面狀態，通常就是問題發生的那一步。
3. 對照 Network 分頁確認是否為 API 回應延遲、錯誤造成；對照 Console 分頁確認是否有前端錯誤。
4. 確認根本原因後，再回頭調整測試（例如改用更精準的 Locator、明確等待特定 API）或回報實際的產品錯誤。

Trace Viewer 讓「CI 上測試失敗、本機重現不出來」這個常見痛點變得可以離線分析，是團隊導入 Playwright 後排查偶發失敗最重要的工具。

下一步

熟悉除錯工具後，可以進入 進階功能，學習 API 測試、身份驗證狀態、視覺比對與 CI 整合等進階應用。