TestOptions

Playwright Test 提供了許多選項來配置測試環境、瀏覽器、瀏覽器上下文和更多。

這些選項通常在配置文件中通過 testConfig.use 和 testProject.use 提供。

playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
  use: {
    headless: false,
    viewport: { width: 1280, height: 720 },
    ignoreHTTPSErrors: true,
    video: 'on-first-retry',
  },
});

或者，使用 test.use() 您可以覆蓋檔案的某些選項。

example.spec.ts
import { test, expect } from '@playwright/test';

// Run tests in this file with portrait-like viewport.
test.use({ viewport: { width: 600, height: 900 } });

test('my portrait test', async ({ page }) => {
  // ...
});

屬性

acceptDownloads

新增於：v1.10

testOptions.acceptDownloads

是否自動下載所有附件。預設為 true，表示接受所有下載。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    acceptDownloads: false,
  },
});

類型

boolean

actionTimeout

新增於：v1.10

testOptions.actionTimeout

每個 Playwright 動作的預設逾時時間（以毫秒為單位），預設為 0（無逾時）。

這是所有 Playwright 動作的預設逾時時間，與通過 page.setDefaultTimeout() 配置的逾時時間相同。

用法

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

export default defineConfig({
  use: {
    /* Maximum time each action such as `click()` can take. Defaults to 0 (no limit). */
    actionTimeout: 0,
  },
});

了解更多關於各種逾時。

類型

number

baseURL

新增於：v1.10

testOptions.baseURL

當使用 page.goto()、page.route()、page.waitForURL()、page.waitForRequest() 或 page.waitForResponse() 時，它會使用 URL() 建構函式來建構相應的 URL，從而考慮基本 URL。預設為未設定。範例

baseURL：https://127.0.0.1:3000 和導航到 /bar.html 會產生 https://127.0.0.1:3000/bar.html
baseURL：https://127.0.0.1:3000/foo/ 和導航到 ./bar.html 會產生 https://127.0.0.1:3000/foo/bar.html
baseURL：https://127.0.0.1:3000/foo (沒有尾部斜線) 和導航到 ./bar.html 會產生 https://127.0.0.1:3000/bar.html

用法

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

export default defineConfig({
  use: {
    /* Base URL to use in actions like `await page.goto('/')`. */
    baseURL: 'https://127.0.0.1:3000',
  },
});

類型

string

browserName

新增於：v1.10

testOptions.browserName

執行測試的瀏覽器名稱。預設為 'chromium'。大多數情況下，您應該在 TestConfig 中設定 browserName

用法

playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  use: {
    browserName: 'firefox',
  },
});

類型

"chromium" | "firefox" | "webkit"

bypassCSP

新增於：v1.10

testOptions.bypassCSP

切換繞過頁面的內容安全策略 (Content-Security-Policy)。預設為 false。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    bypassCSP: true,
  }
});

類型

boolean

channel

新增於：v1.10

testOptions.channel

瀏覽器發行管道。

使用 "chromium" 來選擇加入新的無頭模式。

使用 "chrome"、"chrome-beta"、"chrome-dev"、"chrome-canary"、"msedge"、"msedge-beta"、"msedge-dev" 或 "msedge-canary" 來使用品牌 Google Chrome 和 Microsoft Edge。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  projects: [
    {
      name: 'Microsoft Edge',
      use: {
        ...devices['Desktop Edge'],
        channel: 'msedge'
      },
    },
  ]
});

類型

string

clientCertificates

新增於：1.46

testOptions.clientCertificates

TLS 用戶端驗證允許伺服器請求用戶端憑證並驗證它。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    clientCertificates: [{
      origin: 'https://example.com',
      certPath: './cert.pem',
      keyPath: './key.pem',
      passphrase: 'mysecretpassword',
    }],
  },
});

類型

Array<Object>
- origin string
  
  憑證有效的確切來源。來源包括 https 協議、主機名稱和可選的埠。
- certPath string (可選)
  
  PEM 格式憑證檔案的路徑。
