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';

// 以类似竖屏的视口运行此文件中的测试
test.use({ viewport: { width: 600, height: 900 } });

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

属性

acceptDownloads

Added in: 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: {
    /* 每个操作（如 `click()`）允许的最大执行时间。默认为 0（无限制）。 */
    actionTimeout: 0,
  },
});

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

类型

number

baseURL

Added in: v1.10

testOptions.baseURL

当使用 page.goto()、page.route()、page.waitForURL()、page.waitForRequest() 或 page.waitForResponse() 时，会通过 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

用法

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

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

类型

string

browserName

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

Added in: v1.10

testOptions.bypassCSP

切换是否绕过页面的内容安全策略(Content-Security-Policy)。默认为 false。

用法

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

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

类型

boolean

channel

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

Added in: v1.10

testOptions.contextOptions

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

用法

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

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

类型

Object

deviceScaleFactor

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

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

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

Added in: v1.10

testOptions.hasTouch

指定视口是否支持触摸事件。默认为 false。了解更多关于移动设备模拟的信息。

用法

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

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

类型

boolean

headless

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

Added in: 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)发送 HTTP 凭证。
- send "unauthorized" | "always" (可选)
  
  此选项仅适用于从相应 APIRequestContext 发送的请求，不影响从浏览器发送的请求。'always' - 每个 API 请求都会发送带有基本认证凭证的 Authorization 头。'unauthorized - 仅当收到带有 WWW-Authenticate 头的 401 (未授权) 响应时才发送凭证。默认为 'unauthorized'。

ignoreHTTPSErrors

Added in: v1.10

testOptions.ignoreHTTPSErrors

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

用法

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

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

类型

boolean

isMobile

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

Added in: v1.10

testOptions.javaScriptEnabled

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

用法

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

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

类型

boolean

launchOptions

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

Added in: v1.10

testOptions.locale

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

用法

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

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

类型

string

Added in: v1.10

testOptions.navigationTimeout

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

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

用法

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

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

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

类型

number

offline

Added in: v1.10

testOptions.offline

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

用法

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

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

类型

boolean

permissions

Added in: v1.10

testOptions.permissions

授予此上下文中所有页面的权限列表。详情参见 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

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

Added in: v1.10

testOptions.serviceWorkers

是否允许网站注册 Service Worker。默认为 '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

Added in: v1.10

testOptions.storageState

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

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

用法

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标记
  为上下文设置的cookies
- origins Array<Object>
  - origin string
  - localStorage Array<Object>
    - name string
    - value string
    为上下文设置的localStorage

详细信息

当在配置中设置了存储状态时，可以为特定文件重置存储状态：

not-signed-in.spec.ts
import { test } from '@playwright/test';

// 为此文件重置存储状态以避免认证状态
test.use({ storageState: { cookies: [], origins: [] } });

test('未登录测试', async ({ page }) => {
  // ...
});

testIdAttribute

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

Added in: v1.10

testOptions.timezoneId

更改上下文的时区。支持的时区 ID 列表请参见 ICU's metaZones.txt。默认为系统时区。

用法

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

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

类型

string

trace

添加于: v1.10

testOptions.trace

是否记录每个测试的追踪信息。默认为 'off'。

'off': 不记录追踪信息。
'on': 为每个测试记录追踪信息。
'on-first-retry': 仅在首次重试测试时记录追踪信息。
'on-all-retries': 仅在重试测试时记录追踪信息。
'retain-on-failure': 为每个测试记录追踪信息。当测试运行通过时，删除记录的追踪信息。
'retain-on-first-failure': 为每个测试的首次运行记录追踪信息，但不记录重试。当测试运行通过时，删除记录的追踪信息。

如需更精细控制，可以传入一个对象来指定 mode 和要启用的追踪功能。

用法

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

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

了解更多关于 recording 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"
  
  追踪记录模式。
- attachments boolean (可选)
  
  是否包含测试附件。默认为 true。可选。
- screenshots boolean (可选)
  
  是否在追踪过程中捕获屏幕截图。屏幕截图用于构建时间线预览。默认为 true。可选。
- snapshots boolean (可选)
  
  是否在每个操作上捕获 DOM 快照。默认为 true。可选。
- sources boolean (可选)
  
  是否包含追踪操作的源文件。默认为 true。可选。

userAgent

Added in: v1.10

testOptions.userAgent

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

用法

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

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

类型

string

video

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