TestOptions

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

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

类型

boolean

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

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

类型

number

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

类型

string

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

类型

boolean

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

类型

string

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

详细信息

要使用的客户端证书数组。每个证书对象必须包含 certPath 和 keyPath，或者单个 pfxPath，或者它们对应的直接值 (cert 和 key，或 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.browser、fixtures.context 和 fixtures.page 使用远程浏览器而不是在本地启动浏览器，并且会忽略 testOptions.headless 或 testOptions.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',
    },
  },
});

类型

Object

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

类型

number

extraHTTPHeaders

新增于：v1.10

testOptions.extraHTTPHeaders

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

用法

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

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

类型

Object<string, string>

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

类型

boolean

headless

新增于：v1.10

testOptions.headless

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

用法

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

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

类型

boolean

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

类型

boolean

isMobile

新增于：v1.10

testOptions.isMobile

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

用法

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

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

类型

boolean

javaScriptEnabled

新增于：v1.10

testOptions.javaScriptEnabled

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

用法

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

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

类型

boolean

launchOptions

新增于：v1.10

testOptions.launchOptions

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

警告

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

用法

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

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

类型

Object

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

类型

string

新增于：v1.10

testOptions.navigationTimeout

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

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

用法

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

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

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

类型

number

offline

新增于：v1.10

testOptions.offline

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

用法

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

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

类型

boolean

permissions

新增于：v1.10

testOptions.permissions

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

用法

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

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

类型

Array<string>

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: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

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

类型

string | Object
- cookies Array<Object>
  - name string
  - value string
  - domain string
    
    域和路径是必需的。为了使 cookie 也适用于所有子域，请在域前加上一个点，例如：".example.com"
  - path string
    
    域和路径是必需的
  - expires number
    
    Unix 时间（秒）。
  - httpOnly boolean
  - secure boolean
  - sameSite "Strict" | "Lax" | "None"
    
    sameSite flag
  为 context 设置的 Cookies
- origins Array<Object>
  - origin string
  - localStorage Array<Object>
    - name string
    - value string
    为 context 设置的 localStorage

详细信息

当在配置中设置了 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',
  },
});

类型

string

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

类型

string

video

新增于：v1.10

testOptions.video

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

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

要控制视频大小，请传入一个包含 mode 和 size 属性的对象。如果未指定视频大小，则会根据 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 (可选)
  - width number
  - height number
  记录视频的大小。可选。

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

类型

null | Object
- width number
  
  页面宽度（像素）。
- height number
  
  页面高度（像素）。

属性​

acceptDownloads​

actionTimeout​

baseURL​

browserName​

bypassCSP​

channel​

clientCertificates​

colorScheme​

connectOptions​

contextOptions​

deviceScaleFactor​

extraHTTPHeaders​

geolocation​

hasTouch​

headless​

httpCredentials​

ignoreHTTPSErrors​

isMobile​

javaScriptEnabled​

launchOptions​

locale​

navigationTimeout​

offline​

permissions​

proxy​

screenshot​

serviceWorkers​

storageState​

testIdAttribute​

timezoneId​

trace​

userAgent​

video​

viewport​

属性

acceptDownloads

actionTimeout

baseURL

browserName

bypassCSP

channel

clientCertificates

colorScheme

connectOptions

contextOptions

deviceScaleFactor

extraHTTPHeaders

geolocation

hasTouch

headless

httpCredentials

ignoreHTTPSErrors

isMobile

javaScriptEnabled

launchOptions

locale

navigationTimeout

offline

permissions

proxy

screenshot

serviceWorkers

storageState

testIdAttribute

timezoneId

trace

userAgent

video

viewport