- cert Buffer (可選)
  
  PEM 格式憑證的直接值。
- keyPath string (可選)
  
  PEM 格式私鑰檔案的路徑。
- key Buffer (可選)
  
  PEM 格式私鑰的直接值。
- pfxPath string (可選)
  
  PFX 或 PKCS12 編碼的私鑰和憑證鏈的路徑。
- pfx Buffer (可選)
  
  PFX 或 PKCS12 編碼的私鑰和憑證鏈的直接值。
- passphrase string (可選)
  
  私鑰 (PEM 或 PFX) 的密碼。

詳細資訊

要使用的用戶端憑證陣列。每個憑證物件都必須同時具有 certPath 和 keyPath、單個 pfxPath 或其對應的直接值等效項（cert 和 key，或 pfx）。可選地，如果憑證已加密，則應提供 passphrase 屬性。origin 屬性應與憑證有效的請求來源完全匹配。

注意

在 macOS 上使用 WebKit 時，存取 localhost 將不會取得用戶端憑證。您可以通過將 localhost 替換為 local.playwright 來使其工作。

colorScheme

新增於：v1.10

testOptions.colorScheme

模擬 prefers-colors-scheme 媒體功能，支援的值為 'light' 和 'dark'。有關更多詳細資訊，請參閱 page.emulateMedia()。傳遞 null 會將模擬重置為系統預設值。預設為 'light'。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    colorScheme: 'dark',
  },
});

類型

null | "light" | "dark" | "no-preference"

connectOptions

新增於：v1.10

testOptions.connectOptions

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    connectOptions: {
      wsEndpoint: 'ws://127.0.0.1:5678',
    },
  },
});

當指定連線選項時，預設的 fixtures.browser、fixtures.context 和 fixtures.page 會使用遠端瀏覽器而不是在本機啟動瀏覽器，並且任何啟動選項（如 testOptions.headless 或 testOptions.channel）都會被忽略。

類型

void | Object
- wsEndpoint string
  
  要連線的瀏覽器 websocket 端點。
- headers void | Object<string, string> (可選)
  
  要與 web socket 連線請求一起傳送的其他 HTTP 標頭。可選。
- timeout number (可選)
  
  建立連線的逾時時間（以毫秒為單位）。可選，預設為無逾時。
- exposeNetwork string (可選)
  
  用於將連線用戶端上可用的網路公開給連線的瀏覽器的選項。有關更多詳細資訊，請參閱 browserType.connect()。

contextOptions

新增於：v1.10

testOptions.contextOptions

用於建立上下文的選項，如同傳遞給 browser.newContext()。諸如 testOptions.viewport 之類的特定選項優先於此選項。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    contextOptions: {
      reducedMotion: 'reduce',
    },
  },
});

類型

Object

deviceScaleFactor

新增於：v1.10

testOptions.deviceScaleFactor

指定裝置縮放比例 (可以認為是 dpr)。預設為 1。了解更多關於模擬具有裝置縮放比例的裝置。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    viewport: { width: 2560, height: 1440 },
    deviceScaleFactor: 2,
  },
});

類型

number

extraHTTPHeaders

新增於：v1.10

testOptions.extraHTTPHeaders

一個物件，其中包含要與每個請求一起傳送的其他 HTTP 標頭。預設為無。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    extraHTTPHeaders: {
      'X-My-Header': 'value',
    },
  },
});

類型

Object<string, string>

geolocation

新增於：v1.10

testOptions.geolocation

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    geolocation: { longitude: 12.492507, latitude: 41.889938 },
  },
});

了解更多關於地理位置。

類型

Object
- latitude number
  
  緯度，介於 -90 和 90 之間。
- longitude number
  
  經度，介於 -180 和 180 之間。
- accuracy number (可選)
  
  非負準確度值。預設為 0。

hasTouch

新增於：v1.10

testOptions.hasTouch

指定視窗是否支援觸控事件。預設為 false。了解更多關於行動裝置模擬。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    hasTouch: true
  },
});

