跳到主要内容

测试使用选项

简介​

除了配置测试运行器外，您还可以为Browser或BrowserContext配置模拟选项、网络选项和录制选项。这些选项通过Playwright配置中的use: {}对象传递。

基础选项​

为所有测试设置基础URL和存储状态：

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

export default defineConfig({
  use: {
    // 用于类似`await page.goto('/')`操作的基础URL
    baseURL: 'http://localhost:3000',

    // 使用给定的存储状态填充上下文
    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: {
    // 模拟 `'prefers-colors-scheme'` 媒体特性
    colorScheme: 'dark',

    // 上下文地理位置
    geolocation: { longitude: 12.492507, latitude: 41.889938 },

    // 模拟用户区域设置
    locale: 'en-GB',

    // 授予浏览器上下文指定权限
    permissions: ['geolocation'],

    // 模拟用户时区
    timezoneId: 'Europe/Paris',

    // 上下文所有页面的视口设置
    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.httpCredentialsHTTP认证凭据。
testOptions.ignoreHTTPSErrors是否在导航期间忽略HTTPS错误。
testOptions.offline是否模拟网络离线状态。
testOptions.proxy测试中所有页面使用的代理设置。
备注

您无需配置任何内容即可模拟网络请求。只需定义一个自定义Route来模拟浏览器上下文的网络。查看我们的网络模拟指南了解更多。

录制选项​

使用 Playwright 你可以捕获屏幕截图、录制视频以及测试的追踪记录。默认情况下这些功能是关闭的，但你可以通过在 playwright.config.js 文件中设置 screenshot、video 和 trace 选项来启用它们。

追踪文件、屏幕截图和视频会出现在测试输出目录中，通常是 test-results。

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

export default defineConfig({
  use: {
    // 每次测试失败后捕获屏幕截图
    screenshot: 'only-on-failure',

    // 仅在首次重试测试时记录追踪
    trace: 'on-first-retry',

    // 仅在首次重试测试时录制视频
    video: 'on-first-retry'
  },
});
选项描述
testOptions.screenshot捕获测试的屏幕截图。选项包括 'off'、'on' 和 'only-on-failure'
testOptions.tracePlaywright 可以在运行测试时生成测试追踪记录。之后，你可以通过打开追踪查看器来查看追踪记录并获取关于 Playwright 执行的详细信息。选项包括：'off'、'on'、'retain-on-failure' 和 'on-first-retry'
testOptions.videoPlaywright 可以为你的测试录制视频。选项包括：'off'、'on'、'retain-on-failure' 和 'on-first-retry'

其他选项​

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

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

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

    // 是否绕过内容安全策略（Content-Security-Policy）。
    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是否绕过内容安全策略（Content-Security-Policy）。当 CSP 包含生产环境源时很有用。默认为 false。
testOptions.channel使用的浏览器渠道。了解更多关于不同浏览器和渠道的信息。
testOptions.headless是否以无头模式运行浏览器（运行测试时不显示浏览器界面）。默认为 true。
testOptions.testIdAttribute修改 Playwright 定位器使用的默认 data-testid 属性。

更多浏览器和上下文选项​

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

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('使用内置 browser fixture 时应继承 use 选项', 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 }) => {
    // ...
  });
});

重置选项​

您可以将选项重置为配置文件中定义的值。考虑以下设置了 baseURL 的配置：

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

export default defineConfig({
  use: {
    baseURL: 'https://playwright.dev',
  },
});

现在您可以为文件配置 baseURL，也可以为单个测试取消设置。

intro.spec.ts
import { test } from '@playwright/test';

// 为此文件配置 baseURL
test.use({ baseURL: 'https://playwright.dev/docs/intro' });

test('检查介绍内容', async ({ page }) => {
  // 此测试将使用上面定义的 "https://playwright.dev/docs/intro" 基础 URL
});

test.describe(() => {
  // 将值重置为配置中定义的值
  test.use({ baseURL: undefined });

  test('可以从首页导航到介绍页', async ({ page }) => {
    // 此测试将使用配置中定义的 "https://playwright.dev" 基础 URL
  });
});

如果您想完全将值重置为 undefined，可以使用长格式的 fixture 表示法。

intro.spec.ts
import { test } from '@playwright/test';

// 为此文件完全取消设置 baseURL
test.use({
  baseURL: [async ({}, use) => use(undefined), { scope: 'test' }],
});

test('无基础 URL', async ({ page }) => {
  // 此测试将没有基础 URL
});