Playwright 使用入門

前言

Playwright 是由 Microsoft 支援的自動化測試與瀏覽器自動化工具，支援 Chromium、Firefox、WebKit，能用來做 E2E 測試、功能測試、爬蟲與跨瀏覽器驗證。本文以實務導向，簡潔介紹安裝、範例、偵錯、CI 整合與常見最佳實務，讓你能快速上手並在專案中穩定執行。

快速安裝（Node.js 範例）

建立專案：npm init -y
安裝 Playwright（含瀏覽器）：npm i -D @playwright/test
或僅安裝 core：npm i -D playwright
安裝瀏覽器（若使用 core）：npx playwright install
執行測試（Playwright Test runner）：npx playwright test

核心概念（簡單說明）

Browser：瀏覽器二進位（Chromium/Firefox/WebKit）。
BrowserContext：隔離的瀏覽器環境（類似新分頁的 profile），可同時建立多個 context 實現平行測試與隔離 cookies/session。
Page：context 內的一個分頁（page）。主要在 page 上執行點擊、輸入、截圖等操作。
Locator / Selector：穩定的選取器，Playwright 推薦使用 data-testid 或 role，避免脆弱的 CSS 路徑。

最簡範例（Playwright Test, JavaScript）

// tests/example.spec.js
const { test, expect } = require('@playwright/test');

test('首頁可以載入並顯示標題', async ({ page }) => {
  await page.goto('https://example.com');
  await expect(page).toHaveTitle(/Example/);
});

常用操作範例

點擊：await page.click('button#buy')
輸入：await page.fill('input[name="q"]', 'Playwright')
等待元素：await page.waitForSelector('.result')
截圖：await page.screenshot({ path: 'shot.png' })
攔截/模擬 API：使用 page.route() 或 test fixture 的 network mocking。

偵錯技巧

開啟 headed 模式方便觀察：在 config 或程式碼中設 headless: false。
保留 trace 與錄製：npx playwright test --trace on，測試失敗時可以回放 trace。
使用 page.pause() 在測試中中斷進入交互式偵錯。
加上 await page.locator(...).scrollIntoViewIfNeeded() 或顯式等待，避免非同步 timing 問題。

CI 整合要點

Playwright 提供官方 GitHub Actions 支援，也能在任何 CI（GitLab CI、Jenkins、Azure DevOps）執行。

在 CI 中執行 npx playwright install --with-deps（某些 Linux runner 需要額外依賴）。
設定適度的重試與並行數（retries、workers），讓不穩定測試自動重跑一次降低偽陽性。
在失敗時上傳 trace、截圖與錄影以利除錯。

進階功能速覽

跨瀏覽器測試：同一套測試可針對 Chromium/Firefox/WebKit 執行。
Network Mocking：攔截 API 回應做穩定測試或模擬錯誤情境。
File Upload / Download 支援。
BrowserContext 快照與 state 儲存，方便登入後的重複測試。
Tracing/Inspector：失敗時逐步回放操作與網路資訊。

最佳實務建議

使用穩定的選取器（例如 data-testid），不要太依賴結構性的 CSS 選取器。
避免使用固定時間等待（sleep），改用等待元素或 network idle。
將測試切成小單元，單一測試只驗證一個行為，方便定位失敗原因。
在 CI 上設定合理的 workers 數量與資源（記憶體 / CPU）以避免環境不穩定導致雜訊失敗。
利用 trace、截圖與錄影，加速問題回溯。

結語與延伸資源

Playwright 對於需要穩定跨瀏覽器 E2E 測試的專案非常合適，從快速上手到進階監控（trace、network mock）都有完整支援。建議從 Playwright Test 快速搭建測試骨架，逐步把常見流程納入自動化，並在 CI 中加入失敗蒐集（trace/screenshot）以提升維護效率。