測試使用選項

簡介

除了設定測試執行器，您還可以為瀏覽器或瀏覽器上下文設定模擬、網路和錄製。這些選項會傳遞到 Playwright 設定中的 use: {} 物件。

基本選項

為所有測試設定基礎 URL 和儲存狀態

playwright.config.ts

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

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

    // Populates context with given storage state.
    storageState: 'state.json',
  },
});

選項	描述
testOptions.baseURL	用於上下文中所有頁面的基礎 URL。允許僅使用路徑進行導航，例如 page.goto('/settings')。
testOptions.storageState	使用給定的儲存狀態填充上下文。適用於簡便的身份驗證，了解更多。

模擬選項

使用 Playwright，您可以模擬真實裝置，例如手機或平板電腦。請參閱我們的專案指南，以獲取有關模擬裝置的更多資訊。您還可以為所有測試或特定測試模擬 "geolocation"、"locale" 和 "timezone"，以及設定 "permissions" 以顯示通知或更改 "colorScheme"。請參閱我們的模擬指南以了解更多資訊。

playwright.config.ts

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

export default defineConfig({
  use: {
    // Emulates `'prefers-colors-scheme'` media feature.
    colorScheme: 'dark',

    // Context geolocation.
    geolocation: { longitude: 12.492507, latitude: 41.889938 },

    // Emulates the user locale.
    locale: 'en-GB',

    // Grants specified permissions to the browser context.
    permissions: ['geolocation'],

    // Emulates the user timezone.
    timezoneId: 'Europe/Paris',

    // Viewport used for all pages in the context.
    viewport: { width: 1280, height: 720 },
  },
});

選項	描述
testOptions.colorScheme	模擬 'prefers-colors-scheme' 媒體功能，支援的值為 'light' 和 'dark'
testOptions.geolocation	上下文 地理位置。
testOptions.locale	模擬 使用者地區設定，例如 en-GB、de-DE 等。
testOptions.permissions	要授予上下文中所有頁面的 權限 列表。
testOptions.timezoneId	更改上下文的 時區。
testOptions.viewport	用於上下文中所有頁面的 視窗。

網路選項

可用於設定網路的選項

playwright.config.ts

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

export default defineConfig({
  use: {
    // Whether to automatically download all the attachments.
    acceptDownloads: false,

    // An object containing additional HTTP headers to be sent with every request.
    extraHTTPHeaders: {
      'X-My-Header': 'value',
    },

    // Credentials for HTTP authentication.
    httpCredentials: {
      username: 'user',
      password: 'pass',
    },

    // Whether to ignore HTTPS errors during navigation.
    ignoreHTTPSErrors: true,

    // Whether to emulate network being offline.
    offline: true,

    // Proxy settings used for all pages in the test.
    proxy: {
      server: 'http://myproxy.com:3128',
      bypass: 'localhost',
    },
  },
});

選項	描述
testOptions.acceptDownloads	是否自動下載所有附件，預設為 true。 了解更多 關於使用下載。
testOptions.extraHTTPHeaders	一個包含額外 HTTP 標頭的物件，這些標頭將隨每個請求發送。所有標頭值必須是字串。
testOptions.httpCredentials	HTTP 身份驗證 的憑證。
testOptions.ignoreHTTPSErrors	是否在導航期間忽略 HTTPS 錯誤。
testOptions.offline	是否模擬網路離線。
testOptions.proxy	用於測試中所有頁面的 Proxy 設定。

注意

您不必設定任何內容來模擬網路請求。只需定義一個自訂的 Route，為瀏覽器上下文模擬網路。請參閱我們的網路模擬指南以了解更多資訊。

錄製選項

使用 Playwright，您可以捕獲螢幕截圖、錄製影片以及測試的追蹤記錄。預設情況下，這些功能是關閉的，但您可以通過在您的 playwright.config.js 檔案中設定 screenshot、video 和 trace 選項來啟用它們。

追蹤檔案、螢幕截圖和影片將出現在測試輸出目錄中，通常是 test-results。

playwright.config.ts

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

export default defineConfig({
  use: {
    // Capture screenshot after each test failure.
    screenshot: 'only-on-failure',

    // Record trace only when retrying a test for the first time.
    trace: 'on-first-retry',

    // Record video only when retrying a test for the first time.
    video: 'on-first-retry'
  },
});

