5.1 playwright.config.ts 常用設定#

設定檔的角色#

playwright.config.ts 是專案的測試設定中心：跑哪些瀏覽器、連哪個網址、失敗怎麼處理，全寫在這裡。

完整的常用設定範例#

import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  // 測試檔位置
  testDir: "./tests",

  // 失敗時的處理：只在 CI 上每個失敗都完整重試
  fullyParallel: true,
  forbidOnly: !!process.env.CI,        // CI 上禁止 .only
  retries: process.env.CI ? 2 : 0,     // CI 上失敗重試 2 次
  workers: process.env.CI ? 1 : undefined,

  // 報告
  reporter: [
    ["html"],                          // HTML 報告（npx playwright show-report）
    ...(process.env.CI ? [["github"]] : []),   // CI 上輸出 GitHub 格式
  ],

  use: {
    // 測試的基準網址：page.goto("/login") 會自動補上
    baseURL: "http://localhost:3000",

    // 失敗證據
    screenshot: "only-on-failure",
    video: "retain-on-failure",
    trace: "retain-on-failure",

    // 超時（毫秒）
    actionTimeout: 10_000,
  },

  // 全域超時
  timeout: 30_000,          // 單一測試超時
  expect: {
    timeout: 5_000,         // 斷言重試超時
  },

  // 測試前自動啟動本地伺服器
  webServer: {
    command: "npm run dev",
    url: "http://localhost:3000",
    reuseExistingServer: !process.env.CI,   // 本機重用已開的伺服器
  },

  projects: [
    {
      name: "chromium",
      use: { ...devices["Desktop Chrome"] },
    },
  ],
});

最重要的幾個設定#

設定	用途
`testDir`	測試檔目錄
`baseURL`	基準網址，`page.goto("/login")` 自動補全
`retries`	失敗重試次數（CI 上開 2 次抗 flaky）
`webServer`	測試前自動啟動本地伺服器
`trace`	失敗證據
`projects`	多瀏覽器／多裝置設定（見 5.2）

baseURL 的好處#

設了 baseURL 之後，測試裡只寫路徑：

await page.goto("/login");       // 自動變成 http://localhost:3000/login

環境換了（正式站、測試站）只改設定檔，測試程式不動。

webServer：本地開發的懶人神器#

webServer: {
  command: "npm run dev",
  url: "http://localhost:3000",
  reuseExistingServer: !process.env.CI,
},

跑 npx playwright test 時：

本機：伺服器沒開就自動啟動，已開就重用
CI：自動啟動全新伺服器，測完自動關

建議：新專案直接用上面完整範例改，五分鐘就有齊全的設定。fullyParallel: true + retries: 2（CI）是抗 flaky 的黃金組合。