TestOptions

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

这些选项通常通过testConfig.use和testProject.use在配置文件中提供。

import { defineConfig } from '@playwright/test';
export default defineConfig({
  use: {
    headless: false,
    viewport: { width: 1280, height: 720 },
    ignoreHTTPSErrors: true,
    video: 'on-first-retry',
  },
});

或者，使用test.use()你可以为某个文件覆盖某些选项。

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​

是否自动下载所有附件。默认为true，表示接受所有下载。

用法

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

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

类型

• boolean

操作超时​

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​

在使用page.goto()、page.route()、page.waitForURL()、page.waitForRequest()或page.waitForResponse()时，会通过URL()构造函数考虑基础URL来构建相应的URL。默认情况下未设置。示例：

• baseURL: http://localhost:3000 and navigating to /bar.html results in http://localhost:3000/bar.html
• baseURL: http://localhost:3000/foo/ and navigating to ./bar.html results in http://localhost:3000/foo/bar.html
• baseURL: http://localhost:3000/foo (without trailing slash) and navigating to ./bar.html results in 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

浏览器名称​

运行测试的浏览器名称。默认为 'chromium'。大多数情况下您应该在 TestConfig 中设置 browserName：

用法

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

export default defineConfig({
  use: {
    browserName: 'firefox',
  },
});

类型

• "chromium" | "firefox" | "webkit"

绕过CSP​

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

用法

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

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

类型

• boolean

频道​

浏览器分发渠道。

使用"chromium"来选择加入新的无头模式。

使用"chrome"、"chrome-beta"、"chrome-dev"、"chrome-canary"、"msedge"、"msedge-beta"、"msedge-dev"或"msedge-canary"来使用品牌化的Google Chrome和Microsoft Edge。

用法

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

export default defineConfig({
  projects: [
    {
      name: 'Microsoft Edge',
      use: {
        ...devices['Desktop Edge'],
        channel: 'msedge'
      },
    },
  ]
});

类型

• string

客户端证书​

TLS客户端认证允许服务器请求客户端证书并进行验证。

用法

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

export default defineConfig({
  use: {
    clientCertificates: [{
      origin: 'https://example.com',
      certPath: './cert.pem',
      keyPath: './key.pem',
      passphrase: 'mysecretpassword',
    }],
  },
});

类型

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

colorScheme​

模拟prefers-colors-scheme媒体特性，支持的值为'light'和'dark'。详情请参阅page.emulateMedia()。传入null会将模拟重置为系统默认值。默认为'light'。

用法

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

export default defineConfig({
  use: {
    colorScheme: 'dark',
  },
});

类型

• null | "light" | "dark" | "no-preference"

connectOptions​

用法

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​

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

用法

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

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

类型

• 对象

deviceScaleFactor​

指定设备缩放比例（可视为dpr）。默认为1。了解更多关于使用设备缩放比例模拟设备的信息。

用法

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

export default defineConfig({
  use: {
    viewport: { width: 2560, height: 1440 },
    deviceScaleFactor: 2,
  },
});

类型

• number

extraHTTPHeaders​

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

用法

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

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

类型

• Object<string, string>

地理位置​

用法

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

export default defineConfig({
  use: {
    geolocation: { longitude: 12.492507, latitude: 41.889938 },
  },
});

了解更多关于geolocation的信息。

类型

• Object

  • latitude number

    纬度值，范围在-90到90之间。

  • longitude number

    经度值，范围在-180到180之间。

  • accuracy number (可选)

    非负精度值。默认为 0。

hasTouch​

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

用法

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

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

类型

• boolean

无头模式​

是否以无头模式运行浏览器。关于Chromium和Firefox的更多详情。默认为true，除非devtools选项设为true。

用法

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

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

类型

• boolean

httpCredentials​

HTTP认证的凭据。如果未指定来源，则在收到未经授权的响应时，用户名和密码将被发送到任何服务器。

用法

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

忽略HTTPS错误​

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

用法

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

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

类型

• boolean

isMobile​

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

用法

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

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

类型

• boolean

javaScriptEnabled​

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

用法

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

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

类型

• boolean

启动选项​

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

用法

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

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

类型

• 对象

语言环境​

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

用法

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

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

类型

• string

navigationTimeout​

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

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

用法

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

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

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

类型

• number

离线​

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

用法

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

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

类型

• boolean

权限​

授予此上下文中所有页面的权限列表。有关更多详细信息，请参阅browserContext.grantPermissions()。默认为无。

用法

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

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

类型

• Array<string>

代理​

网络代理设置。

用法

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代理需要认证时可选的密码。

截图​

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

• 'off': 不捕获屏幕截图。
• 'on': 在每个测试后捕获屏幕截图。
• 'only-on-failure': 仅在测试失败时捕获屏幕截图。
• 'on-first-failure': 在每次测试首次失败后捕获截图。

用法

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​

是否允许网站注册Service workers。默认为'allow'。

• 'allow': 可以注册Service Workers。
• 'block': Playwright 将阻止所有 Service Workers 的注册。

用法

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

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

类型

• "allow" | "block"

storageState​

了解更多关于storage state and auth的信息。

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

用法

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

export default defineConfig({
  use: {
    storageState: 'storage-state.json',
  },
});

类型

• 字符串 | Object
  • cookies 数组<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 to set for context
  • origins 数组<Object>

    • origin string

    • localStorage Array<Object>

      • name string

      • value string

      为上下文设置的localStorage

详情

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

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 }) => {
  // ...
});

testId属性​

用于page.getByTestId()的自定义属性。默认使用data-testid。

用法

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

export default defineConfig({
  use: {
    testIdAttribute: 'pw-test-id',
  },
});

时区ID​

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

用法

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

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

类型

• string

跟踪​

是否为每个测试记录跟踪。默认为 'off'。

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

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

用法

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​

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

用法

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

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

类型

• string

视频​

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

• 'off': 不录制视频。
• 'on': 为每个测试录制视频。
• 'retain-on-failure': 为每个测试录制视频，但会删除所有成功测试运行的视频。
• 'on-first-retry': 仅在首次重试测试时录制视频。

要控制视频尺寸，请传入一个包含mode和size属性的对象。如果未指定视频尺寸，它将等于testOptions.viewport按比例缩小以适应800x800的尺寸。如果未显式配置viewport，视频尺寸默认为800x450。每个页面的实际图像将根据需要按比例缩小以适应指定尺寸。

用法

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

    录制视频的大小。可选。

视口​

为每个页面模拟一致的视口。默认视口尺寸为1280x720。使用null可禁用一致的视口模拟。了解更多关于视口模拟的信息。

用法

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

export default defineConfig({
  use: {
    viewport: { width: 100, height: 100 },
  },
});

类型

• null | Object

  • width number

    页面宽度，单位为像素。

  • height number

    页面高度，单位为像素。