Optional buildPlaywright transpiler configuration.
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
build: {
external: ['**/*bundle.js'],
},
});
Optional external?: string[]Paths to exclude from the transpilation expressed as a list of glob patterns. Typically heavy JS bundles that your test uses are listed here.
Optional expectConfiguration for the expect assertion library. Learn more about various timeouts.
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
expect: {
timeout: 10000,
toMatchSnapshot: {
maxDiffPixels: 10,
},
},
});
Optional timeout?: numberDefault timeout for async expect matchers in milliseconds, defaults to 5000ms.
Optional toConfiguration for the expect(page).toHaveScreenshot(name[, options]) method.
Optional animations?: "disabled" | "allow"See animations in page.screenshot([options]).
Defaults to "disabled".
Optional caret?: "initial" | "hide"See caret in page.screenshot([options]). Defaults
to "hide".
Optional maxan acceptable ratio of pixels that are different to the total amount of pixels, between 0 and 1 , unset by
default.
Optional maxan acceptable amount of pixels that could be different, unset by default.
Optional scale?: "css" | "device"See scale in page.screenshot([options]). Defaults
to "css".
Optional styleSee style in page.screenshot([options]).
Optional threshold?: numberan acceptable perceived color difference between the same pixel in compared images, ranging from 0 (strict) and
1 (lax). "pixelmatch" comparator computes color difference in
YIQ color space and defaults threshold value to 0.2.
Optional toConfiguration for the expect(value).toMatchSnapshot(name[, options]) method.
Optional maxan acceptable ratio of pixels that are different to the total amount of pixels, between 0 and 1 , unset by
default.
Optional maxan acceptable amount of pixels that could be different, unset by default.
Optional threshold?: numberan acceptable perceived color difference between the same pixel in compared images, ranging from 0 (strict) and
1 (lax). "pixelmatch" comparator computes color difference in
YIQ color space and defaults threshold value to 0.2.
Optional toConfiguration for the expect(value).toPass() method.
Optional timeout?: numbertimeout for toPass method in milliseconds.
Optional forbidWhether to exit with an error if any tests or groups are marked as test.only(title[, details, body]) or test.describe.only([title, details, callback]). Useful on CI.
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
forbidOnly: !!process.env.CI,
});
Optional fullyPlaywright Test runs tests in parallel. In order to achieve that, it runs several worker processes that run at the same time. By default, test files are run in parallel. Tests in a single file are run in order, in the same worker process.
You can configure entire test run to concurrently execute all tests in all files using this option.
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
fullyParallel: true,
});
Optional globalPath to the global setup file. This file will be required and run before all the tests. It must export a single
function that takes a [TestConfig] argument.
Learn more about global setup and teardown.
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
globalSetup: './global-setup',
});
Optional globalPath to the global teardown file. This file will be required and run after all the tests. It must export a single function. See also testConfig.globalSetup.
Learn more about global setup and teardown.
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
globalTeardown: './global-teardown',
});
Optional globalMaximum time in milliseconds the whole test suite can run. Zero timeout (default) disables this behavior. Useful on CI to prevent broken setup from running too long and wasting resources. Learn more about various timeouts.
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
globalTimeout: process.env.CI ? 60 * 60 * 1000 : undefined,
});
Optional grepFilter to only run tests with a title matching one of the patterns. For example, passing grep: /cart/ should only
run tests with "cart" in the title. Also available in the command line with the -g option. The
regular expression will be tested against the string that consists of the test file name, test.describe name (if
any) and the test name divided by spaces, e.g. my-test.spec.ts my-suite my-test.
grep option is also useful for tagging tests.
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
grep: /smoke/,
});
Optional grepFilter to only run tests with a title not matching one of the patterns. This is the opposite of
testConfig.grep. Also available in the
command line with the --grep-invert option.
grepInvert option is also useful for tagging tests.
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
grepInvert: /manual/,
});
Optional ignoreWhether to skip snapshot expectations, such as expect(value).toMatchSnapshot() and await expect(page).toHaveScreenshot().
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
ignoreSnapshots: !process.env.CI,
});
Optional maxThe maximum number of test failures for the whole test suite run. After reaching this number, testing will stop and exit with an error. Setting to zero (default) disables this behavior.
Also available in the command line with the --max-failures and -x options.
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
maxFailures: process.env.CI ? 1 : 0,
});
Optional metadataMetadata that will be put directly to the test report serialized as JSON.
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
metadata: 'acceptance tests',
});
Optional nameConfig name is visible in the report and during test execution, unless overridden by testProject.name.
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
name: 'acceptance tests',
});
Optional outputThe output directory for files created during test execution. Defaults to <package.json-directory>/test-results.
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
outputDir: './test-results',
});
Details
This directory is cleaned at the start. When running a test, a unique subdirectory inside the testConfig.outputDir is created, guaranteeing that test running in parallel do not conflict. This directory can be accessed by testInfo.outputDir and testInfo.outputPath(...pathSegments).
Here is an example that uses testInfo.outputPath(...pathSegments) to create a temporary file.
import { test, expect } from '@playwright/test';
import fs from 'fs';
test('example test', async ({}, testInfo) => {
const file = testInfo.outputPath('temporary-file.txt');
await fs.promises.writeFile(file, 'Put some data to the file', 'utf8');
});
Optional preserveWhether to preserve test output in the
testConfig.outputDir. Defaults to
'always'.
'always' - preserve output for all tests;'never' - do not preserve output for any tests;'failures-only' - only preserve output for failed tests.Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
preserveOutput: 'always',
});
Optional projectsPlaywright Test supports running multiple test projects at the same time. See TestProject for more information.
Usage
// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
projects: [
{ name: 'chromium', use: devices['Desktop Chrome'] }
]
});
Optional quietWhether to suppress stdio and stderr output from the tests.
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
quiet: !!process.env.CI,
});
Optional repeatThe number of times to repeat each test, useful for debugging flaky tests.
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
repeatEach: 3,
});
Optional reportWhether to report slow test files. Pass null to disable this feature.
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
reportSlowTests: null,
});
Details
Test files that took more than threshold milliseconds are considered slow, and the slowest ones are reported, no
more than max number of them. Passing zero as max reports all test files that exceed the threshold.
The maximum number of slow test files to report. Defaults to 5.
Test duration in milliseconds that is considered slow. Defaults to 15 seconds.
Optional reporterThe list of reporters to use. Each reporter can be:
'list' or 'json'.'my-awesome-reporter'.'./reporters/my-awesome-reporter.js'.You can pass options to the reporter in a tuple like ['json', { outputFile: './report.json' }].
Learn more in the reporters guide.
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
reporter: 'line',
});
Optional retriesThe maximum number of retry attempts given to failed tests. By default failing tests are not retried. Learn more about test retries.
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
retries: 2,
});
Optional shardShard tests and execute only the selected shard. Specify in the one-based form like { total: 5, current: 2 }.
Learn more about parallelism and sharding with Playwright Test.
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
shard: { total: 10, current: 3 },
});
The index of the shard to execute, one-based.
The total number of shards.
Optional snapshotNOTE Use testConfig.snapshotPathTemplate to configure snapshot paths.
The base directory, relative to the config file, for snapshot files created with toMatchSnapshot. Defaults to
testConfig.testDir.
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
snapshotDir: './snapshots',
});
Details
The directory for each test can be accessed by testInfo.snapshotDir and testInfo.snapshotPath(...pathSegments).
This path will serve as the base directory for each test file snapshot directory. Setting snapshotDir to
'snapshots', the testInfo.snapshotDir
would resolve to snapshots/a.spec.js-snapshots.
Optional snapshotThis option configures a template controlling location of snapshots generated by expect(page).toHaveScreenshot(name[, options]) and expect(value).toMatchSnapshot(name[, options]).
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
testDir: './tests',
snapshotPathTemplate: '{testDir}/__screenshots__/{testFilePath}/{arg}{ext}',
});
Details
The value might include some "tokens" that will be replaced with actual values during test execution.
Consider the following file structure:
playwright.config.ts
tests/
└── page/
└── page-click.spec.ts
And the following page-click.spec.ts that uses toHaveScreenshot() call:
// page-click.spec.ts
import { test, expect } from '@playwright/test';
test.describe('suite', () => {
test('test should work', async ({ page }) => {
await expect(page).toHaveScreenshot(['foo', 'bar', 'baz.png']);
});
});
The list of supported tokens:
{testDir} - Project's
testConfig.testDir./home/playwright/tests (absolute path is since testDir is resolved relative to directory with
config){snapshotDir} - Project's
testConfig.snapshotDir./home/playwright/tests (since snapshotDir is not provided in config, it defaults to testDir){platform} - The value of process.platform.{projectName} - Project's file-system-sanitized name, if any.'' (empty string).{testFileDir} - Directories in relative path from testDir to test file.page{testFileName} - Test file name with extension.page-click.spec.ts{testFilePath} - Relative path from testDir to test filepage/page-click.spec.ts{testName} - File-system-sanitized test title, including parent describes but excluding file name.suite-test-should-work{arg} - Relative snapshot path without extension. These come from the arguments passed to the
toHaveScreenshot() and toMatchSnapshot() calls; if called without arguments, this will be an auto-generated
snapshot name.foo/bar/baz{ext} - snapshot extension (with dots).pngEach token can be preceded with a single character that will be used only if this token has non-empty value.
Consider the following config:
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
snapshotPathTemplate: '__screenshots__{/projectName}/{testFilePath}/{arg}{ext}',
testMatch: 'example.spec.ts',
projects: [
{ use: { browserName: 'firefox' } },
{ name: 'chromium', use: { browserName: 'chromium' } },
],
});
In this config:
<configDir>/__screenshots__/example.spec.ts/....<configDir>/__screenshots__/chromium/example.spec.ts/...snapshotPathTemplate resolves to relative path, it will be resolved relative to configDir."/" can be used as path separators on any platform.Optional testDirectory that will be recursively scanned for test files. Defaults to the directory of the configuration file.
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
testDir: './tests/playwright',
});
Optional testFiles matching one of these patterns are not executed as test files. Matching is performed against the absolute file path. Strings are treated as glob patterns.
For example, '**/test-assets/**' will ignore any files in the test-assets directory.
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
testIgnore: '**/test-assets/**',
});
Optional testOnly the files matching one of these patterns are executed as test files. Matching is performed against the absolute file path. Strings are treated as glob patterns.
By default, Playwright looks for files matching the following glob pattern: **/*.@(spec|test).?(c|m)[jt]s?(x).
This means JavaScript or TypeScript files with ".test" or ".spec" suffix, for example
login-screen.wrong-credentials.spec.ts.
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
testMatch: /.*\.e2e\.js/,
});
Optional timeoutTimeout for each test in milliseconds. Defaults to 30 seconds.
This is a base timeout for all tests. In addition, each test can configure its own timeout with test.setTimeout(timeout). Learn more about various timeouts.
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
timeout: 5 * 60 * 1000,
});
Optional updateWhether to update expected snapshots with the actual results produced by the test run. Defaults to 'missing'.
'all' - All tests that are executed will update snapshots that did not match. Matching snapshots will not be
updated.'none' - No snapshots are updated.'missing' - Missing snapshots are created, for example when authoring a new test and running it for the first
time. This is the default.Learn more about snapshots.
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
updateSnapshots: 'missing',
});
Optional useGlobal options for all tests, for example testOptions.browserName. Learn more about configuration and see [available options]TestOptions.
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
browserName: 'chromium',
},
});
Optional webLaunch a development web server (or multiple) during the tests.
Details
If the port is specified, Playwright Test will wait for it to be available on 127.0.0.1 or ::1, before running
the tests. If the url is specified, Playwright Test will wait for the URL to return a 2xx, 3xx, 400, 401, 402, or
403 status code before running the tests.
For continuous integration, you may want to use the reuseExistingServer: !process.env.CI option which does not
use an existing server on the CI. To see the stdout, you can set the DEBUG=pw:webserver environment variable.
The port (but not the url) gets passed over to Playwright as a
testOptions.baseURL. For example port
8080 produces baseURL equal http://localhost:8080. If webServer is specified as an array, you must
explicitly configure the baseURL (even if it only has one entry).
NOTE It is also recommended to specify testOptions.baseURL in the config, so that tests could use relative urls.
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
webServer: {
command: 'npm run start',
url: 'http://127.0.0.1:3000',
timeout: 120 * 1000,
reuseExistingServer: !process.env.CI,
},
use: {
baseURL: 'http://localhost:3000/',
},
});
Now you can use a relative path when navigating the page:
// test.spec.ts
import { test } from '@playwright/test';
test('test', async ({ page }) => {
// This will result in http://localhost:3000/foo
await page.goto('/foo');
});
Multiple web servers (or background processes) can be launched:
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
webServer: [
{
command: 'npm run start',
url: 'http://127.0.0.1:3000',
timeout: 120 * 1000,
reuseExistingServer: !process.env.CI,
},
{
command: 'npm run backend',
url: 'http://127.0.0.1:3333',
timeout: 120 * 1000,
reuseExistingServer: !process.env.CI,
}
],
use: {
baseURL: 'http://127.0.0.1:3000',
},
});
Optional workersThe maximum number of concurrent worker processes to use for parallelizing tests. Can also be set as percentage of
logical CPU cores, e.g. '50%'.
Playwright Test uses worker processes to run tests. There is always at least one worker process, but more can be used to speed up test execution.
Defaults to half of the number of logical CPU cores. Learn more about parallelism and sharding with Playwright Test.
Usage
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
workers: 3,
});
Generated using TypeDoc
Playwright Test provides many options to configure how your tests are collected and executed, for example
timeoutortestDir. These options are described in the TestConfig object in the configuration file.Playwright Test supports running multiple test projects at the same time. Project-specific options should be put to testConfig.projects, but top-level TestConfig can also define base options shared between all projects.