TestOptions

Playwright 测试提供了许多选项来配置测试环境，浏览器，浏览器上下文等等。

这些选项通常在配置文件中通过 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

切换绕过页面的内容安全策略。默认为 false。

用法

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

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

类型

boolean

channel

添加于：v1.10

testOptions.channel

浏览器分发渠道。支持的值为 "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'、'no-preference'。有关更多详细信息，请参见 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',
    },
  },
});

类型

对象<字符串, 字符串>

地理位置

添加于：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 数字
  
  纬度在 -90 到 90 之间。
- longitude 数字
  
  经度在 -180 到 180 之间。
- accuracy 数字 (可选)
  
  非负精度值。默认为 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 身份验证的凭据。如果未指定来源，则用户名和密码将在未经授权的响应时发送到任何服务器。

用法

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

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

类型

Object
- username 字符串
- password 字符串
- origin 字符串 (可选)
  
  限制在特定来源（scheme://host）上发送 http 凭据: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

是否在上下文中启用 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 请求标头值以及数字和日期格式规则。默认为系统默认区域设置。了解更多关于我们模拟指南中的模拟。

用法

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

类型

数组<字符串>

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 字符串
  
  将用于所有请求的代理。支持 HTTP 和 SOCKS 代理，例如 http://myproxy.com:3128 或 socks5://myproxy.com:3128。简短形式 myproxy.com:3128 被视为 HTTP 代理。
- bypass 字符串 (可选)
  
  要绕过代理的可选逗号分隔域，例如 ".com, chromium.org, .domain.com"。
- username 字符串 (可选)
  
  如果 HTTP 代理需要身份验证，则可以使用可选用户名。
- password 字符串 (可选)
  
  如果 HTTP 代理需要身份验证，则可以使用可选密码。

screenshot

添加于：v1.10

testOptions.screenshot

是否在每次测试后自动捕获屏幕截图。默认为 'off'。

'off': 不捕获屏幕截图。
'on': 在每次测试后捕获屏幕截图。
'only-on-failure': 在每次测试失败后捕获屏幕截图。

用法

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

export default defineConfig({
  use: {
    screenshot: 'only-on-failure',
  },
});

了解更多关于自动屏幕截图。

类型

对象 | "off" | "on" | "only-on-failure"
- mode "off" | "on" | "only-on-failure"
  
  自动屏幕截图模式。
- fullPage 布尔值 (可选)
  
  如果为 true，则截取整个可滚动页面的屏幕截图，而不是当前可见的视窗。默认为 false。
- omitBackground 布尔值 (可选)
  
  隐藏默认的白色背景，并允许捕获具有透明度的屏幕截图。不适用于 jpeg 图片。默认为 false。

serviceWorkers

添加于：v1.10

testOptions.serviceWorkers

是否允许网站注册服务工作者。默认为 'allow'。

'allow': 服务工作者可以注册。
'block': Playwright 将阻止所有服务工作者的注册。

用法

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

类型

字符串 | 对象
- cookies 数组<对象>
  - name 字符串
  - value 字符串
  - domain 字符串
    
    需要域和路径。为了使 cookie 也应用于所有子域，请在域前加点，例如：".example.com"
  - path 字符串
    
    需要域和路径
  - expires 数字
    
    以秒为单位的 Unix 时间。
  - httpOnly 布尔值
  - secure 布尔值
  - sameSite "Strict" | "Lax" | "None"
    
    sameSite 标志
  要为上下文设置的 Cookie
- origins 数组<对象>
  - origin string
  - localStorage 数组<对象>
    - name 字符串
    - value 字符串
  用于设置上下文环境的 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

是否为每个测试记录跟踪。默认为 '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'
  },
});

了解有关记录跟踪的更多信息。

类型

对象 | "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 布尔值 (可选)
  
  是否包含测试附件。默认为 true。可选。
- screenshots 布尔值 (可选)
  
  是否在跟踪期间捕获屏幕截图。屏幕截图用于构建时间线预览。默认为 true。可选。
- snapshots 布尔值 (可选)
  
  是否在每次操作时捕获 DOM 快照。默认为 true。可选。
- sources 布尔值 (可选)
  
  是否包含跟踪操作的源文件。默认为 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',
  },
});

了解有关记录视频的更多信息。

类型

对象 | "off" | "on" | "retain-on-failure" | "on-first-retry"
- mode "off" | "on" | "retain-on-failure" | "on-first-retry"
  
  视频记录模式。
- size 对象 (可选)
  - width 数字
  - height 数字
  录制视频的大小。可选。

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

类型

空 | 对象
- width 数字
  
  页面宽度（以像素为单位）。
- height 数字
  
  页面高度（以像素为单位）。

属性​

acceptDownloads​

actionTimeout​

baseURL​

browserName​

bypassCSP​

channel​

clientCertificates​

colorScheme​

connectOptions​

contextOptions​

deviceScaleFactor​

extraHTTPHeaders​

地理位置​

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

地理位置

hasTouch

headless

httpCredentials

ignoreHTTPSErrors

isMobile

javaScriptEnabled

launchOptions

locale

navigationTimeout

offline

permissions

proxy

screenshot

serviceWorkers

storageState

testIdAttribute

timezoneId

trace

userAgent

video

viewport