類型

boolean

headless

新增於：v1.10

testOptions.headless

是否在無頭模式下執行瀏覽器。有關 Chromium 和 Firefox 的更多詳細資訊。預設為 true，除非 devtools 選項為 true。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    headless: false
  },
});

類型

boolean

httpCredentials

新增於：v1.10

testOptions.httpCredentials

用於 HTTP 驗證的憑證。如果未指定來源，則使用者名稱和密碼將在未經授權的回應時傳送給任何伺服器。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    httpCredentials: {
      username: 'user',
      password: 'pass',
    },
  },
});

類型

Object
- username string
- password string
- origin string (可選)
  
  限制在特定來源上傳送 http 憑證 (scheme://host:port).
- send "unauthorized" | "always" (可選)
  
  此選項僅適用於從相應 APIRequestContext 傳送的請求，並且不影響從瀏覽器傳送的請求。'always' - 帶有基本驗證憑證的 Authorization 標頭將與每個 API 請求一起傳送。'unauthorized - 憑證僅在收到帶有 WWW-Authenticate 標頭的 401 (未經授權) 回應時傳送。預設為 'unauthorized'。

ignoreHTTPSErrors

新增於：v1.10

testOptions.ignoreHTTPSErrors

是否在傳送網路請求時忽略 HTTPS 錯誤。預設為 false。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    ignoreHTTPSErrors: true,
  },
});

類型

boolean

isMobile

新增於：v1.10

testOptions.isMobile

是否考慮 meta viewport 標籤並啟用觸控事件。isMobile 是裝置的一部分，因此您實際上不需要手動設定它。預設為 false，且在 Firefox 中不受支援。了解更多關於行動裝置模擬。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    isMobile: false,
  },
});

類型

boolean

javaScriptEnabled

新增於：v1.10

testOptions.javaScriptEnabled

是否在上下文中啟用 JavaScript。預設為 true。了解更多關於停用 JavaScript。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    javaScriptEnabled: false,
  },
});

類型

boolean

launchOptions

新增於：v1.10

testOptions.launchOptions

用於啟動瀏覽器的選項，如同傳遞給 browserType.launch()。特定選項 testOptions.headless 和 testOptions.channel 優先於此選項。

警告

自行承擔使用自訂瀏覽器引數的風險，因為其中一些引數可能會破壞 Playwright 功能。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  projects: [
    {
      name: 'chromium',
      use: {
        ...devices['Desktop Chrome'],
        launchOptions: {
          args: ['--start-maximized']
        }
      }
    }
  ]
});

類型

Object

locale

新增於：v1.10

testOptions.locale

指定使用者地區設定，例如 en-GB、de-DE 等。地區設定將影響 navigator.language 值、Accept-Language 請求標頭值以及數字和日期格式規則。預設為 en-US。了解更多關於我們模擬指南中的模擬。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    locale: 'it-IT',
  },
});

類型

string

新增於：v1.10

testOptions.navigationTimeout

每個導航動作的逾時時間（以毫秒為單位）。預設為 0（無逾時）。

這是預設導航逾時時間，與通過 page.setDefaultNavigationTimeout() 配置的逾時時間相同。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    navigationTimeout: 3000,
  },
});

了解更多關於各種逾時。

類型

number

offline

新增於：v1.10

testOptions.offline

是否模擬網路離線。預設為 false。了解更多關於網路模擬。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    offline: true
  },
});

類型

boolean

permissions

新增於：v1.10

testOptions.permissions

要授予此上下文中所有頁面的權限列表。有關更多詳細資訊，請參閱 browserContext.grantPermissions()。預設為無。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    permissions: ['notifications'],
  },
});

類型

Array<string>

proxy

新增於：v1.10

testOptions.proxy

網路代理設定。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    proxy: {
      server: 'http://myproxy.com:3128',
      bypass: 'localhost',
    },
  },
});

類型

