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() 构造函数来构建相应的 URL。默认未设置。示例

baseURL: https://127.0.0.1:3000 和导航到 /bar.html 会得到 https://127.0.0.1:3000/bar.html
baseURL: https://127.0.0.1:3000/foo/ 和导航到 ./bar.html 会得到 https://127.0.0.1:3000/foo/bar.html
baseURL: https://127.0.0.1:3000/foo (没有尾部斜杠) 和导航到 ./bar.html 会得到 https://127.0.0.1:3000/bar.html

用法

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

export default defineConfig({
  use: {
    /* Base URL to use in actions like `await page.goto('/')`. */
    baseURL: 'https://127.0.0.1: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

切换绕过页面的内容安全策略 (CSP)。默认为 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://127.0.0.1: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

用于创建上下文的选项，与传递给 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。除非 devtools 选项为 true，否则默认为 true。

用法

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

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

类型

boolean

httpCredentials

添加于: v1.10

testOptions.httpCredentials

HTTP 身份验证的凭据。如果未指定来源，则用户名和密码将发送到任何服务器以响应未经授权的请求。

用法

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' - Authorization 标头将随每个 API 请求一起发送，其中包含基本身份验证凭据。 '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

是否在上下文中启用 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 等。区域设置将影响 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

要授予此上下文中所有页面的权限列表。有关更多详细信息，请参阅 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 Worker。默认为 'allow'。

'allow': 可以注册 Service Worker。
'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

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

使用给定的存储状态填充上下文。此选项可用于使用通过 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 标志
  要为上下文设置的 Cookie
- origins Array<Object>
  - origin string
  - localStorage Array<Object>
    - name string
    - value string
    要为上下文设置的 localStorage

详情

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

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

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

用法

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 (可选)
  
  是否在 tracing 期间捕获屏幕截图。屏幕截图用于构建时间线预览。默认为 true。可选。
- snapshots boolean (可选)
  
  是否在每次操作时捕获 DOM 快照。默认为 true。可选。
- sources boolean (可选)
  
  是否包含 trace 操作的源文件。默认为 true。可选。

userAgent

添加于: v1.10

testOptions.userAgent

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

用法

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