playwright-best-practices

Playwright 最佳實務

此技能提供 Playwright 測試開發的全面指引，從撰寫新測試到除錯與維護現有測試套件。

依活動分類的參考指南

根據您正在進行的活動查閱以下參考資料：

撰寫新測試

使用時機：建立新測試檔案、撰寫測試案例、實作測試情境

活動	參考檔案
撰寫 E2E 測試	test-suite-structure.md, locators.md, assertions-waiting.md
撰寫元件測試	component-testing.md, test-suite-structure.md
撰寫 API 測試	api-testing.md, test-suite-structure.md
撰寫 GraphQL 測試	graphql-testing.md, api-testing.md
撰寫視覺回歸測試	visual-regression.md, canvas-webgl.md
使用 POM 結構化測試程式碼	page-object-model.md, test-suite-structure.md
設定測試資料/固定裝置	fixtures-hooks.md, test-data.md
處理驗證	authentication.md, authentication-flows.md
測試日期/時間功能	clock-mocking.md
測試檔案上傳/下載	file-operations.md, file-upload-download.md
測試表單/驗證	forms-validation.md
測試拖放	drag-drop.md
測試無障礙性	accessibility.md
測試安全性（XSS、CSRF）	security-testing.md
使用測試註解	annotations.md
使用測試標籤	test-tags.md
測試 iframe	iframes.md
測試 canvas/WebGL	canvas-webgl.md
國際化（i18n）	i18n.md
測試 Electron 應用程式	electron.md
測試瀏覽器擴充功能	browser-extensions.md

行動裝置與響應式測試

使用時機：測試行動裝置、觸控互動、響應式版面

活動	參考檔案
裝置模擬	mobile-testing.md
觸控手勢（滑動、點擊）	mobile-testing.md
視埠/斷點測試	mobile-testing.md
行動裝置專用 UI	mobile-testing.md, locators.md

即時與瀏覽器 API

使用時機：測試 WebSocket、地理位置、權限、多分頁流程

活動	參考檔案
WebSocket/即時測試	websockets.md
地理位置模擬	browser-apis.md
權限處理	browser-apis.md
剪貼簿測試	browser-apis.md
相機/麥克風模擬	browser-apis.md
多分頁/彈出視窗流程	multi-context.md
OAuth 彈出視窗處理	third-party.md, multi-context.md

除錯與疑難排解

使用時機：測試失敗、找不到元素、逾時、非預期行為

活動	參考檔案
除錯測試失敗	debugging.md, assertions-waiting.md
修復不穩定測試	flaky-tests.md, debugging.md, assertions-waiting.md
除錯不穩定的並行執行	flaky-tests.md, performance.md, fixtures-hooks.md
確保測試隔離 / 避免狀態洩漏	flaky-tests.md, fixtures-hooks.md, performance.md
修正選擇器問題	locators.md, debugging.md
調查逾時問題	assertions-waiting.md, debugging.md
使用追蹤檢視器	debugging.md
除錯競爭條件	flaky-tests.md, debugging.md, assertions-waiting.md
除錯主控台/JS 錯誤	console-errors.md, debugging.md

錯誤與邊界案例測試

使用時機：測試錯誤狀態、離線模式、網路失敗、驗證

活動	參考檔案
錯誤邊界測試	error-testing.md
網路失敗模擬	error-testing.md, network-advanced.md
離線模式測試	error-testing.md, service-workers.md
Service Worker 測試	service-workers.md
載入狀態測試	error-testing.md
表單驗證測試	error-testing.md

多人與協作測試

使用時機：測試涉及多位使用者、角色或即時協作的功能

活動	參考檔案
單一測試中的多位使用者	multi-user.md
即時協作	multi-user.md, websockets.md
角色權限測試	multi-user.md
並行動作測試	multi-user.md

架構決策

使用時機：選擇測試模式、決定方法、規劃測試架構

活動	參考檔案
POM 與固定裝置決策	pom-vs-fixtures.md
測試類型選擇	test-architecture.md
模擬與真實服務	when-to-mock.md
測試套件結構	test-suite-structure.md

框架特定測試

使用時機：測試 React、Angular、Vue 或 Next.js 應用程式

活動	參考檔案
測試 React 應用程式	react.md
測試 Angular 應用程式	angular.md
測試 Vue/Nuxt 應用程式	vue.md
測試 Next.js 應用程式	nextjs.md

重構與維護

使用時機：改善現有測試、程式碼審查、減少重複

