TestConfig
Playwright Test provides many options to configure how your tests are collected and executed, for example timeout
or testDir
. These options are described in the TestConfig object in the configuration file. This type describes format of the configuration file, to access resolved configuration parameters at run time use FullConfig.
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.
import { defineConfig } from '@playwright/test';
export default defineConfig({
timeout: 30000,
globalTimeout: 600000,
reporter: 'list',
testDir: './tests',
});
Properties
build
Added in: v1.35Playwright transpiler configuration.
Usage
import { defineConfig } from '@playwright/test';
export default defineConfig({
build: {
external: ['**/*bundle.js'],
},
});
Type
expect
Added in: v1.10Configuration for the expect
assertion library. Learn more about various timeouts.
Usage
import { defineConfig } from '@playwright/test';
export default defineConfig({
expect: {
timeout: 10000,
toMatchSnapshot: {
maxDiffPixels: 10,
},
},
});
Type
- Object
-
timeout
number (optional)Default timeout for async expect matchers in milliseconds, defaults to 5000ms.
-
toHaveScreenshot
Object (optional)-
animations
"allow" | "disabled" (optional)See animations in page.screenshot(). Defaults to
"disabled"
. -
caret
"hide" | "initial" (optional)See caret in page.screenshot(). Defaults to
"hide"
. -
maxDiffPixels
number (optional)An acceptable amount of pixels that could be different, unset by default.
-
maxDiffPixelRatio
number (optional)An acceptable ratio of pixels that are different to the total amount of pixels, between
0
and1
, unset by default. -
scale
"css" | "device" (optional)See scale in page.screenshot(). Defaults to
"css"
. -
stylePath
string | Array<string> (optional)See style in page.screenshot().
-
threshold
number (optional)An acceptable perceived color difference between the same pixel in compared images, ranging from
0
(strict) and1
(lax)."pixelmatch"
comparator computes color difference in YIQ color space and defaultsthreshold
value to0.2
.
Configuration for the expect(page).toHaveScreenshot() method.
-
-
toMatchSnapshot
Object (optional)-
maxDiffPixels
number (optional)An acceptable amount of pixels that could be different, unset by default.
-
maxDiffPixelRatio
number (optional)An acceptable ratio of pixels that are different to the total amount of pixels, between
0
and1
, unset by default. -
threshold
number (optional)An acceptable perceived color difference between the same pixel in compared images, ranging from
0
(strict) and1
(lax)."pixelmatch"
comparator computes color difference in YIQ color space and defaultsthreshold
value to0.2
.
Configuration for the expect(value).toMatchSnapshot() method.
-
-
toPass
Object (optional)-
intervals
Array<number> (optional)Probe intervals for toPass method in milliseconds.
-
timeout
number (optional)Timeout for toPass method in milliseconds.
Configuration for the expect(value).toPass() method.
-
-
forbidOnly
Added in: v1.10Whether to exit with an error if any tests or groups are marked as test.only() or test.describe.only(). Useful on CI.
Usage
import { defineConfig } from '@playwright/test';
export default defineConfig({
forbidOnly: !!process.env.CI,
});
Type
fullyParallel
Added in: v1.20Playwright 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
import { defineConfig } from '@playwright/test';
export default defineConfig({
fullyParallel: true,
});
Type
globalSetup
Added in: v1.10Path 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 FullConfig argument.
Learn more about global setup and teardown.
Usage
import { defineConfig } from '@playwright/test';
export default defineConfig({
globalSetup: './global-setup',
});
Type
globalTeardown
Added in: v1.10Path 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
import { defineConfig } from '@playwright/test';
export default defineConfig({
globalTeardown: './global-teardown',
});
Type
globalTimeout
Added in: v1.10Maximum 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
import { defineConfig } from '@playwright/test';
export default defineConfig({
globalTimeout: process.env.CI ? 60 * 60 * 1000 : undefined,
});
Type
grep
Added in: v1.10Filter 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 project name, the test file name, the test.describe
name (if any), the test name and the test tags divided by spaces, e.g. chromium my-test.spec.ts my-suite my-test
.
grep
option is also useful for tagging tests.
Usage
import { defineConfig } from '@playwright/test';
export default defineConfig({
grep: /smoke/,
});
Type
grepInvert
Added in: v1.10Filter 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
import { defineConfig } from '@playwright/test';
export default defineConfig({
grepInvert: /manual/,
});
Type
ignoreSnapshots
Added in: v1.26Whether to skip snapshot expectations, such as expect(value).toMatchSnapshot()
and await expect(page).toHaveScreenshot()
.
Usage
import { defineConfig } from '@playwright/test';
export default defineConfig({
ignoreSnapshots: !process.env.CI,
});
Type
maxFailures
Added in: v1.10The 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
import { defineConfig } from '@playwright/test';
export default defineConfig({
maxFailures: process.env.CI ? 1 : 0,
});
Type
metadata
Added in: v1.10Metadata that will be put directly to the test report serialized as JSON.
Usage
import { defineConfig } from '@playwright/test';
export default defineConfig({
metadata: 'acceptance tests',
});
Type
name
Added in: v1.10Config name is visible in the report and during test execution, unless overridden by testProject.name.
Usage
import { defineConfig } from '@playwright/test';
export default defineConfig({
name: 'acceptance tests',
});
Type
outputDir
Added in: v1.10The output directory for files created during test execution. Defaults to <package.json-directory>/test-results
.
Usage
import { defineConfig } from '@playwright/test';
export default defineConfig({
outputDir: './test-results',
});
Type
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().
Here is an example that uses testInfo.outputPath() 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');
});
preserveOutput
Added in: v1.10Whether 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
import { defineConfig } from '@playwright/test';
export default defineConfig({
preserveOutput: 'always',
});
Type
- "always" | "never" | "failures-only"
projects
Added in: v1.10Playwright Test supports running multiple test projects at the same time. See TestProject for more information.
Usage
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
projects: [
{ name: 'chromium', use: devices['Desktop Chrome'] }
]
});
Type
quiet
Added in: v1.10Whether to suppress stdio and stderr output from the tests.
Usage
import { defineConfig } from '@playwright/test';
export default defineConfig({
quiet: !!process.env.CI,
});
Type
repeatEach
Added in: v1.10The number of times to repeat each test, useful for debugging flaky tests.
Usage
import { defineConfig } from '@playwright/test';
export default defineConfig({
repeatEach: 3,
});
Type
reportSlowTests
Added in: v1.10Whether to report slow test files. Pass null
to disable this feature.
Usage
import { defineConfig } from '@playwright/test';
export default defineConfig({
reportSlowTests: null,
});
Type
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.
reporter
Added in: v1.10The list of reporters to use. Each reporter can be:
- A builtin reporter name like
'list'
or'json'
. - A module name like
'my-awesome-reporter'
. - A relative path to the reporter like
'./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
import { defineConfig } from '@playwright/test';
export default defineConfig({
reporter: 'line',
});
Type
respectGitIgnore
Added in: v1.45Whether to skip entries from .gitignore
when searching for test files. By default, if neither testConfig.testDir nor testProject.testDir are explicitly specified, Playwright will ignore any test files matching .gitignore
entries.
Usage
testConfig.respectGitIgnore
Type
retries
Added in: v1.10The maximum number of retry attempts given to failed tests. By default failing tests are not retried. Learn more about test retries.
Usage
import { defineConfig } from '@playwright/test';
export default defineConfig({
retries: 2,
});
Type
shard
Added in: v1.10Shard 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
import { defineConfig } from '@playwright/test';
export default defineConfig({
shard: { total: 10, current: 3 },
});
Type
snapshotPathTemplate
Added in: v1.28This option configures a template controlling location of snapshots generated by expect(page).toHaveScreenshot() and expect(value).toMatchSnapshot().
Usage
import { defineConfig } from '@playwright/test';
export default defineConfig({
testDir: './tests',
snapshotPathTemplate: '{testDir}/__screenshots__/{testFilePath}/{arg}{ext}',
});
Type
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:
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:
{arg}
- Relative snapshot path without extension. These come from the arguments passed to thetoHaveScreenshot()
andtoMatchSnapshot()
calls; if called without arguments, this will be an auto-generated snapshot name.- Value:
foo/bar/baz
- Value:
{ext}
- snapshot extension (with dots)- Value:
.png
- Value:
{platform}
- The value ofprocess.platform
.{projectName}
- Project's file-system-sanitized name, if any.- Value:
''
(empty string).
- Value:
{snapshotDir}
- Project's testConfig.snapshotDir.- Value:
/home/playwright/tests
(sincesnapshotDir
is not provided in config, it defaults totestDir
)
- Value:
{testDir}
- Project's testConfig.testDir.- Value:
/home/playwright/tests
(absolute path is sincetestDir
is resolved relative to directory with config)
- Value:
{testFileDir}
- Directories in relative path fromtestDir
to test file.- Value:
page
- Value:
{testFileName}
- Test file name with extension.- Value:
page-click.spec.ts
- Value:
{testFilePath}
- Relative path fromtestDir
to test file- Value:
page/page-click.spec.ts
- Value:
{testName}
- File-system-sanitized test title, including parent describes but excluding file name.- Value:
suite-test-should-work
- Value:
Each token can be preceded with a single character that will be used only if this token has non-empty value.
Consider the following config:
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:
- First project does not have a name, so its snapshots will be stored in
<configDir>/__screenshots__/example.spec.ts/...
. - Second project does have a name, so its snapshots will be stored in
<configDir>/__screenshots__/chromium/example.spec.ts/..
. - Since
snapshotPathTemplate
resolves to relative path, it will be resolved relative toconfigDir
. - Forward slashes
"/"
can be used as path separators on any platform.
testDir
Added in: v1.10Directory that will be recursively scanned for test files. Defaults to the directory of the configuration file.
Usage
import { defineConfig } from '@playwright/test';
export default defineConfig({
testDir: './tests/playwright',
});
Type
testIgnore
Added in: v1.10Files 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
import { defineConfig } from '@playwright/test';
export default defineConfig({
testIgnore: '**/test-assets/**',
});
Type
testMatch
Added in: v1.10Only 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
import { defineConfig } from '@playwright/test';
export default defineConfig({
testMatch: /.*\.e2e\.js/,
});
Type
timeout
Added in: v1.10Timeout 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(). Learn more about various timeouts.
Usage
import { defineConfig } from '@playwright/test';
export default defineConfig({
timeout: 5 * 60 * 1000,
});
Type
updateSnapshots
Added in: v1.10Whether 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
import { defineConfig } from '@playwright/test';
export default defineConfig({
updateSnapshots: 'missing',
});
Type
- "all" | "none" | "missing"
use
Added in: v1.10Global options for all tests, for example testOptions.browserName. Learn more about configuration and see available options.
Usage
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
browserName: 'chromium',
},
});
Type
webServer
Added in: v1.10Launch a development web server (or multiple) during the tests.
Usage
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:
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:
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',
},
});
Type
- Object | Array<Object>
-
command
stringShell command to start. For example
npm run start
.. -
cwd
string (optional)Current working directory of the spawned process, defaults to the directory of the configuration file.
-
env
Object<string, string> (optional)Environment variables to set for the command,
process.env
by default. -
ignoreHTTPSErrors
boolean (optional)Whether to ignore HTTPS errors when fetching the
url
. Defaults tofalse
. -
port
number (optional)The port that your http server is expected to appear on. It does wait until it accepts connections. Either
port
orurl
should be specified. -
reuseExistingServer
boolean (optional)If true, it will re-use an existing server on the
port
orurl
when available. If no server is running on thatport
orurl
, it will run the command to start a new server. Iffalse
, it will throw if an existing process is listening on theport
orurl
. This should be commonly set to!process.env.CI
to allow the local dev server when running tests locally. -
stdout
"pipe" | "ignore" (optional)If
"pipe"
, it will pipe the stdout of the command to the process stdout. If"ignore"
, it will ignore the stdout of the command. Default to"ignore"
. -
stderr
"pipe" | "ignore" (optional)Whether to pipe the stderr of the command to the process stderr or ignore it. Defaults to
"pipe"
. -
timeout
number (optional)How long to wait for the process to start up and be available in milliseconds. Defaults to 60000.
-
url
string (optional)The url on your http server that is expected to return a 2xx, 3xx, 400, 401, 402, or 403 status code when the server is ready to accept connections. Redirects (3xx status codes) are being followed and the new location is checked. Either
port
orurl
should be specified.
-
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).
It is also recommended to specify testOptions.baseURL in the config, so that tests could use relative urls.
workers
Added in: v1.10The 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
import { defineConfig } from '@playwright/test';
export default defineConfig({
workers: 3,
});
Type
Deprecated
snapshotDir
Added in: v1.10Use 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
import { defineConfig } from '@playwright/test';
export default defineConfig({
snapshotDir: './snapshots',
});
Type
Details
The directory for each test can be accessed by testInfo.snapshotDir and testInfo.snapshotPath().
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
.