测试使用选项

介绍

除了配置测试运行器，你还可以配置【浏览器】或【浏览器上下文】的 【仿真】、【网络】和【录制】选项。这些选项被传递给 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: {
    // 是否自动下载所有附件。
    acceptDownloads: false,

    // 每个请求都会发送的附加 HTTP 头。
    extraHTTPHeaders: {
      'X-My-Header': 'value',
    },

    // HTTP 认证的凭据。
    httpCredentials: {
      username: 'user',
      password: 'pass',
    },

    // 在导航过程中是否忽略 HTTPS 错误。
    ignoreHTTPSErrors: true,

    // 是否仿真网络离线。
    offline: true,

    // 为所有测试页面使用的代理设置。
    proxy: {
      server: 'http://myproxy.com:3128',
      bypass: 'localhost',
    },
  },
});

配置选项说明：

选项 描述

testOptions.acceptDownloads

是否自动下载所有附件，默认值为 true。了解更多关于下载的信息。

testOptions.extraHTTPHeaders

一个包含附加 HTTP 头的对象，所有头的值必须是字符串。

testOptions.httpCredentials

HTTP 认证的凭据。

testOptions.ignoreHTTPSErrors

是否在导航时忽略 HTTPS 错误。

testOptions.offline

是否仿真网络离线。

testOptions.proxy

为所有页面使用的代理设置。

你不需要配置任何内容来模拟网络请求。只需定义一个自定义的路由来模拟浏览器上下文的网络。了解更多关于【网络模拟】的信息。

录制选项

通过 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 可以在运行测试时生成测试痕迹。稍后你可以查看痕迹并通过 Trace Viewer 获取 Playwright 执行的详细信息。选项包括：'off'、'on'、'retain-on-failure' 和 'on-first-retry'。

testOptions.video

Playwright 可以录制测试的视频。选项包括：'off'、'on'、'retain-on-failure' 和 'on-first-retry'。

其他选项

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

export default defineConfig({
  use: {
    // 每个操作（如 `click()`）的最大超时。默认为 0（无限制）。
    actionTimeout: 0,

    // 运行测试的浏览器名称。例如 `chromium`、`firefox`、`webkit`。
    browserName: 'chromium',

    // 是否绕过内容安全策略（CSP）。
    bypassCSP: true,

    // 使用的浏览器频道，例如 "chrome"、"chrome-beta"、"msedge"、"msedge-beta"。
    channel: 'chrome',

    // 是否在无头模式下运行浏览器。
    headless: false,

    // 更改默认的 `data-testid` 属性。
    testIdAttribute: 'pw-test-id',
  },
});

配置选项说明：

选项 描述

testOptions.actionTimeout

每个 Playwright 操作的超时（以毫秒为单位）。默认为 0（没有超时）。了解更多关于超时的信息以及如何为单个测试设置它们。

testOptions.browserName

运行测试的浏览器名称。默认为 'chromium'。可选值包括 chromium、firefox 或 webkit。

testOptions.bypassCSP

是否绕过内容安全策略（CSP）。当 CSP 包含生产来源时很有用。默认为 false。

testOptions.channel

使用的浏览器频道。了解更多关于不同浏览器和频道的信息。

testOptions.headless

是否在无头模式下运行浏览器，即测试时不显示浏览器。默认为 true。

testOptions.testIdAttribute

更改 Playwright 定位器使用的默认 data-testid 属性。

更多浏览器和上下文选项

任何被 browserType.launch() 或 browser.newContext() 接受的选项，都可以放在 launchOptions 或 contextOptions 中，放在 use 部分。

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

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

然而，大多数常见的选项（如 headless 或 viewport）可以直接在 use 部分配置，见 【基本选项】、【仿真】或【网络配置】。

显式上下文创建和选项继承

如果使用内置的 browser 夹具，调用 browser.newContext() 会创建一个继承自配置选项的上下文：

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 }) => {
    // ...
  });
});