TestOptions
Playwright Test 提供了许多用于配置测试环境、Browser、BrowserContext 等的选项。
这些选项通常通过 配置文件 中的 testConfig.use 和 testProject.use 提供。
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
headless: false,
viewport: { width: 1280, height: 720 },
ignoreHTTPSErrors: true,
video: 'on-first-retry',
},
});
另外,使用 test.use() 可以覆盖某个文件的部分选项。
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是否自动下载所有附件。默认为 true
,即接受所有下载。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
acceptDownloads: false,
},
});
类型
actionTimeout
新增于:v1.10每个 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使用 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运行测试的浏览器名称。默认为 'chromium'
。大多数情况下,您应该在您的 TestConfig 中设置 browserName
。
用法
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
use: {
browserName: 'firefox',
},
});
类型
- "chromium" | "firefox" | "webkit"
bypassCSP
新增于:v1.10切换是否绕过页面的内容安全策略(Content-Security-Policy)。默认为 false
。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
bypassCSP: true,
}
});
类型
channel
新增于:v1.10浏览器发行渠道。
使用 "chromium" 选择启用新的无头模式。
使用 "chrome", "chrome-beta", "chrome-dev", "chrome-canary", "msedge", "msedge-beta", "msedge-dev", 或 "msedge-canary" 来使用品牌化的 Google Chrome 和 Microsoft Edge。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
projects: [
{
name: 'Microsoft Edge',
use: {
...devices['Desktop Edge'],
channel: 'msedge'
},
},
]
});
类型
clientCertificates
新增于:1.46TLS 客户端身份验证允许服务器请求并验证客户端证书。
用法
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 格式)的密码。
-
详细信息
要使用的客户端证书数组。每个证书对象必须包含 certPath
和 keyPath
,或者单个 pfxPath
,或者它们对应的直接值 (cert
和 key
,或 pfx
)。如果证书已加密,可以选择提供 passphrase
属性。origin
属性应与证书有效的请求源精确匹配。
在 macOS 上使用 WebKit 时,访问 localhost
将不会拾取客户端证书。您可以通过将 localhost
替换为 local.playwright
来使其工作。
colorScheme
新增于:v1.10模拟 prefers-colors-scheme 媒体特性,支持的值为 'light'
和 'dark'
。更多详细信息请参见 page.emulateMedia()。传入 null
将模拟重置为系统默认设置。默认为 'light'
。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
colorScheme: 'dark',
},
});
类型
- null | "light" | "dark" | "no-preference"
connectOptions
新增于:v1.10用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
connectOptions: {
wsEndpoint: 'ws://localhost:5678',
},
},
});
指定连接选项时,默认的 fixtures.browser、fixtures.context 和 fixtures.page 使用远程浏览器而不是在本地启动浏览器,并且会忽略 testOptions.headless 或 testOptions.channel 等启动选项。
类型
contextOptions
新增于:v1.10用于创建 context 的选项,传递给 browser.newContext()。testOptions.viewport 等特定选项优先于此。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
contextOptions: {
reducedMotion: 'reduce',
},
},
});
类型
deviceScaleFactor
新增于:v1.10指定设备缩放因子(可以认为是 dpr)。默认为 1
。了解更多关于使用设备缩放因子模拟设备的信息。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
viewport: { width: 2560, height: 1440 },
deviceScaleFactor: 2,
},
});
类型
extraHTTPHeaders
新增于:v1.10包含要随每个请求发送的额外 HTTP 头部的对象。默认为无。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
extraHTTPHeaders: {
'X-My-Header': 'value',
},
},
});
类型
geolocation
新增于:v1.10用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
geolocation: { longitude: 12.492507, latitude: 41.889938 },
},
});
了解更多关于地理位置的信息。
类型
hasTouch
新增于:v1.10指定视口是否支持触摸事件。默认为 false。了解更多关于移动设备模拟的信息。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
hasTouch: true
},
});
类型
headless
新增于:v1.10是否以无头模式运行浏览器。更多详细信息请参见 Chromium 和 Firefox。默认为 true
,除非 devtools 选项为 true
。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
headless: false
},
});
类型
httpCredentials
新增于:v1.10用于 HTTP 身份验证 的凭据。如果未指定 origin,则在收到未授权响应时,会将用户名和密码发送给任何服务器。
用法
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发送网络请求时是否忽略 HTTPS 错误。默认为 false
。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
ignoreHTTPSErrors: true,
},
});
类型
isMobile
新增于:v1.10是否考虑 meta viewport
标签并启用触摸事件。isMobile 是设备的一部分,因此您实际上不需要手动设置它。默认为 false
,并且在 Firefox 中不支持。了解更多关于移动设备模拟的信息。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
isMobile: false,
},
});
类型
javaScriptEnabled
新增于:v1.10是否在 context 中启用 JavaScript。默认为 true
。了解更多关于禁用 JavaScript 的信息。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
javaScriptEnabled: false,
},
});
类型
launchOptions
新增于:v1.10用于启动浏览器的选项,传递给 browserType.launch()。特定选项 testOptions.headless 和 testOptions.channel 优先于此。
使用自定义浏览器参数风险自负,因为其中一些可能会破坏 Playwright 功能。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
projects: [
{
name: 'chromium',
use: {
...devices['Desktop Chrome'],
launchOptions: {
args: ['--start-maximized']
}
}
}
]
});
类型
locale
新增于:v1.10指定用户区域设置,例如 en-GB
, de-DE
等。Locale 将影响 navigator.language
值、Accept-Language
请求头值以及数字和日期格式规则。默认为 en-US
。在我们的模拟指南中了解更多关于模拟的信息。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
locale: 'it-IT',
},
});
类型
navigationTimeout
新增于:v1.10每个导航操作的超时时间(毫秒)。默认为 0(无超时)。
这是默认的导航超时时间,与通过 page.setDefaultNavigationTimeout() 配置的相同。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
navigationTimeout: 3000,
},
});
了解更多关于各种超时时间的信息。
类型
offline
新增于:v1.10是否模拟网络离线。默认为 false
。了解更多关于网络模拟的信息。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
offline: true
},
});
类型
permissions
新增于:v1.10要授予此 context 中所有页面的权限列表。更多详细信息请参见 browserContext.grantPermissions()。默认为无。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
permissions: ['notifications'],
},
});
类型
proxy
新增于:v1.10网络代理设置。
用法
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:3128
或socks5://myproxy.com:3128
。简写形式myproxy.com:3128
被视为 HTTP 代理。 -
bypass
string (可选)可选的逗号分隔域,用于绕过代理,例如
".com, chromium.org, .domain.com"
。 -
username
string (可选)如果 HTTP 代理需要身份验证,则使用的可选用户名。
-
password
string (可选)如果 HTTP 代理需要身份验证,则使用的可选密码。
-
screenshot
新增于:v1.10是否在每次测试后自动捕获屏幕截图。默认为 'off'
。
'off'
:不捕获屏幕截图。'on'
:在每次测试后捕获屏幕截图。'only-on-failure'
:在每次测试失败后捕获屏幕截图。'on-first-failure'
:在每次测试的首次失败后捕获屏幕截图。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
screenshot: 'only-on-failure',
},
});
了解更多关于自动屏幕截图的信息。
类型
- Object | "off" | "on" | "only-on-failure" | "on-first-failure"
serviceWorkers
新增于:v1.10是否允许站点注册 Service Workers。默认为 'allow'
。
'allow'
: Service Workers 可以注册。'block'
: Playwright 将阻止所有 Service Worker 的注册。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
serviceWorkers: 'allow'
},
});
类型
- "allow" | "block"
storageState
新增于:v1.10了解更多关于存储状态和身份验证的信息。
使用给定的存储状态填充 context。此选项可用于使用通过 browserContext.storageState() 获取的登录信息初始化 context。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
storageState: 'storage-state.json',
},
});
类型
详细信息
当在配置中设置了 storage state 时,可以重置某个文件的 storage state
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在 page.getByTestId() 中使用的自定义属性。默认使用 data-testid
。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
testIdAttribute: 'pw-test-id',
},
});
timezoneId
新增于:v1.10更改 context 的时区。请参阅 ICU 的 metaZones.txt 以获取支持的时区 ID 列表。默认为系统时区。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
timezoneId: 'Europe/Rome',
},
});
类型
trace
新增于:v1.10是否记录每个测试的 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 特性的对象。
用法
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在此 context 中使用的特定用户代理。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
userAgent: 'some custom ua',
},
});
类型
video
新增于:v1.10是否记录每个测试的视频。默认为 'off'
。
'off'
:不记录视频。'on'
:记录每个测试的视频。'retain-on-failure'
:记录每个测试的视频,但移除所有成功测试运行的视频。'on-first-retry'
:仅在首次重试测试时记录视频。
要控制视频大小,请传入一个包含 mode
和 size
属性的对象。如果未指定视频大小,则会根据 testOptions.viewport 缩放以适应 800x800 的大小。如果 viewport
未显式配置,视频大小默认为 800x450。每页的实际图像如有必要将按比例缩小以适应指定大小。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
video: 'on-first-retry',
},
});
了解更多关于记录视频的信息。
类型
- Object | "off" | "on" | "retain-on-failure" | "on-first-retry"
viewport
新增于:v1.10模拟每个页面的一致视口。默认为 1280x720 视口。使用 null
可禁用一致视口模拟。了解更多关于视口模拟的信息。
null
值会退出默认预设,使视口取决于操作系统定义的主机窗口大小。这会使测试执行变得非确定性。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
viewport: { width: 100, height: 100 },
},
});
类型