Skip to main content

TestOptions

Playwright Test 提供了许多选项来配置测试环境、Browser、BrowserContext 等。

这些选项通常在配置文件中通过 testConfig.use 和 testProject.use 提供。

import type { PlaywrightTestConfig } from '@playwright/test';
const config: PlaywrightTestConfig = {
  use: {
    headless: false,
    viewport: { width: 1280, height: 720 },
    ignoreHTTPSErrors: true,
    video: 'on-first-retry',
  },
};
export default config;

或者，使用 test.use(options) 可以覆盖文件的某些选项。

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

// 在此文件中使用纵向视口运行测试。
test.use({ viewport: { width: 600, height: 900 } });

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

testOptions.acceptDownloads​

Added in: v1.10

是否自动下载所有附件。默认为 true，即接受所有下载。

testOptions.actionTimeout​

Added in: v1.10

每个 Playwright 操作的默认超时时间（以毫秒为单位），默认为 0（无超时）。

这是所有 Playwright 操作的默认超时，与通过 page.setDefaultTimeout(timeout) 配置的相同。

了解有关各种超时的更多信息。

testOptions.baseURL​

Added in: v1.10

当使用 page.goto(url[, options])、page.route(url, handler[, options])、page.waitForURL(url[, options])、page.waitForRequest(urlOrPredicate[, options]) 或 page.waitForResponse(urlOrPredicate[, options]) 时，它会通过使用 URL() 构造函数构建相应的 URL 来考虑基本 URL。示例：

  • baseURL: http://localhost:3000 并且导航到 /bar.html 结果为 http://localhost:3000/bar.html
  • baseURL: http://localhost:3000/foo/ 并且导航到 ./bar.html 结果为 http://localhost:3000/foo/bar.html
  • baseURL: http://localhost:3000/foo (没有尾部斜杠) 并且导航到 ./bar.html 结果为 http://localhost:3000/bar.html

testOptions.browserName​

Added in: v1.10
  • type: <"chromium"|"firefox"|"webkit">

运行测试的浏览器名称。默认为 'chromium'。大多数情况下，您应该在 TestConfig 中设置 browserName：

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

const config: PlaywrightTestConfig = {
  use: {
    browserName: 'firefox',
  },
};
export default config;

testOptions.bypassCSP​

Added in: v1.10

切换绕过页面的 Content-Security-Policy。

testOptions.channel​

Added in: v1.10

浏览器分发渠道。支持的值有 "chrome"、"chrome-beta"、"chrome-dev"、"chrome-canary"、"msedge"、"msedge-beta"、"msedge-dev"、"msedge-canary"。阅读有关使用 Google Chrome 和 Microsoft Edge 的更多信息。

testOptions.colorScheme​

Added in: v1.10
  • type: <"light"|"dark"|"no-preference">

模拟 'prefers-colors-scheme' 媒体特性，支持的值有 'light'、'dark'、'no-preference'。有关更多详细信息，请参阅 page.emulateMedia([options])。默认为 'light'。

testOptions.connectOptions​

Added in: v1.10
  • type: <void|Object>
    • wsEndpoint <string> 要连接的浏览器 websocket 端点。
    • headers? <void|Object<string, string>> 与 web socket 连接请求一起发送的其他 HTTP 标头。可选。
    • timeout? <number> 建立连接的超时时间（以毫秒为单位）。可选，默认为无超时。

指定连接选项时，默认的 fixtures.browser、fixtures.context 和 fixtures.page 使用远程浏览器而不是在本地启动浏览器，并且任何启动选项（如 testOptions.headless 或 testOptions.channel）都将被忽略。

testOptions.contextOptions​

Added in: v1.10

用于创建上下文的选项，传递给 browser.newContext([options])。特定选项（如 testOptions.viewport）优先于此选项。

testOptions.deviceScaleFactor​

Added in: v1.10

指定设备缩放因子（可以认为是 dpr）。默认为 1。

testOptions.extraHTTPHeaders​

Added in: v1.10

包含要随每个请求发送的附加 HTTP 标头的对象。

testOptions.geolocation​

Added in: v1.10
  • type: <Object>
    • latitude <number> -90 到 90 之间的纬度。
    • longitude <number> -180 到 180 之间的经度。
    • accuracy? <number> 非负精度值。默认为 0。

testOptions.hasTouch​

Added in: v1.10

指定视口是否支持触摸事件。默认为 false。

testOptions.headless​

Added in: v1.10

是否在无头模式下运行浏览器。有关 Chromium 和 Firefox 的更多详细信息。默认为 true，除非 devtools 选项为 true。

testOptions.httpCredentials​

Added in: v1.10

HTTP 身份验证的凭据。

testOptions.ignoreHTTPSErrors​

Added in: v1.10

发送网络请求时是否忽略 HTTPS 错误。默认为 false。

testOptions.isMobile​

Added in: v1.10

