Skip to main content

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

testOptions.acceptDownloads​

Added in: v1.10

Whether to automatically download all the attachments. Defaults to true where all the downloads are accepted.

testOptions.actionTimeout​

Added in: v1.10

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).

Learn more about various timeouts.

testOptions.baseURL​

Added in: v1.10

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

testOptions.browserName​

Added in: v1.10
  • 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.ts
import { type PlaywrightTestConfig, devices } from '@playwright/test';

const config: PlaywrightTestConfig = {
  use: {
    browserName: 'firefox',
  },
};
export default config;

testOptions.bypassCSP​

Added in: v1.10

Toggles bypassing page's Content-Security-Policy.

testOptions.channel​

Added in: v1.10

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​

Added in: v1.10
  • 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.connectOptions​

Added in: v1.10
  • type: <void|Object>
    • wsEndpoint <string> A browser websocket endpoint to connect to.
    • headers? <void|Object<string, string>> Additional HTTP headers to be sent with web socket connect request. Optional.
    • timeout? <number> Timeout in milliseconds for the connection to be established. Optional, defaults to no timeout.

When connect options are specified, default fixtures.browser, fixtures.context and fixtures.page use the remote browser instead of launching a browser locally, and any launch options like testOptions.headless or testOptions.channel are ignored.

testOptions.contextOptions​

Added in: v1.10

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

testOptions.deviceScaleFactor​

Added in: v1.10

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

testOptions.extraHTTPHeaders​

Added in: v1.10

An object containing additional HTTP headers to be sent with every request.

testOptions.geolocation​

Added in: v1.10
  • 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​

Added in: v1.10

Specifies if viewport supports touch events. Defaults to false.

testOptions.headless​

Added in: v1.10

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

testOptions.httpCredentials​

Added in: v1.10

Credentials for HTTP authentication.

testOptions.ignoreHTTPSErrors​

Added in: v1.10

Whether to ignore HTTPS errors when sending network requests. Defaults to false.

testOptions.isMobile​

Added in: v1.10

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

testOptions.javaScriptEnabled​

Added in: v1.10

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

testOptions.launchOptions​

Added in: v1.10

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​

Added in: v1.10

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​

Added in: v1.10

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).

Learn more about various timeouts.

testOptions.offline​

Added in: v1.10

Whether to emulate network being offline. Defaults to false.

testOptions.permissions​

Added in: v1.10

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

testOptions.proxy​

Added in: v1.10
  • 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 comma-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​

Added in: v1.10
  • 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.serviceWorkers​

Added in: v1.10
  • type: <"allow"|"block">

Whether to allow sites to register Service workers. Defaults to 'allow'.

  • 'allow': Service Workers can be registered.
  • 'block': Playwright will block all registration of Service Workers.

testOptions.storageState​

Added in: v1.10

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.testIdAttribute​

Added in: v1.27

Custom attribute to be used in page.getByTestId(testId). data-testid is used by default.

testOptions.timezoneId​

Added in: v1.10

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

testOptions.trace​

Added in: v1.10
  • type: <Object|"off"|"on"|"retain-on-failure"|"on-first-retry">
    • mode <"off"|"on"|"retain-on-failure"|"on-first-retry"> Trace recording mode.
    • screenshots? <boolean> Whether to capture screenshots during tracing. Screenshots are used to build a timeline preview. Defaults to true. Optional.
    • snapshots? <boolean> Whether to capture DOM snapshot on every action. Defaults to true. Optional.
    • sources? <boolean> Whether to include source files for trace actions. Defaults to true. Optional.

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

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

For more control, pass an object that specifies mode and trace features to enable.

Learn more about recording trace.

testOptions.userAgent​

Added in: v1.10

Specific user agent to use in this context.

testOptions.video​

Added in: v1.10
  • 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. Optional.

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.

To control video size, pass an object with mode and size properties. If video size is not specified, it will be equal to testOptions.viewport scaled down to fit into 800x800. If viewport is not configured explicitly the video size defaults to 800x450. Actual picture of each page will be scaled down if necessary to fit the specified size.

Learn more about recording video.

testOptions.viewport​

Added in: v1.10

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