playwright-best-practices

此技能為在 Claude Code 等基於 CLI 的代理環境中開發和維護 Playwright 端對端測試提供了標準化框架。它專為需要編寫穩健、易維護且具備上下文感知測試套件的軟體工程師和自動化測試專家而設計。該技能強調以用戶為中心的測試模式，確保測試對 UI 結構變化具有彈性，從而減少測試代碼的脆弱性。

• 優先採用具彈性的定位策略，強調使用 getByRole、getByLabel 和 getByTestId 等面向用戶的屬性，而非脆弱的 CSS 選擇器或 XPath 表達式。

• 強制執行基於 web-first 的斷言模式，使用 await expect(locator)，確保測試具備自動等待和重試機制，這對動態 Web 應用程序至關重要。

• 推廣架構最佳實踐，包括測試隔離、通過 storageState 重用認證狀態，以及使用 Fixtures 進行設置和清理任務，取代手動的 beforeEach 鉤子。

• 集成 CLI 特有的優化規則，例如強制使用 line 或 dot 等最小化報告器，防止測試執行期間的輸出淹沒 LLM 上下文窗口。

• 通過鼓勵每項測試獨立創建數據以及穩健的網絡模擬策略，確保測試的確定性。

• 始終優先使用語義化的定位器（如角色、標籤和佔位符），使測試意圖與無障礙標準對齊。

• 避免使用硬編碼的等待（如 page.waitForTimeout），應改用自動等待定位器和 web-first 斷言。

• 配置 playwright.config.ts 以自動檢測 CI 或 CLAUDE 環境變量，並切換至最小化報告模式。

• 使用頁面對象模型 (POM) 組織代碼，將定位器邏輯與測試場景分離，以便在 UI 發生變更時更輕鬆地進行維護。

• 通過避免共享狀態並實現適當的清理過程，確保測試之間的真正隔離，使測試環境保持整潔狀態。