Skip to main content
Version: 1.15

TestOptions

Playwright Test provides many options to configure test environment, Browser, BrowserContext and more.

These options are usually provided in the configuration file through testConfig.use and testProject.use.

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

Alternatively, with test.use(options) you can override some options for a file.

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

testOptions.acceptDownloads#

Whether to automatically download all the attachments. Defaults to false where all the downloads are canceled.

testOptions.actionTimeout#

Default timeout for each Playwright action in milliseconds, defaults to 0 (no timeout).

This is a default timeout for all Playwright actions, same as configured via page.setDefaultTimeout(timeout).

testOptions.baseURL#

When using page.goto(url[, options]), page.route(url, handler[, options]), page.waitForURL(url[, options]), page.waitForRequest(urlOrPredicate[, options]), or page.waitForResponse(urlOrPredicate[, options]) it takes the base URL in consideration by using the URL() constructor for building the corresponding URL. Examples:

  • 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

testOptions.browserName#

  • type: <"chromium"|"firefox"|"webkit">

Name of the browser that runs tests. Defaults to 'chromium'. Most of the time you should set browserName in your TestConfig:

// playwright.config.tsimport { PlaywrightTestConfig, devices } from '@playwright/test';
const config: PlaywrightTestConfig = {  use: {    browserName: 'firefox',  },};export default config;

testOptions.bypassCSP#

Toggles bypassing page's Content-Security-Policy.

testOptions.channel#

Browser distribution channel. Supported values are "chrome", "chrome-beta", "chrome-dev", "chrome-canary", "msedge", "msedge-beta", "msedge-dev", "msedge-canary". Read more about using Google Chrome and Microsoft Edge.

testOptions.colorScheme#

  • type: <"light"|"dark"|"no-preference">

Emulates 'prefers-colors-scheme' media feature, supported values are 'light', 'dark', 'no-preference'. See page.emulateMedia([options]) for more details. Defaults to 'light'.

testOptions.contextOptions#

Options used to create the context, as passed to browser.newContext([options]). Specific options like testOptions.viewport take priority over this.

testOptions.deviceScaleFactor#

Specify device scale factor (can be thought of as dpr). Defaults to 1.

testOptions.extraHTTPHeaders#

An object containing additional HTTP headers to be sent with every request. All header values must be strings.

testOptions.geolocation#

  • type: <Object>
    • latitude <number> Latitude between -90 and 90.
    • longitude <number> Longitude between -180 and 180.
    • accuracy <number> Non-negative accuracy value. Defaults to 0.

testOptions.hasTouch#

Specifies if viewport supports touch events. Defaults to false.

testOptions.headless#

Whether to run browser in headless mode. More details for Chromium and Firefox. Defaults to true unless the devtools option is true.

testOptions.httpCredentials#

Credentials for HTTP authentication.

testOptions.ignoreHTTPSErrors#

Whether to ignore HTTPS errors during navigation. Defaults to false.

testOptions.isMobile#

Whether the meta viewport tag is taken into account and touch events are enabled. Defaults to false. Not supported in Firefox.

testOptions.javaScriptEnabled#

Whether or not to enable JavaScript in the context. Defaults to true.

testOptions.launchOptions#

Options used to launch the browser, as passed to browserType.launch([options]). Specific options testOptions.headless and testOptions.channel take priority over this.

testOptions.locale#

Specify user locale, for example en-GB, de-DE, etc. Locale will affect navigator.language value, Accept-Language request header value as well as number and date formatting rules.

testOptions.navigationTimeout#

Timeout for each navigation action in milliseconds. Defaults to 0 (no timeout).

This is a default navigation timeout, same as configured via page.setDefaultNavigationTimeout(timeout).

testOptions.offline#

Whether to emulate network being offline. Defaults to false.

testOptions.permissions#

A list of permissions to grant to all pages in this context. See browserContext.grantPermissions(permissions[, options]) for more details.

testOptions.proxy#

  • type: <Object>
    • server <string> Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example http://myproxy.com:3128 or socks5://myproxy.com:3128. Short form myproxy.com:3128 is considered an HTTP proxy.
    • bypass <string> Optional coma-separated domains to bypass proxy, for example ".com, chromium.org, .domain.com".
    • username <string> Optional username to use if HTTP proxy requires authentication.
    • password <string> Optional password to use if HTTP proxy requires authentication.

Network proxy settings.

testOptions.screenshot#

  • type: <"off"|"on"|"only-on-failure">

Whether to automatically capture a screenshot after each test. Defaults to 'off'.

  • 'off': Do not capture screenshots.
  • 'on': Capture screenshot after each test.
  • 'only-on-failure': Capture screenshot after each test failure.

Learn more about automatic screenshots.

testOptions.storageState#

  • type: <string|Object>
    • cookies <Array<Object>> Optional cookies to set for context
      • name <string>
      • value <string>
      • url <string> Optional either url or domain / path are required
      • domain <string> Optional either url or domain / path are required
      • path <string> Optional either url or domain / path are required
      • expires <number> Optional Unix time in seconds.
      • httpOnly <boolean> Optional httpOnly flag
      • secure <boolean> Optional secure flag
      • sameSite <"Strict"|"Lax"|"None"> Optional sameSite flag
    • origins <Array<Object>> Optional localStorage to set for context

Populates context with given storage state. This option can be used to initialize context with logged-in information obtained via browserContext.storageState([options]). Either a path to the file with saved storage, or an object with the following fields:

testOptions.timezoneId#

Changes the timezone of the context. See ICU's metaZones.txt for a list of supported timezone IDs.

testOptions.trace#

  • type: <"off"|"on"|"retain-on-failure"|"on-first-retry">

Whether to record a trace for each test. Defaults to 'off'.

  • 'off': Do not record a trace.
  • 'on': Record a trace for each test.
  • 'retain-on-failure': Record a trace for each test, but remove it from successful test runs.
  • 'on-first-retry': Record a trace only when retrying a test for the first time.

Learn more about recording trace.

testOptions.userAgent#

Specific user agent to use in this context.

testOptions.video#

  • type: <Object|"off"|"on"|"retain-on-failure"|"on-first-retry">
    • mode <"off"|"on"|"retain-on-failure"|"on-first-retry"> Video recording mode.
    • size <Object> Size of the recorded video.

Whether to record video for each test. Defaults to 'off'.

  • 'off': Do not record video.
  • 'on': Record video for each test.
  • 'retain-on-failure': Record video for each test, but remove all videos from successful test runs.
  • 'on-first-retry': Record video only when retrying a test for the first time.

Learn more about recording video.

testOptions.viewport#

Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. null disables the default viewport.