fix

fix skill 概覽

fix skill 的用途

fix skill 是一套專注於偵錯失敗或不穩定 Playwright 測試的工作流程。它能協助 AI agent 從「這個測試壞了」推進到較可能的根本原因：先重現失敗、擷取 trace 證據，再用 flaky-test 分類法判斷問題，而不是只憑 assertion error 猜測。

最適合用在 Playwright 測試偵錯

如果你維護端對端測試，而且經常看到「test failing」、「flaky test」、「passes locally but fails in CI」或「intermittent failure」這類訊息，就適合安裝這個 skill。對於在 CI 中使用 Playwright 的團隊尤其有幫助，因為失敗可能來自 timing、測試隔離、環境差異，或基礎設施壓力。

為什麼比一般提示詞更有用

一般偵錯提示詞常會直接跳到修改程式碼。fix skill 會強制採用更好的順序：先重現；如果失敗消失，就進行 burn-in；接著擷取 traces；最後把症狀對應到分類。它搭配的 flaky-taxonomy.md 提供具體診斷分支與修復模式，涵蓋 missing await、共享狀態、只在 CI 出現的 viewport/font/timezone 差異、瀏覽器崩潰，以及 worker 相關的不穩定性。

安裝前的重要限制

這不是通用型 bug 修復工具。它的範圍限於 Playwright 測試，並假設 agent 能檢查你的測試檔、執行 Playwright commands，並讀取 traces、screenshots、logs 或 CI failure text 等輸出。它沒有 helper scripts，因此價值來自工作流程與分類法，而不是自動化。

如何使用 fix skill

fix 安裝方式與優先檢查的檔案

在相容的 skills environment 中用以下指令安裝：

npx skills add alirezarezvani/claude-skills --skill fix

安裝後，先閱讀 SKILL.md 了解執行工作流程，再開啟 flaky-taxonomy.md 查看 decision tree 與常見修復方式。repository path 是 engineering-team/playwright-pro/skills/fix，有用的 source files 刻意維持很小：沒有隱藏 scripts、rules 或 metadata files 需要設定。

fix skill 需要哪些輸入

若要取得最佳結果，請至少提供下列其中一種輸入：

• 測試檔路徑，例如 e2e/login.spec.ts
• 精確的 test name 或 --grep 字串
• Failure message、stack trace 或 assertion error
• 失敗是發生在本機、CI，還是兩者都有
• 是否單獨執行會通過，但放在完整 suite 裡會失敗
• 若有 trace、screenshot、video 或 CI artifact path，也一併提供
• 相關 Playwright config，特別是 workers、retries、projects、viewport、timezone 與 base URL

較弱的提示：「Fix my flaky checkout test。」

較強的提示：「Use the fix skill for Debugging e2e/checkout.spec.ts, test should submit paid order. It passes locally alone, fails in CI about 30% of runs, and the failure is Timeout 5000ms exceeded waiting for getByRole('button', { name: 'Pay' }). CI uses 4 workers and retries=2. Suggest the reproduction commands, likely category, and minimal code/config changes.」

實務上的 fix 使用流程

從確切失敗的檔案開始：

npx playwright test <file> --reporter=list

如果通過，先把它視為可能是 flaky，並進行 burn-in：

npx playwright test <file> --repeat-each=10 --reporter=list

如果問題只在並行執行時出現，就用 parallelism 測試：

npx playwright test --fully-parallel --workers=4 --repeat-each=5

接著擷取 trace 證據：

npx playwright test <file> --trace=on --retries=0

在修改前，要求 agent 先分類失敗。預期分類包含 timing/async、test isolation、environment 或 infrastructure。這能避免常見的錯誤修法，例如隨意加入 waitForTimeout、提高 global timeouts，或用 retries 把真正的 race condition 蓋掉。

讓結果更好的提示詞模式

使用能把證據與請求分開的提示：

「Use the fix skill. Diagnose before changing code. Test: <file> / <test name>. Reproduction result: <passes/fails command>. CI/local behavior: <details>. Trace or screenshot: <path or summary>. Current suspicion: <optional>. Please categorize using flaky-taxonomy.md, explain the evidence, propose the smallest safe fix, and list the command to verify it.」

這種結構能協助 skill 產出可驗證的偵錯計畫，而不是憑猜測給出 patch。

fix skill 常見問題

fix 只適用於 flaky tests 嗎？

不是。fix skill 同時能處理穩定重現失敗的 Playwright 測試，以及間歇性失敗。對於 deterministic failures，它仍會從重現與 trace capture 開始。對於 intermittent failures，則會加入 burn-in 與 parallel-worker checks，讓 timing、isolation 或 infrastructure 的模式更容易浮現。

什麼情況不該使用這個 skill？

不要把它當作 unit tests、backend integration tests、沒有 Playwright 覆蓋的 production bugs，或大型應用架構偵錯的主要工具。它仍可能提供一般性的想法，但它的 commands、taxonomy 與 examples 都是為 Playwright end-to-end tests 編寫的。

它和單獨使用 Playwright trace viewer 有什麼不同？

Trace viewer 會顯示發生了什麼；fix skill 則協助判斷 trace 代表什麼。例如，元素找不到可能表示 async race、前一個測試洩漏的狀態、CI viewport 差異，或 network dependency。taxonomy 會把 artifacts 轉換成診斷路徑與建議的修復類型。

fix 適合新手嗎？

適合，只要使用者能執行 Playwright commands 並分享錯誤。新手會受益於明確的 command sequence 與 category table。不過，這個 skill 不會取代基本的專案設定知識：Playwright 必須已安裝、test suite 必須能執行，而且 artifacts 必須能存取。

如何改善 fix skill 的使用效果

提供更完整的 fix 失敗證據

最重要的改善是提高輸入品質。請包含已嘗試過的精確 commands 以及結果。「Fails in CI」不如「fails in CI with 4 workers, passes locally with one worker, fails locally with --fully-parallel --workers=4 --repeat-each=5」有用。這一項細節就能把方向指向 isolation 或 parallelism，而不是泛泛的 timing 問題。

避免常見偵錯失敗模式

不要在診斷前就要求 patch。常見的不良結果包括加入固定 sleep、提高 global timeouts、啟用更多 retries，或在尚未確認原因前重寫 selectors。請先要求 skill 說明分類、證據、最小修復方案與驗證 command，再修改程式碼。

在第一個修復後持續迭代

套用建議變更後，重新執行最小但有意義的驗證 command。如果修復目標是 timing，就使用 burn-in。如果目標是 isolation，就比較單一測試與整個 suite 的行為。如果目標是 CI environment，就用更接近 CI 的設定重現，例如 Docker、workers、timezone、viewport 或 mocked network services。

為你的專案擴充 fix 指南

團隊可以在 skill workflow 附近加入專案專屬註記，以改善本機結果：常見 CI settings、已知 flaky services、必要的 test data resets、standard fixtures、mock strategy，以及偏好的 locator conventions。當 fix skill 的 taxonomy 與你 repository 中真實的失敗模式結合時，效果最好。