Object
- server string
  
  要用於所有請求的代理。支援 HTTP 和 SOCKS 代理，例如 http://myproxy.com:3128 或 socks5://myproxy.com:3128。簡短形式 myproxy.com:3128 被視為 HTTP 代理。
- bypass string (可選)
  
  可選的逗號分隔網域，用於繞過代理，例如 ".com, chromium.org, .domain.com"。
- username string (可選)
  
  如果 HTTP 代理需要驗證，則使用的可選使用者名稱。
- password string (可選)
  
  如果 HTTP 代理需要驗證，則使用的可選密碼。

screenshot

新增於：v1.10

testOptions.screenshot

是否在每次測試後自動擷取螢幕截圖。預設為 'off'。

'off'：不擷取螢幕截圖。
'on'：在每次測試後擷取螢幕截圖。
'only-on-failure'：僅在每次測試失敗後擷取螢幕截圖。
'on-first-failure'：僅在每次測試的第一次失敗後擷取螢幕截圖。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    screenshot: 'only-on-failure',
  },
});

了解更多關於自動螢幕截圖。

類型

Object | "off" | "on" | "only-on-failure" | "on-first-failure"
- mode "off" | "on" | "only-on-failure" | "on-first-failure"
  
  自動螢幕截圖模式。
- fullPage boolean (可選)
  
  如果為 true，則擷取整個可滾動頁面的螢幕截圖，而不是當前可見的視窗。預設為 false。
- omitBackground boolean (可選)
  
  隱藏預設的白色背景，並允許擷取具有透明度的螢幕截圖。不適用於 jpeg 影像。預設為 false。

serviceWorkers

新增於：v1.10

testOptions.serviceWorkers

是否允許站點註冊 Service workers。預設為 'allow'。

'allow'：可以註冊 Service Workers。
'block'：Playwright 將阻止所有 Service Workers 的註冊。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    serviceWorkers: 'allow'
  },
});

類型

"allow" | "block"

storageState

新增於：v1.10

testOptions.storageState

了解更多關於儲存狀態和驗證。

使用給定的儲存狀態填充上下文。此選項可用於使用通過 browserContext.storageState() 獲得的已登入資訊初始化上下文。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    storageState: 'storage-state.json',
  },
});

類型

string | Object
- cookies Array<Object>
  - name string
  - value string
  - domain string
    
    網域和路徑為必填項。為了使 Cookie 也適用於所有子網域，請在網域前加上點，例如：".example.com"
  - path string
    
    網域和路徑為必填項
  - expires number
    
    Unix 時間（以秒為單位）。
  - httpOnly boolean
  - secure boolean
  - sameSite "Strict" | "Lax" | "None"
    
    sameSite 標誌
  要為上下文設定的 Cookie
- origins Array<Object>
  - origin string
  - localStorage Array<Object>
    - name string
    - value string
  要為上下文設定的 localStorage

詳細資訊

當在配置中設定儲存狀態時，可以重置檔案的儲存狀態

not-signed-in.spec.ts
import { test } from '@playwright/test';

// Reset storage state for this file to avoid being authenticated
test.use({ storageState: { cookies: [], origins: [] } });

test('not signed in test', async ({ page }) => {
  // ...
});

testIdAttribute

新增於：v1.27

testOptions.testIdAttribute

要在 page.getByTestId() 中使用的自訂屬性。預設使用 data-testid。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    testIdAttribute: 'pw-test-id',
  },
});

timezoneId

新增於：v1.10

testOptions.timezoneId

變更上下文的時區。有關支援的時區 ID 列表，請參閱 ICU's metaZones.txt。預設為系統時區。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    timezoneId: 'Europe/Rome',
  },
});

類型

string

trace

新增於：v1.10

testOptions.trace

是否為每個測試記錄追蹤。預設為 'off'。

'off'：不記錄追蹤。
'on'：為每個測試記錄追蹤。
'on-first-retry'：僅在第一次重試測試時記錄追蹤。
'on-all-retries'：僅在重試測試時記錄追蹤。
'retain-on-failure'：為每個測試記錄追蹤。當測試執行通過時，移除記錄的追蹤。
'retain-on-first-failure'：為每個測試的第一次執行記錄追蹤，但不為重試記錄追蹤。當測試執行通過時，移除記錄的追蹤。