活動	參考檔案
重構為 Page Object Model	page-object-model.md, test-suite-structure.md
改善測試組織	test-suite-structure.md, page-object-model.md
提取共用設定/拆卸	fixtures-hooks.md
取代脆弱的選擇器	locators.md
移除明確等待	assertions-waiting.md
建立測試資料工廠	test-data.md
設定配置	configuration.md

基礎設施與配置

使用時機：設定專案、配置 CI/CD、最佳化效能

活動	參考檔案
配置 Playwright 專案	configuration.md, projects-dependencies.md
設定 CI/CD 管線	ci-cd.md, github-actions.md
GitHub Actions 設定	github-actions.md
GitLab CI 設定	gitlab.md
其他 CI 提供者	other-providers.md
Docker/容器設定	docker.md
全域設定與拆卸	global-setup.md
專案相依性	projects-dependencies.md
最佳化測試效能	performance.md, test-suite-structure.md
配置並行執行	parallel-sharding.md, performance.md
在工作執行緒之間隔離測試資料	fixtures-hooks.md, performance.md
測試涵蓋率	test-coverage.md
測試報告/成品	reporting.md

進階模式

使用時機：複雜情境、API 模擬、網路攔截

活動	參考檔案
模擬 API 回應	test-suite-structure.md, network-advanced.md
網路攔截	network-advanced.md, assertions-waiting.md
GraphQL 模擬	network-advanced.md
HAR 錄製/重播	network-advanced.md
自訂固定裝置	fixtures-hooks.md
進階等待策略	assertions-waiting.md
OAuth/SSO 模擬	third-party.md, multi-context.md
付款閘道模擬	third-party.md
電子郵件/SMS 驗證模擬	third-party.md
主控台錯誤時失敗	console-errors.md
安全性測試（XSS、CSRF）	security-testing.md
效能預算與 Web Vitals	performance-testing.md
Lighthouse 整合	performance-testing.md
測試註解（skip、fixme）	annotations.md
測試標籤（@smoke、@fast）	test-tags.md
用於報告的測試步驟	annotations.md

快速決策樹

