playwright-skill

為什麼要用

核心特性

以角色和無障礙為基礎的定位器模式（避免 CSS/XPath 的脆弱性）
網路攔截與回應模擬慣用模式
跨測試重複使用驗證狀態的測試固件
追蹤擷取與透過追蹤檢視器進行除錯的工作流程
平行執行與分片指引
降低不穩定性：web-first 斷言、重試策略

即時演示

實際使用效果

playwright-skill-2.replay ▶ 就緒

0/0

安裝

作者儲存庫 · Claude Skills 官方文件

使用場景

實戰用法： playwright-skill

如何撰寫可維護的第一個 E2E 測試

👤 首次將 Playwright 加入專案的開發者 ⏱ ~30 min beginner

何時使用： 你有一個測試環境 URL 和登入流程；想在擴展之前先建立一個扎實的測試。

步驟

描述流程

Write a Playwright test for login at staging.example.com: email, password, expect dashboard heading. Use role-based locators only.✓ 已複製

→ 使用 getByRole、getByLabel；沒有 .class 或 xpath
加入驗證重複使用固件

Convert the login into a reusable auth fixture so other tests skip logging in.✓ 已複製

→ 基於 storageState 的固件加上 globalSetup
確保測試穩定

Audit the test for waitFor* anti-patterns; switch to web-first assertions.✓ 已複製

→ 使用 expect(locator).toBeVisible() 而非 waitForSelector

結果： 一個穩健的第一個測試，加上整個測試套件都能繼承的固件。

注意事項

Claude 傾向使用 page.waitForTimeout — 明確告知技能：不使用任意等待，改用 web-first 斷言

攔截後端 API 以測試前端邊界情況

👤 測試空白/錯誤/載入中狀態的前端工程師 ⏱ ~25 min intermediate

何時使用： 你無法輕易將真實後端切換到各種特定狀態時。

步驟

攔截端點

Stub GET /api/orders to return empty array, then assert the empty state renders.✓ 已複製

→ 使用 route.fulfill 搭配 JSON 主體；對空白狀態元素進行斷言
依測試變化回應

Parameterize the stub: one test for 500 error, one for timeout, one for partial data.✓ 已複製

→ 三個測試共用一個輔助函式

結果： 無需觸及後端，即可涵蓋邊界狀態的測試。

注意事項

攔截設定洩漏到其他測試 — 在 beforeEach 或固件作用域中設定，而非模組層級的鉤子

使用追蹤檢視器除錯不穩定的測試

👤 在 CI 中排查不穩定測試套件的工程師 ⏱ ~45 min intermediate

何時使用： 測試在本機通過，但在 CI 中有 5% 的機率失敗。

步驟

在重試時擷取追蹤

Configure trace: 'on-first-retry' in playwright.config.ts.✓ 已複製

→ 設定檔差異
分析追蹤結果

Download the trace.zip from the failed CI run; walk me through what's different from the successful run.✓ 已複製

→ 網路／DOM 時序上的具體差異
修復問題

Based on the trace, propose the minimal change to de-flake.✓ 已複製

→ 具體的定位器或斷言修改，而非直接加 sleep

結果： 一個已修復的穩定測試，並附有文件記錄的根本原因。

注意事項

透過增加逾時時間來處理不穩定問題 — 大多數不穩定問題是隱藏的競態條件——追蹤結果通常會揭露缺少的 await

組合

與其他 MCP 搭配，撬動十倍槓桿

playwright-skill-2 + seo-audit-skill

Playwright 擷取頁面，SEO 稽核針對需要 JavaScript 渲染的應用程式的已渲染 HTML 執行

Use Playwright to authenticate and capture logged-in pages, then run seo-audit against each.✓ 已複製

工具

此 MCP 暴露的能力

工具	輸入參數	何時呼叫
Locator patterns	-	撰寫新的選取器時
Network stubbing	-	測試前端邊界狀態時
Fixtures & auth reuse	-	測試套件規模超過 5 個測試時
Trace analysis	trace.zip	除錯不穩定問題時
Parallelism & sharding	-	測試套件在 CI 中執行超過 5 分鐘時

成本與限制

運行它的成本

API 配額: 無
每次呼叫 Token 數: 測試生成：3-8k tokens
費用: 免費
提示: 手動生成一個測試並儲存為範本，讓 Claude 依照此範本生成其他測試。

安全

權限、密鑰、影響範圍

憑證儲存： 測試憑證存放於 .env（透過 dotenv）。切勿將含有正式環境驗證資訊的 storageState.json 提交至版本控制。

資料出站： 測試會連線至你指定的目標 URL。此技能不會呼叫任何第三方服務。

storageState.json 包含 session cookie。請將其加入 .gitignore，且不要將其作為 CI 產出物公開上傳。

故障排查

常見錯誤與修復

Test is flaky on CI only

啟用 trace: 'on-first-retry' 並分析失敗嘗試的追蹤結果。

驗證： npx playwright show-trace trace.zip

getByRole doesn't find an element that's clearly there

元素可能缺少無障礙名稱。使用 Playwright Inspector 查看計算出的角色與名稱。

驗證： npx playwright test --ui

Login fixture works locally, fails in CI

CI 環境可能需要 --headed=false 以及明確安裝瀏覽器。在 CI 中執行 npx playwright install --with-deps。

替代方案