是否考虑 meta viewport 标签并启用触摸事件。默认为 false。Firefox 不支持。

testOptions.javaScriptEnabled​

Added in: v1.10

是否在上下文中启用 JavaScript。默认为 true。

testOptions.launchOptions​

Added in: v1.10

用于启动浏览器的选项，传递给 browserType.launch([options])。特定选项 testOptions.headless 和 testOptions.channel 优先于此选项。

testOptions.locale​

Added in: v1.10

指定用户区域设置，例如 en-GB、de-DE 等。区域设置将影响 navigator.language 值、Accept-Language 请求标头值以及数字和日期格式规则。

testOptions.navigationTimeout​

Added in: v1.10

每个导航操作的超时时间（以毫秒为单位）。默认为 0（无超时）。

这是默认的导航超时，与通过 page.setDefaultNavigationTimeout(timeout) 配置的相同。

了解有关各种超时的更多信息。

testOptions.offline​

Added in: v1.10

是否模拟网络离线。默认为 false。

testOptions.permissions​

Added in: v1.10

要授予此上下文中所有页面的权限列表。有关更多详细信息，请参阅 browserContext.grantPermissions(permissions[, options])。

testOptions.proxy​

Added in: v1.10
  • type: <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 代理需要身份验证，则为可选密码。

网络代理设置。

testOptions.screenshot​

Added in: v1.10
  • type: <"off"|"on"|"only-on-failure">

是否在每次测试后自动捕获屏幕截图。默认为 'off'。

  • 'off': 不捕获屏幕截图。
  • 'on': 每次测试后捕获屏幕截图。
  • 'only-on-failure': 每次测试失败后捕获屏幕截图。

了解有关自动屏幕截图的更多信息。

testOptions.serviceWorkers​

Added in: v1.10
  • type: <"allow"|"block">

是否允许站点注册 Service workers。默认为 'allow'。

  • 'allow': 可以注册 Service Workers。
  • 'block': Playwright 将阻止所有 Service Workers 的注册。

testOptions.storageState​

Added in: v1.10

使用给定的存储状态填充上下文。此选项可用于使用通过 browserContext.storageState([options]) 获取的登录信息初始化上下文。可以是保存存储的文件的路径，也可以是具有以下字段的对象：

testOptions.testIdAttribute​

Added in: v1.27

在 page.getByTestId(testId) 中使用的自定义属性。默认使用 data-testid。

testOptions.timezoneId​

Added in: v1.10

更改上下文的时区。有关支持的时区 ID 列表，请参阅 ICU 的 metaZones.txt。

testOptions.trace​

Added in: v1.10
  • type: <Object|"off"|"on"|"retain-on-failure"|"on-first-retry">
    • mode <"off"|"on"|"retain-on-failure"|"on-first-retry"> 跟踪记录模式。
    • screenshots? <boolean> 是否在跟踪期间捕获屏幕截图。屏幕截图用于构建时间轴预览。默认为 true。可选。
    • snapshots? <boolean> 是否在每次操作时捕获 DOM 快照。默认为 true。可选。
    • sources? <boolean> 是否在跟踪操作中包含源文件。默认为 true。可选。

是否为每个测试记录跟踪。默认为 'off'。

  • 'off': 不记录跟踪。
  • 'on': 为每个测试记录跟踪。
  • 'retain-on-failure': 为每个测试记录跟踪，但从成功的测试运行中删除所有跟踪。
  • 'on-first-retry': 仅在首次重试测试时记录跟踪。

要进行更多控制，请传递一个指定 mode 和要启用的跟踪功能的对象。

了解有关记录跟踪的更多信息。

testOptions.userAgent​

Added in: v1.10

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

testOptions.video​

Added in: v1.10
  • type: <Object|"off"|"on"|"retain-on-failure"|"on-first-retry">
    • mode <"off"|"on"|"retain-on-failure"|"on-first-retry"> 视频录制模式。
    • size? <Object> 录制视频的尺寸。可选。

是否为每个测试录制视频。默认为 'off'。

  • 'off': 不录制视频。
  • 'on': 为每个测试录制视频。
  • 'retain-on-failure': 为每个测试录制视频，但从成功的测试运行中删除所有视频。
  • 'on-first-retry': 仅在首次重试测试时录制视频。

要控制视频尺寸，请传递一个具有 mode 和 size 属性的对象。如果未指定视频尺寸，它将等于 testOptions.viewport 缩小以适应 800x800。如果未显式配置 viewport，则视频尺寸默认为 800x450。如果需要，每个页面的实际图片将按比例缩小以适应指定尺寸。

了解有关录制视频的更多信息。

testOptions.viewport​

Added in: v1.10
  • type: <null|Object>
    • width <number> 页面宽度（以像素为单位）。
    • height <number> 页面高度（以像素为单位）。

为每个页面模拟一致的视口。默认为 1280x720 视口。null 禁用默认视口。