您正在做什麼？
│
├─ 撰寫新測試？
│  ├─ E2E 測試 → core/test-suite-structure.md, core/locators.md, core/assertions-waiting.md
│  ├─ 元件測試 → testing-patterns/component-testing.md
│  ├─ API 測試 → testing-patterns/api-testing.md, core/test-suite-structure.md
│  ├─ GraphQL 測試 → testing-patterns/graphql-testing.md
│  ├─ 視覺回歸 → testing-patterns/visual-regression.md
│  ├─ 視覺/canvas 測試 → testing-patterns/canvas-webgl.md, core/test-suite-structure.md
│  ├─ 無障礙測試 → testing-patterns/accessibility.md
│  ├─ 行動裝置/響應式測試 → advanced/mobile-testing.md
│  ├─ i18n/語系測試 → testing-patterns/i18n.md
│  ├─ Electron 應用程式測試 → testing-patterns/electron.md
│  ├─ 瀏覽器擴充功能測試 → testing-patterns/browser-extensions.md
│  ├─ 多人測試 → advanced/multi-user.md
│  ├─ 表單驗證測試 → testing-patterns/forms-validation.md
│  └─ 拖放測試 → testing-patterns/drag-drop.md
│
├─ 測試特定功能？
│  ├─ 檔案上傳/下載 → testing-patterns/file-operations.md, testing-patterns/file-upload-download.md
│  ├─ 日期/時間相依 → advanced/clock-mocking.md
│  ├─ WebSocket/即時 → browser-apis/websockets.md
│  ├─ 地理位置/權限 → browser-apis/browser-apis.md
│  ├─ OAuth/SSO 模擬 → advanced/third-party.md, advanced/multi-context.md
│  ├─ 付款/電子郵件/SMS → advanced/third-party.md
│  ├─ iFrame → browser-apis/iframes.md
│  ├─ Canvas/WebGL/圖表 → testing-patterns/canvas-webgl.md
│  ├─ Service Worker/PWA → browser-apis/service-workers.md
│  ├─ i18n/本地化 → testing-patterns/i18n.md
│  ├─ 安全性（XSS、CSRF） → testing-patterns/security-testing.md
│  └─ 效能/Web Vitals → testing-patterns/performance-testing.md
│
├─ 架構決策？
│  ├─ POM 與固定裝置 → architecture/pom-vs-fixtures.md
│  ├─ 測試類型選擇 → architecture/test-architecture.md
│  ├─ 模擬與真實服務 → architecture/when-to-mock.md
│  └─ 測試套件結構 → core/test-suite-structure.md
│
├─ 框架特定測試？
│  ├─ React 應用程式 → frameworks/react.md
│  ├─ Angular 應用程式 → frameworks/angular.md
│  ├─ Vue/Nuxt 應用程式 → frameworks/vue.md
│  └─ Next.js 應用程式 → frameworks/nextjs.md
│
├─ 驗證測試？
│  ├─ 基本驗證模式 → advanced/authentication.md
│  └─ 複雜流程（MFA、重設） → advanced/authentication-flows.md
│
├─ 測試失敗/不穩定？
│  ├─ 不穩定測試調查 → debugging/flaky-tests.md
│  ├─ 找不到元素 → core/locators.md, debugging/debugging.md
│  ├─ 逾時問題 → core/assertions-waiting.md, debugging/debugging.md
│  ├─ 競爭條件 → debugging/flaky-tests.md, debugging/debugging.md
│  ├─ 僅在多個工作執行緒時不穩定 → debugging/flaky-tests.md, infrastructure-ci-cd/performance.md
│  ├─ 狀態洩漏/隔離 → debugging/flaky-tests.md, core/fixtures-hooks.md
│  ├─ 主控台/JS 錯誤 → debugging/console-errors.md, debugging/debugging.md
│  └─ 一般除錯 → debugging/debugging.md
│
├─ 測試錯誤情境？
│  ├─ 網路失敗 → debugging/error-testing.md, advanced/network-advanced.md
│  ├─ 離線（非預期） → debugging/error-testing.md
│  ├─ 離線優先/PWA → browser-apis/service-workers.md
│  ├─ 錯誤邊界 → debugging/error-testing.md
│  └─ 表單驗證 → testing-patterns/forms-validation.md, debugging/error-testing.md
│
├─ 重構現有程式碼？
│  ├─ 實作 POM → core/page-object-model.md
│  ├─ 改善選擇器 → core/locators.md
│  ├─ 提取固定裝置 → core/fixtures-hooks.md
│  ├─ 建立資料工廠 → core/test-data.md
│  └─ 配置設定 → core/configuration.md
│
├─ 設定基礎設施？
│  ├─ CI/CD → infrastructure-ci-cd/ci-cd.md
│  ├─ GitHub Actions → infrastructure-ci-cd/github-actions.md
│  ├─ GitLab CI → infrastructure-ci-cd/gitlab.md
│  ├─ 其他 CI 提供者 → infrastructure-ci-cd/other-providers.md
│  ├─ Docker/容器 → infrastructure-ci-cd/docker.md
│  ├─ 分片/並行 → infrastructure-ci-cd/parallel-sharding.md
│  ├─ 報告/成品 → infrastructure-ci-cd/reporting.md
│  ├─ 全域設定/拆卸 → core/global-setup.md
│  ├─ 專案相依性 → core/projects-dependencies.md
│  ├─ 測試效能 → infrastructure-ci-cd/performance.md
│  ├─ 測試涵蓋率 → infrastructure-ci-cd/test-coverage.md
│  └─ 專案配置 → core/configuration.md, core/projects-dependencies.md
│
├─ 組織測試？
│  ├─ Skip/fixme/slow 測試 → core/annotations.md
│  ├─ 測試標籤（@smoke、@fast） → core/test-tags.md
│  ├─ 篩選測試（--grep） → core/test-tags.md
│  ├─ 測試步驟 → core/annotations.md
│  └─ 條件式執行 → core/annotations.md
│
└─ 執行測試子集？
   ├─ 依標籤（@smoke、@critical） → core/test-tags.md
   ├─ 排除慢速/不穩定測試 → core/test-tags.md
   ├─ PR 與夜間測試 → core/test-tags.md, infrastructure-ci-cd/ci-cd.md
   └─ 專案特定篩選 → core/test-tags.md, core/configuration.md

測試驗證迴圈

撰寫或修改測試後：

1. 執行測試：npx playwright test --reporter=list
2. 如果測試失敗：
   • 檢視錯誤輸出與追蹤（npx playwright show-trace）
   • 修正選擇器、等待或斷言
   • 重新執行測試
3. 僅在所有測試通過後才繼續
4. 對關鍵測試多次執行：npx playwright test --repeat-each=5