選項	描述
testOptions.screenshot	捕獲測試的螢幕截圖。選項包括 'off'、'on' 和 'only-on-failure'
testOptions.trace	Playwright 可以在運行測試時產生測試追蹤記錄。之後，您可以通過打開 追蹤檢視器 來查看追蹤記錄並獲得有關 Playwright 執行的詳細資訊。選項包括：'off'、'on'、'retain-on-failure' 和 'on-first-retry'
testOptions.video	Playwright 可以為您的測試錄製影片。選項包括：'off'、'on'、'retain-on-failure' 和 'on-first-retry'

其他選項

playwright.config.ts

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

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

    // Name of the browser that runs tests. For example `chromium`, `firefox`, `webkit`.
    browserName: 'chromium',

    // Toggles bypassing Content-Security-Policy.
    bypassCSP: true,

    // Channel to use, for example "chrome", "chrome-beta", "msedge", "msedge-beta".
    channel: 'chrome',

    // Run browser in headless mode.
    headless: false,

    // Change the default data-testid attribute.
    testIdAttribute: 'pw-test-id',
  },
});

選項	描述
testOptions.actionTimeout	每個 Playwright 動作的逾時時間，以毫秒為單位。預設為 0 (無逾時)。了解更多 關於逾時以及如何為單個測試設定它們。
testOptions.browserName	運行測試的瀏覽器名稱。預設為 'chromium'。選項包括 chromium、firefox 或 webkit。
testOptions.bypassCSP	切換繞過內容安全策略 (Content-Security-Policy)。當 CSP 包含生產來源時很有用。預設為 false。
testOptions.channel	要使用的瀏覽器管道。了解更多 關於不同的瀏覽器和管道。
testOptions.headless	是否在無頭模式下運行瀏覽器，這表示運行測試時不顯示瀏覽器。預設為 true。
testOptions.testIdAttribute	更改 Playwright 定位器使用的預設 data-testid 屬性。

更多瀏覽器和上下文選項

browserType.launch() 或 browser.newContext() 接受的任何選項都可以分別放入 launchOptions 或 contextOptions 的 use 區段中。

playwright.config.ts

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

export default defineConfig({
  use: {
    launchOptions: {
      slowMo: 50,
    },
  },
});

但是，大多數常見的選項，如 headless 或 viewport，可以直接在 use 區段中使用 - 請參閱基本選項、模擬 或 網路。

顯式上下文創建和選項繼承

如果使用內建的 browser fixture，調用 browser.newContext() 將創建一個上下文，其選項繼承自設定

playwright.config.ts

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

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

一個範例測試，說明了如何設定初始上下文選項

test('should inherit use options on context when using built-in browser fixture', async ({
  browser,
}) => {
  const context = await browser.newContext();
  const page = await context.newPage();
  expect(await page.evaluate(() => navigator.userAgent)).toBe('some custom ua');
  expect(await page.evaluate(() => window.innerWidth)).toBe(100);
  await context.close();
});

設定範圍

您可以全域、按專案或按測試設定 Playwright。例如，您可以通過將 locale 添加到 Playwright 設定的 use 選項中來設定全域使用的地區設定，然後使用設定中的 project 選項為特定專案覆蓋它。您還可以通過在測試檔案中添加 test.use({}) 並傳遞選項來為特定測試覆蓋它。

playwright.config.ts

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

export default defineConfig({
  use: {
    locale: 'en-GB'
  },
});

您可以使用 Playwright 設定中的 project 選項來覆蓋特定專案的選項。

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

export default defineConfig({
  projects: [
    {
      name: 'chromium',
      use: {
        ...devices['Desktop Chrome'],
        locale: 'de-DE',
      },
    },
  ],
});

您可以使用 test.use() 方法並傳遞選項來覆蓋特定測試檔案的選項。例如，為特定測試使用法語地區設定運行測試

import { test, expect } from '@playwright/test';

test.use({ locale: 'fr-FR' });

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

同樣的方法也適用於 describe 區塊內。例如，在具有法語地區設定的 describe 區塊中運行測試

import { test, expect } from '@playwright/test';

test.describe('french language block', () => {

  test.use({ locale: 'fr-FR' });

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