Playwright Pro
專為 AI 編碼代理設計的生產級 Playwright 測試工具包。
可用指令
作為 Claude Code 外掛安裝後，這些指令可透過 /pw: 使用：
| 指令 | 功能說明 |
|---|---|
/pw:init | 設定 Playwright — 偵測框架、產生設定檔、CI、第一個測試 |
/pw:generate <spec> | 從使用者故事、URL 或元件產生測試 |
/pw:review | 審查測試，找出反模式和覆蓋率缺口 |
/pw:fix <test> | 診斷並修復失敗或不穩定的測試 |
/pw:migrate | 從 Cypress 或 Selenium 遷移至 Playwright |
/pw:coverage | 分析已測試與遺漏的部分 |
/pw:testrail | 與 TestRail 同步 — 讀取測試案例、提交結果 |
/pw:browserstack | 在 BrowserStack 上執行，提取跨瀏覽器報告 |
/pw:report | 以偏好的格式產生測試報告 |
快速入門工作流程
多數專案建議的順序：
1. /pw:init → 建立設定檔、CI pipeline 和第一個冒煙測試
2. /pw:generate → 根據你的規格或 URL 產生測試
3. /pw:review → 驗證品質並標記反模式 ← 每次 generate 後務必執行
4. /pw:fix <test> → 診斷並修復任何失敗或不穩定的測試 ← 當 CI 變紅時執行
驗證檢查點：
- 執行
/pw:generate後 — 在提交前務必執行/pw:review；它會自動捕捉定位器反模式和遺漏的斷言。 - 執行
/pw:fix後 — 在本機重新執行完整測試套件（npx playwright test），以確認修復不會引入回歸。 - 執行
/pw:migrate後 — 執行/pw:coverage以確認與舊套件的功能一致性，再淘汰 Cypress/Selenium 測試。
範例：產生 → 審查 → 修復
# 1. 從使用者故事產生測試
/pw:generate "As a user I can log in with email and password"
# 已產生：tests/auth/login.spec.ts
# → Playwright Pro 使用 auth 範本建立該檔案。
# 2. 審查產生的測試
/pw:review tests/auth/login.spec.ts
# → 標記：一個測試使用了 page.locator('input[type=password]') — 建議改用 getByLabel('Password')
# → 自動套用修復。
# 3. 在本機執行以確認
npx playwright test tests/auth/login.spec.ts --headed
# 4. 若測試在 CI 中不穩定，進行診斷
/pw:fix tests/auth/login.spec.ts
# → 識別遺漏的 web-first 斷言；將 waitForTimeout(2000) 取代為 expect(locator).toBeVisible()
黃金規則
- 優先使用
getByRole()而非 CSS/XPath — 對標記變更更具韌性 - 絕不使用
page.waitForTimeout()— 使用 web-first 斷言 expect(locator)會自動重試；expect(await locator.textContent())則不會- 每個測試皆獨立 — 測試之間不共用狀態
- 在設定中使用
baseURL— 杜絕硬編碼 URL - 重試次數：CI 環境設為
2，本機環境設為0 - 追蹤：設定為
'on-first-retry'— 豐富除錯資訊且不影響速度 - 使用 Fixture 而非全域變數 — 透過
test.extend()共用狀態 - 每個測試一個行為 — 多個相關斷言可以接受
- 僅模擬外部服務 — 絕不模擬自己的應用程式
定位器優先順序
1. getByRole() — 按鈕、連結、標題、表單元素
2. getByLabel() — 附有標籤的表單欄位
3. getByText() — 非互動式文字
4. getByPlaceholder() — 附有佔位符的輸入框
5. getByTestId() — 當無語義選項時使用
6. page.locator() — CSS/XPath 作為最後手段
包含內容
- 9 個技能，附有詳細的逐步說明
- 3 個專門代理：測試架構師、測試除錯器、遷移規劃者
- 55 個測試範本：驗證、CRUD、結帳、搜尋、表單、儀表板、設定、入門引導、通知、API、無障礙
- 2 個 MCP 伺服器（TypeScript）：TestRail 和 BrowserStack 整合
- 智慧鉤子：自動驗證測試品質、自動偵測 Playwright 專案
- 6 份參考文件：黃金規則、定位器、斷言、Fixture、常見陷阱、不穩定測試
- 遷移指南：Cypress 和 Selenium 對照表
整合設定
TestRail（選用）
export TESTRAIL_URL="https://your-instance.testrail.io"
export TESTRAIL_USER="[email protected]"
export TESTRAIL_API_KEY="your-api-key"
BrowserStack（選用）
export BROWSERSTACK_USERNAME="your-username"
export BROWSERSTACK_ACCESS_KEY="your-access-key"
快速參考
請參閱 reference/ 目錄：
golden-rules.md— 10 條不容妥協的規則locators.md— 完整的定位器優先順序與速查表assertions.md— Web-first 斷言參考fixtures.md— 自訂 Fixture 與 storageState 模式common-pitfalls.md— 10 大常見錯誤與修正flaky-tests.md— 診斷指令與快速修復
請參閱 templates/README.md 取得完整的範本索引。
使用時機
當你需要 Playwright-pro 的指導或自動化時，請使用此技能。