跳到主要内容

TestOptions

Playwright Test 提供了许多用于配置测试环境、BrowserBrowserContext 等的选项。

这些选项通常通过 配置文件 中的 testConfig.usetestProject.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,
},
});

类型


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,
},
});

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

类型


baseURL

新增于:v1.10 testOptions.baseURL

使用 page.goto()page.route()page.waitForURL()page.waitForRequest()page.waitForResponse() 时,它会使用 URL() 构造函数构建相应的 URL,并考虑 baseURL。默认情况下未设置。示例

  • 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

用法

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

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

类型


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,
}
});

类型


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'
},
},
]
});

类型


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 格式)的密码。

详细信息

要使用的客户端证书数组。每个证书对象必须包含 certPathkeyPath,或者单个 pfxPath,或者它们对应的直接值 (certkey,或 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://localhost:5678',
},
},
});

指定连接选项时,默认的 fixtures.browserfixtures.contextfixtures.page 使用远程浏览器而不是在本地启动浏览器,并且会忽略 testOptions.headlesstestOptions.channel 等启动选项。

类型

  • void | Object
    • wsEndpoint string

      要连接的浏览器 websocket 端点。

    • headers void | Object<string, string> (可选)

      WebSocket 连接请求附带的额外 HTTP 头。可选。

    • timeout number (可选)

      建立连接的超时时间(毫秒)。可选,默认为无超时。

    • exposeNetwork string (可选)

      将连接客户端上可用的网络暴露给正在连接的浏览器的选项。更多详细信息请参见 browserType.connect()


contextOptions

新增于:v1.10 testOptions.contextOptions

用于创建 context 的选项,传递给 browser.newContext()。testOptions.viewport 等特定选项优先于此。

用法

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

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

类型


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,
},
});

类型


extraHTTPHeaders

新增于:v1.10 testOptions.extraHTTPHeaders

包含要随每个请求发送的额外 HTTP 头部的对象。默认为无。

用法

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

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

类型


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
},
});

类型


headless

新增于:v1.10 testOptions.headless

是否以无头模式运行浏览器。更多详细信息请参见 ChromiumFirefox。默认为 true,除非 devtools 选项为 true

用法

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

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

类型


httpCredentials

新增于:v1.10 testOptions.httpCredentials

用于 HTTP 身份验证 的凭据。如果未指定 origin,则在收到未授权响应时,会将用户名和密码发送给任何服务器。

用法

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

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

类型

  • Object
    • username string

    • password string

    • origin string (可选)

      限制在特定源 (scheme://host:port).

    • send "unauthorized" | "always" (可选)

      此选项仅适用于从相应的 APIRequestContext 发送的请求,不影响从浏览器发送的请求。'always' - 每次 API 请求都会发送包含基本身份验证凭据的 Authorization 头。'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,
},
});

类型


isMobile

新增于:v1.10 testOptions.isMobile

是否考虑 meta viewport 标签并启用触摸事件。isMobile 是设备的一部分,因此您实际上不需要手动设置它。默认为 false,并且在 Firefox 中不支持。了解更多关于移动设备模拟的信息。

用法

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

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

类型


javaScriptEnabled

新增于:v1.10 testOptions.javaScriptEnabled

是否在 context 中启用 JavaScript。默认为 true。了解更多关于禁用 JavaScript 的信息。

用法

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

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

类型


launchOptions

新增于:v1.10 testOptions.launchOptions

用于启动浏览器的选项,传递给 browserType.launch()。特定选项 testOptions.headlesstestOptions.channel 优先于此。

警告

使用自定义浏览器参数风险自负,因为其中一些可能会破坏 Playwright 功能。

用法

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

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

类型


locale

新增于:v1.10 testOptions.locale

指定用户区域设置,例如 en-GB, de-DE 等。Locale 将影响 navigator.language 值、Accept-Language 请求头值以及数字和日期格式规则。默认为 en-US。在我们的模拟指南中了解更多关于模拟的信息。

用法

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

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

类型


navigationTimeout

新增于:v1.10 testOptions.navigationTimeout

每个导航操作的超时时间(毫秒)。默认为 0(无超时)。

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

用法

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

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

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

类型


offline

新增于:v1.10 testOptions.offline

是否模拟网络离线。默认为 false。了解更多关于网络模拟的信息。

用法

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

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

类型


permissions

新增于:v1.10 testOptions.permissions

要授予此 context 中所有页面的权限列表。更多详细信息请参见 browserContext.grantPermissions()。默认为无。

用法

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

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

类型


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:3128socks5://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 Worker 的注册。

用法

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

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

类型

  • "allow" | "block"

storageState

新增于:v1.10 testOptions.storageState

了解更多关于存储状态和身份验证的信息。

使用给定的存储状态填充 context。此选项可用于使用通过 browserContext.storageState() 获取的登录信息初始化 context。

用法

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

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

类型

详细信息

当在配置中设置了 storage state 时,可以重置某个文件的 storage state

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

更改 context 的时区。请参阅 ICU 的 metaZones.txt 以获取支持的时区 ID 列表。默认为系统时区。

用法

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

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

类型


trace

新增于:v1.10 testOptions.trace

是否记录每个测试的 trace。默认为 'off'

  • 'off':不记录 trace。
  • 'on':记录每个测试的 trace。
  • 'on-first-retry':仅在首次重试测试时记录 trace。
  • 'on-all-retries':仅在重试测试时记录 trace。
  • 'retain-on-failure':记录每个测试的 trace。测试运行时通过时,删除记录的 trace。
  • 'retain-on-first-failure':记录每个测试首次运行的 trace,但不包括重试。测试运行时通过时,删除记录的 trace。

要进行更多控制,请传入一个指定 mode 和要启用的 trace 特性的对象。

用法

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

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

了解更多关于记录 trace的信息。

类型

  • 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"

      Trace 记录模式。

    • attachments boolean (可选)

      是否包含测试附件。默认为 true。可选。

    • screenshots boolean (可选)

      在 trace 期间是否捕获屏幕截图。屏幕截图用于构建时间轴预览。默认为 true。可选。

    • snapshots boolean (可选)

      是否在每次操作时捕获 DOM 快照。默认为 true。可选。

    • sources boolean (可选)

      是否包含 trace 动作的源文件。默认为 true。可选。


userAgent

新增于:v1.10 testOptions.userAgent

在此 context 中使用的特定用户代理。

用法

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

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

类型


video

新增于:v1.10 testOptions.video

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

  • 'off':不记录视频。
  • 'on':记录每个测试的视频。
  • 'retain-on-failure':记录每个测试的视频,但移除所有成功测试运行的视频。
  • 'on-first-retry':仅在首次重试测试时记录视频。

要控制视频大小,请传入一个包含 modesize 属性的对象。如果未指定视频大小,则会根据 testOptions.viewport 缩放以适应 800x800 的大小。如果 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 (可选)

      记录视频的大小。可选。


viewport

新增于:v1.10 testOptions.viewport

模拟每个页面的一致视口。默认为 1280x720 视口。使用 null 可禁用一致视口模拟。了解更多关于视口模拟的信息。

注意

null 值会退出默认预设,使视口取决于操作系统定义的主机窗口大小。这会使测试执行变得非确定性。

用法

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

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

类型