為了獲得更多控制，請傳遞一個物件，該物件指定要啟用的 mode 和追蹤功能。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    trace: 'on-first-retry'
  },
});

了解更多關於記錄追蹤。

類型

Object | "off" | "on" | "retain-on-failure" | "on-first-retry" | "retain-on-first-failure"
- mode "off" | "on" | "retain-on-failure" | "on-first-retry" | "on-all-retries" | "retain-on-first-failure"
  
  追蹤記錄模式。
- attachments boolean (可選)
  
  是否包含測試附件。預設為 true。可選。
- screenshots boolean (可選)
  
  是否在追蹤期間擷取螢幕截圖。螢幕截圖用於建立時間軸預覽。預設為 true。可選。
- snapshots boolean (可選)
  
  是否在每個動作上擷取 DOM 快照。預設為 true。可選。
- sources boolean (可選)
  
  是否包含追蹤動作的原始碼檔案。預設為 true。可選。

userAgent

新增於：v1.10

testOptions.userAgent

要在此上下文中使用的特定使用者代理。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    userAgent: 'some custom ua',
  },
});

類型

string

video

新增於：v1.10

testOptions.video

是否為每個測試錄製影片。預設為 'off'。

'off'：不錄製影片。
'on'：為每個測試錄製影片。
'retain-on-failure'：為每個測試錄製影片，但移除所有成功測試執行中的影片。
'on-first-retry'：僅在第一次重試測試時錄製影片。

若要控制影片大小，請傳遞具有 mode 和 size 屬性的物件。如果未指定影片大小，則其大小將等於縮小以符合 800x800 的 testOptions.viewport。如果未明確設定 viewport，則影片大小預設為 800x450。如有必要，每個頁面的實際圖片將會縮小以符合指定的大小。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    video: 'on-first-retry',
  },
});

深入了解錄製影片。

類型

Object | "off" | "on" | "retain-on-failure" | "on-first-retry"
- mode "off" | "on" | "retain-on-failure" | "on-first-retry"
  
  影片錄製模式。
- size Object (選用)
  - width number
  - height number
  錄製影片的大小。選用。

viewport

新增於：v1.10

testOptions.viewport

為每個頁面模擬一致的 viewport。預設為 1280x720 viewport。使用 null 停用一致的 viewport 模擬。深入了解viewport 模擬。

注意

null 值會選擇退出預設預設值，使 viewport 依賴於作業系統定義的主機視窗大小。這會使測試的執行變成非決定性的。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    viewport: { width: 100, height: 100 },
  },
});

類型

null | Object
- width number
  
  頁面寬度，以像素為單位。
- height number
  
  頁面高度，以像素為單位。

屬性​

acceptDownloads​

actionTimeout​

baseURL​

browserName​

bypassCSP​

channel​

clientCertificates​

colorScheme​

connectOptions​

contextOptions​

deviceScaleFactor​

extraHTTPHeaders​

geolocation​

hasTouch​

headless​

httpCredentials​

ignoreHTTPSErrors​

isMobile​

javaScriptEnabled​

launchOptions​

locale​

navigationTimeout​

offline​

permissions​

proxy​

screenshot​

serviceWorkers​

storageState​

testIdAttribute​

timezoneId​

trace​

userAgent​

video​

viewport​

屬性

acceptDownloads

actionTimeout

baseURL

browserName

bypassCSP

channel

clientCertificates

colorScheme

connectOptions

contextOptions

deviceScaleFactor

extraHTTPHeaders

geolocation

hasTouch

headless

httpCredentials

ignoreHTTPSErrors

isMobile

javaScriptEnabled

launchOptions

locale

navigationTimeout

offline

permissions

proxy

screenshot

serviceWorkers

storageState

testIdAttribute

timezoneId

trace

userAgent

video

viewport