TestOptions

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

这些选项通常通过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,
  },
});

类型

布尔值

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: https://:3000，导航到 /bar.html 会得到 https://:3000/bar.html
baseURL: https://:3000/foo/，导航到 ./bar.html 会得到 https://:3000/foo/bar.html
baseURL: https://:3000/foo (不带尾部斜杠)，导航到 ./bar.html，结果为 https://: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://:3000',
  },
});

类型

字符串

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

类型

布尔值

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

类型

字符串

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

类型

数组<对象>
- 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属性应提供与证书有效请求来源完全匹配的值。

只有在至少提供一个客户端证书时，客户端证书认证才有效。如果您想拒绝服务器发送的所有客户端证书，您需要提供一个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://:5678',
    },
  },
});

当指定连接选项时，默认的fixtures.browser、fixtures.context和fixtures.page使用远程浏览器而不是本地启动浏览器，并且任何启动选项，如testOptions.headless或testOptions.channel都将被忽略。

类型

void | Object
- wsEndpoint 字符串
  
  要连接的浏览器 websocket 端点。
- headers void | Object<字符串, 字符串> （可选）
  
  要随 WebSocket 连接请求发送的额外 HTTP 头。可选。
- timeout 数字 (可选)
  
  建立连接的超时时间（毫秒）。可选，默认为无超时。
- exposeNetwork 字符串 （可选）
  
  将连接客户端上可用的网络暴露给被连接的浏览器的选项。有关更多详细信息，请参阅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
  },
});

类型

布尔值

headless

新增于: v1.10

testOptions.headless

是否在无头模式下运行浏览器。有关Chromium和Firefox的更多详细信息。默认为true，除非devtools选项为true。

用法

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

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

类型

布尔值

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）上发送 http 凭据).
- 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,
  },
});

类型

布尔值

isMobile

新增于: v1.10

testOptions.isMobile

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

用法

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

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

类型

布尔值

javaScriptEnabled

新增于: v1.10

testOptions.javaScriptEnabled

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

用法

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

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

类型

布尔值

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

类型

字符串

新增于: 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
  },
});

类型

布尔值

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 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 Workers 的注册。

用法

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

export default defineConfig({
  use: {
    serviceWorkers: 'allow'
  },
});

类型

"允许" | "阻止"

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

类型

字符串

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

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

类型

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

新增于: v1.10

testOptions.userAgent

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

用法

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

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

类型

字符串

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