Interface PlaywrightWorkerOptions

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

Usage

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

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

Browser distribution channel.

Use "chromium" to opt in to new headless mode.

Use "chrome", "chrome-beta", "chrome-dev", "chrome-canary", "msedge", "msedge-beta", "msedge-dev", or "msedge-canary" to use branded Google Chrome and Microsoft Edge.

Usage

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

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

Usage

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

export default defineConfig({
  use: {
    connectOptions: {
      wsEndpoint: 'ws://localhost:5678',
    },
  },
});
Copy

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.

Whether to run browser in headless mode. More details for Chromium and Firefox. Defaults to true.

Usage

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

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

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

NOTE Use custom browser args at your own risk, as some of them may break Playwright functionality.

Usage

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

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

NOTE This option trades test isolation for speed and is intended for component tests that drive a story gallery. Leave it unset for end-to-end tests - a fresh browser context per test is one of the core guarantees of Playwright Test.

Experimental. When set to true, all tests in a worker process run in a single browser context that is reused between tests, instead of getting a brand new context per test. Defaults to false.

Between tests, Playwright resets the state that component tests typically touch: it clears cookies, cache, local storage and IndexedDB of visited origins, unregisters service workers, closes extra pages, removes routes, bindings and init scripts, and re-applies the configured storage state, viewport and emulation options.

This reset is best-effort, not a guarantee of isolation. State that is not reset includes:

• Permissions granted with browserContext.grantPermissions(permissions[, options]) during a test.
• Runtime changes made through browserContext.setGeolocation(geolocation), browserContext.setOffline(offline) and browserContext.setExtraHTTPHeaders(headers).
• Browsing history, window.name and any browser-process-wide state.

Additional restrictions:

• The option is ignored when testOptions.video recording is enabled.
• Only a few context options may differ between consecutive tests: colorScheme, forcedColors, reducedMotion, contrast, screen, userAgent, viewport and testIdAttribute. Changing any other option in test.use(options), for example locale or storageState, silently forces a fresh context and negates the speedup.
• Do not combine with testOptions.connectOptions pointing multiple workers at a shared browser - workers would compete for the single reusable context.
• recordHar in testOptions.contextOptions is not supported and produces no HAR file.

Usage

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

export default defineConfig({
  projects: [
    {
      name: 'components',
      testDir: './tests/components',
      use: { reuseContext: true },
    },
  ],
});
Copy

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.
• 'on-first-failure': Capture screenshot after each test's first failure.

Usage

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

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

Learn more about automatic screenshots.

Whether to record trace for each test. Defaults to 'off'. The initial run of a test is the "first run"; subsequent runs caused by retries are "retries".

• 'off': Do not record trace.
• 'on': Record and keep a trace for every run.
• 'on-first-retry': Record and keep a trace only for the first retry of a test.
• 'on-all-retries': Record and keep a trace for every retry.
• 'retain-on-failure': Record a trace for every run, but keep it only for runs that failed. A failed run's trace is kept even when a later retry passes.
• 'retain-on-first-failure': Record a trace only for the first run of a test (not for retries), and keep it only if that run failed.
• 'retain-on-failure-and-retries': Record a trace for every run, and keep it for any run that failed or that is a retry.

See trace modes for a side-by-side comparison of what each mode records and keeps.

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

Usage

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

export default defineConfig({
  use: {
    trace: 'on-first-retry'
  },
});
Copy

Learn more about recording trace.

Whether to record video for each test. Defaults to 'off'. The initial run of a test is the "first run"; subsequent runs caused by retries are "retries".

• 'off': Do not record video.
• 'on': Record and keep a video for every run.
• 'on-first-retry': Record and keep a video only for the first retry of a test.
• 'on-all-retries': Record and keep a video for every retry.
• 'retain-on-failure': Record a video for every run, but keep it only for runs that failed. A failed run's video is kept even when a later retry passes.
• 'retain-on-first-failure': Record a video only for the first run of a test (not for retries), and keep it only if that run failed.
• 'retain-on-failure-and-retries': Record a video for every run, and keep it for any run that failed or that is a retry.

See video modes for a side-by-side comparison of what each mode records and keeps.

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.

To annotate actions in the video, pass show with action and/or test sub-options. The action option controls visual highlights on interacted elements with an optional delay in milliseconds (defaults to 500). The test option controls which test information is displayed as a status overlay.

Usage

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

export default defineConfig({
  use: {
    video: 'on-first-retry',
  },
});
Copy

Learn more about recording video.