playwright
Version:
A high-level API to automate web browsers
1,427 lines (1,342 loc) • 369 kB
TypeScript
// This file is generated by /utils/generate_types/index.js
/**
* Copyright (c) Microsoft Corporation.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import type { APIRequestContext, Browser, BrowserContext, BrowserContextOptions, Page, LaunchOptions, ViewportSize, Geolocation, HTTPCredentials, Locator, APIResponse, PageScreenshotOptions } from 'playwright-core';
export * from 'playwright-core';
export type BlobReporterOptions = { outputDir?: string, fileName?: string };
export type ListReporterOptions = { printSteps?: boolean };
export type JUnitReporterOptions = { outputFile?: string, stripANSIControlSequences?: boolean, includeProjectInTestName?: boolean, includeRetries?: boolean };
export type JsonReporterOptions = { outputFile?: string };
export type HtmlReporterOptions = {
outputFolder?: string;
open?: 'always' | 'never' | 'on-failure';
host?: string;
port?: number;
attachmentsBaseURL?: string;
title?: string;
noSnippets?: boolean;
noCopyPrompt?: boolean;
doNotInlineAssets?: boolean;
};
export type ReporterDescription = Readonly<
['blob'] | ['blob', BlobReporterOptions] |
['dot'] |
['line'] |
['list'] | ['list', ListReporterOptions] |
['github'] |
['junit'] | ['junit', JUnitReporterOptions] |
['json'] | ['json', JsonReporterOptions] |
['html'] | ['html', HtmlReporterOptions] |
['null'] |
[string] | [string, any]
>;
type UseOptions<TestArgs, WorkerArgs> = Partial<WorkerArgs> & Partial<TestArgs>;
/**
* Playwright Test supports running multiple test projects at the same time. This is useful for running tests in
* multiple configurations. For example, consider running tests against multiple browsers. This type describes format
* of a project in the configuration file, to access resolved configuration parameters at run time use
* [FullProject](https://playwright.dev/docs/api/class-fullproject).
*
* `TestProject` encapsulates configuration specific to a single project. Projects are configured in
* [testConfig.projects](https://playwright.dev/docs/api/class-testconfig#test-config-projects) specified in the
* [configuration file](https://playwright.dev/docs/test-configuration). Note that all properties of
* [TestProject](https://playwright.dev/docs/api/class-testproject) are available in the top-level
* [TestConfig](https://playwright.dev/docs/api/class-testconfig), in which case they are shared between all projects.
*
* Here is an example configuration that runs every test in Chromium, Firefox and WebKit, both Desktop and Mobile
* versions.
*
* ```js
* // playwright.config.ts
* import { defineConfig, devices } from '@playwright/test';
*
* export default defineConfig({
* // Options shared for all projects.
* timeout: 30000,
* use: {
* ignoreHTTPSErrors: true,
* },
*
* // Options specific to each project.
* projects: [
* {
* name: 'chromium',
* use: devices['Desktop Chrome'],
* },
* {
* name: 'firefox',
* use: devices['Desktop Firefox'],
* },
* {
* name: 'webkit',
* use: devices['Desktop Safari'],
* },
* {
* name: 'Mobile Chrome',
* use: devices['Pixel 5'],
* },
* {
* name: 'Mobile Safari',
* use: devices['iPhone 12'],
* },
* ],
* });
* ```
*
*/
interface TestProject<TestArgs = {}, WorkerArgs = {}> {
/**
* Options for all tests in this project, for example
* [testOptions.browserName](https://playwright.dev/docs/api/class-testoptions#test-options-browser-name). Learn more
* about [configuration](https://playwright.dev/docs/test-configuration) and see
* [available options][TestOptions](https://playwright.dev/docs/api/class-testoptions).
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* projects: [
* {
* name: 'Chromium',
* use: {
* browserName: 'chromium',
* },
* },
* ],
* });
* ```
*
* Use [testConfig.use](https://playwright.dev/docs/api/class-testconfig#test-config-use) to change this option for
* all projects.
*/
use?: UseOptions<TestArgs, WorkerArgs>;
/**
* List of projects that need to run before any test in this project runs. Dependencies can be useful for configuring
* the global setup actions in a way that every action is in a form of a test. Passing `--no-deps` argument ignores
* the dependencies and behaves as if they were not specified.
*
* Using dependencies allows global setup to produce traces and other artifacts, see the setup steps in the test
* report, etc.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* projects: [
* {
* name: 'setup',
* testMatch: /global.setup\.ts/,
* },
* {
* name: 'chromium',
* use: devices['Desktop Chrome'],
* dependencies: ['setup'],
* },
* {
* name: 'firefox',
* use: devices['Desktop Firefox'],
* dependencies: ['setup'],
* },
* {
* name: 'webkit',
* use: devices['Desktop Safari'],
* dependencies: ['setup'],
* },
* ],
* });
* ```
*
*/
dependencies?: Array<string>;
/**
* Configuration for the `expect` assertion library.
*
* Use [testConfig.expect](https://playwright.dev/docs/api/class-testconfig#test-config-expect) to change this option
* for all projects.
*/
expect?: {
/**
* Default timeout for async expect matchers in milliseconds, defaults to 5000ms.
*/
timeout?: number;
/**
* Configuration for the
* [expect(page).toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1)
* method.
*/
toHaveScreenshot?: {
/**
* an 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](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`.
*/
threshold?: number;
/**
* an acceptable amount of pixels that could be different, unset by default.
*/
maxDiffPixels?: number;
/**
* an acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by
* default.
*/
maxDiffPixelRatio?: number;
/**
* See [`animations`](https://playwright.dev/docs/api/class-page#page-screenshot-option-animations) in
* [page.screenshot([options])](https://playwright.dev/docs/api/class-page#page-screenshot). Defaults to `"disabled"`.
*/
animations?: "allow"|"disabled";
/**
* See [`caret`](https://playwright.dev/docs/api/class-page#page-screenshot-option-caret) in
* [page.screenshot([options])](https://playwright.dev/docs/api/class-page#page-screenshot). Defaults to `"hide"`.
*/
caret?: "hide"|"initial";
/**
* See [`scale`](https://playwright.dev/docs/api/class-page#page-screenshot-option-scale) in
* [page.screenshot([options])](https://playwright.dev/docs/api/class-page#page-screenshot). Defaults to `"css"`.
*/
scale?: "css"|"device";
/**
* See [`style`](https://playwright.dev/docs/api/class-page#page-screenshot-option-style) in
* [page.screenshot([options])](https://playwright.dev/docs/api/class-page#page-screenshot).
*/
stylePath?: string|Array<string>;
/**
* A template controlling location of the screenshots. See
* [testProject.snapshotPathTemplate](https://playwright.dev/docs/api/class-testproject#test-project-snapshot-path-template)
* for details.
*/
pathTemplate?: string;
};
/**
* Configuration for the
* [expect(locator).toMatchAriaSnapshot([options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-match-aria-snapshot-2)
* method.
*/
toMatchAriaSnapshot?: {
/**
* A template controlling location of the aria snapshots. See
* [testProject.snapshotPathTemplate](https://playwright.dev/docs/api/class-testproject#test-project-snapshot-path-template)
* for details.
*/
pathTemplate?: string;
/**
* Controls how children of the snapshot root are matched against the actual accessibility tree. This is equivalent to
* adding a `/children` property at the top of every aria snapshot template. Individual snapshots can override this by
* including an explicit `/children` property.
*/
children?: "contain"|"equal"|"deep-equal";
};
/**
* Configuration for the
* [expect(value).toMatchSnapshot(name[, options])](https://playwright.dev/docs/api/class-snapshotassertions#snapshot-assertions-to-match-snapshot-1)
* method.
*/
toMatchSnapshot?: {
/**
* an 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](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`.
*/
threshold?: number;
/**
* an acceptable amount of pixels that could be different, unset by default.
*/
maxDiffPixels?: number;
/**
* an acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by
* default.
*/
maxDiffPixelRatio?: number;
};
/**
* Configuration for the [expect(value).toPass()](https://playwright.dev/docs/test-assertions) method.
*/
toPass?: {
/**
* timeout for toPass method in milliseconds.
*/
timeout?: number;
/**
* probe intervals for toPass method in milliseconds.
*/
intervals?: Array<number>;
};
};
/**
* Playwright 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 project to concurrently run all tests in all files using this option.
*/
fullyParallel?: boolean;
/**
* Filter 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 globally and in the [command line](https://playwright.dev/docs/test-cli) 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](https://playwright.dev/docs/test-annotations#tag-tests).
*/
grep?: RegExp|Array<RegExp>;
/**
* Filter to only run tests with a title **not** matching any of the patterns. This is the opposite of
* [testProject.grep](https://playwright.dev/docs/api/class-testproject#test-project-grep). Also available globally
* and in the [command line](https://playwright.dev/docs/test-cli) with the `--grep-invert` option.
*
* `grepInvert` option is also useful for [tagging tests](https://playwright.dev/docs/test-annotations#tag-tests).
*/
grepInvert?: RegExp|Array<RegExp>;
/**
* Whether to skip snapshot expectations, such as `expect(value).toMatchSnapshot()` and `await
* expect(page).toHaveScreenshot()`.
*
* **Usage**
*
* The following example will only perform screenshot assertions on Chromium.
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* projects: [
* {
* name: 'chromium',
* use: devices['Desktop Chrome'],
* },
* {
* name: 'firefox',
* use: devices['Desktop Firefox'],
* ignoreSnapshots: true,
* },
* {
* name: 'webkit',
* use: devices['Desktop Safari'],
* ignoreSnapshots: true,
* },
* ],
* });
* ```
*
*/
ignoreSnapshots?: boolean;
/**
* Metadata that will be put directly to the test report serialized as JSON.
*/
metadata?: Metadata;
/**
* Project name is visible in the report and during test execution.
*
* **NOTE** Playwright executes the configuration file multiple times. Do not dynamically produce non-stable values in
* your configuration.
*
*/
name?: string;
/**
* The output directory for files created during test execution. Defaults to `<package.json-directory>/test-results`.
*
* This directory is cleaned at the start. When running a test, a unique subdirectory inside the
* [testProject.outputDir](https://playwright.dev/docs/api/class-testproject#test-project-output-dir) is created,
* guaranteeing that test running in parallel do not conflict. This directory can be accessed by
* [testInfo.outputDir](https://playwright.dev/docs/api/class-testinfo#test-info-output-dir) and
* [testInfo.outputPath(...pathSegments)](https://playwright.dev/docs/api/class-testinfo#test-info-output-path).
*
* Here is an example that uses
* [testInfo.outputPath(...pathSegments)](https://playwright.dev/docs/api/class-testinfo#test-info-output-path) to
* create a temporary file.
*
* ```js
* 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');
* });
* ```
*
* Use [testConfig.outputDir](https://playwright.dev/docs/api/class-testconfig#test-config-output-dir) to change this
* option for all projects.
*/
outputDir?: string;
/**
* The number of times to repeat each test, useful for debugging flaky tests.
*
* Use [testConfig.repeatEach](https://playwright.dev/docs/api/class-testconfig#test-config-repeat-each) to change
* this option for all projects.
*/
repeatEach?: number;
/**
* Whether to skip entries from `.gitignore` when searching for test files. By default, if neither
* [testConfig.testDir](https://playwright.dev/docs/api/class-testconfig#test-config-test-dir) nor
* [testProject.testDir](https://playwright.dev/docs/api/class-testproject#test-project-test-dir) are explicitly
* specified, Playwright will ignore any test files matching `.gitignore` entries. This option allows to override that
* behavior.
*/
respectGitIgnore?: boolean;
/**
* The maximum number of retry attempts given to failed tests. Learn more about
* [test retries](https://playwright.dev/docs/test-retries#retries).
*
* Use [test.describe.configure([options])](https://playwright.dev/docs/api/class-test#test-describe-configure) to
* change the number of retries for a specific file or a group of tests.
*
* Use [testConfig.retries](https://playwright.dev/docs/api/class-testconfig#test-config-retries) to change this
* option for all projects.
*/
retries?: number;
/**
* The base directory, relative to the config file, for snapshot files created with `toMatchSnapshot`. Defaults to
* [testProject.testDir](https://playwright.dev/docs/api/class-testproject#test-project-test-dir).
*
* The directory for each test can be accessed by
* [testInfo.snapshotDir](https://playwright.dev/docs/api/class-testinfo#test-info-snapshot-dir) and
* [testInfo.snapshotPath(...name[, options])](https://playwright.dev/docs/api/class-testinfo#test-info-snapshot-path).
*
* This path will serve as the base directory for each test file snapshot directory. Setting `snapshotDir` to
* `'snapshots'`, the [testInfo.snapshotDir](https://playwright.dev/docs/api/class-testinfo#test-info-snapshot-dir)
* would resolve to `snapshots/a.spec.js-snapshots`.
*/
snapshotDir?: string;
/**
* This option configures a template controlling location of snapshots generated by
* [expect(page).toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1),
* [expect(locator).toMatchAriaSnapshot([options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-match-aria-snapshot-2)
* and
* [expect(value).toMatchSnapshot(name[, options])](https://playwright.dev/docs/api/class-snapshotassertions#snapshot-assertions-to-match-snapshot-1).
*
* You can configure templates for each assertion separately in
* [testConfig.expect](https://playwright.dev/docs/api/class-testconfig#test-config-expect).
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* testDir: './tests',
*
* // Single template for all assertions
* snapshotPathTemplate: '{testDir}/__screenshots__/{testFilePath}/{arg}{ext}',
*
* // Assertion-specific templates
* expect: {
* toHaveScreenshot: {
* pathTemplate: '{testDir}/__screenshots__{/projectName}/{testFilePath}/{arg}{ext}',
* },
* toMatchAriaSnapshot: {
* pathTemplate: '{testDir}/__snapshots__/{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:
*
* ```txt
* playwright.config.ts
* tests/
* └── page/
* └── page-click.spec.ts
* ```
*
* And the following `page-click.spec.ts` that uses `toHaveScreenshot()` call:
*
* ```js
* // 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:
* - `{arg}` - Relative snapshot path **without extension**. This comes from the arguments passed to
* `toHaveScreenshot()`, `toMatchAriaSnapshot()` or `toMatchSnapshot()`; if called without arguments, this will be
* an auto-generated snapshot name.
* - Value: `foo/bar/baz`
* - `{ext}` - Snapshot extension (with the leading dot).
* - Value: `.png`
* - `{platform}` - The value of `process.platform`.
* - `{projectName}` - Project's file-system-sanitized name, if any.
* - Value: `''` (empty string).
* - `{snapshotDir}` - Project's
* [testProject.snapshotDir](https://playwright.dev/docs/api/class-testproject#test-project-snapshot-dir).
* - Value: `/home/playwright/tests` (since `snapshotDir` is not provided in config, it defaults to `testDir`)
* - `{testDir}` - Project's
* [testProject.testDir](https://playwright.dev/docs/api/class-testproject#test-project-test-dir).
* - Value: `/home/playwright/tests` (absolute path since `testDir` is resolved relative to directory with
* config)
* - `{testFileDir}` - Directories in relative path from `testDir` to **test file**.
* - Value: `page`
* - `{testFileName}` - Test file name with extension.
* - Value: `page-click.spec.ts`
* - `{testFilePath}` - Relative path from `testDir` to **test file**.
* - Value: `page/page-click.spec.ts`
* - `{testName}` - File-system-sanitized test title, including parent describes but excluding file name.
* - Value: `suite-test-should-work`
*
* 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:
*
* ```js
* // 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:
* 1. First project **does not** have a name, so its snapshots will be stored in
* `<configDir>/__screenshots__/example.spec.ts/...`.
* 1. Second project **does** have a name, so its snapshots will be stored in
* `<configDir>/__screenshots__/chromium/example.spec.ts/..`.
* 1. Since `snapshotPathTemplate` resolves to relative path, it will be resolved relative to `configDir`.
* 1. Forward slashes `"/"` can be used as path separators on any platform.
*/
snapshotPathTemplate?: string;
/**
* Name of a project that needs to run after this and all dependent projects have finished. Teardown is useful to
* cleanup any resources acquired by this project.
*
* Passing `--no-deps` argument ignores
* [testProject.teardown](https://playwright.dev/docs/api/class-testproject#test-project-teardown) and behaves as if
* it was not specified.
*
* **Usage**
*
* A common pattern is a "setup" dependency that has a corresponding "teardown":
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* projects: [
* {
* name: 'setup',
* testMatch: /global.setup\.ts/,
* teardown: 'teardown',
* },
* {
* name: 'teardown',
* testMatch: /global.teardown\.ts/,
* },
* {
* name: 'chromium',
* use: devices['Desktop Chrome'],
* dependencies: ['setup'],
* },
* {
* name: 'firefox',
* use: devices['Desktop Firefox'],
* dependencies: ['setup'],
* },
* {
* name: 'webkit',
* use: devices['Desktop Safari'],
* dependencies: ['setup'],
* },
* ],
* });
* ```
*
*/
teardown?: string;
/**
* Directory that will be recursively scanned for test files. Defaults to the directory of the configuration file.
*
* Each project can use a different directory. Here is an example that runs smoke tests in three browsers and all
* other tests in stable Chrome browser.
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* projects: [
* {
* name: 'Smoke Chromium',
* testDir: './smoke-tests',
* use: {
* browserName: 'chromium',
* }
* },
* {
* name: 'Smoke WebKit',
* testDir: './smoke-tests',
* use: {
* browserName: 'webkit',
* }
* },
* {
* name: 'Smoke Firefox',
* testDir: './smoke-tests',
* use: {
* browserName: 'firefox',
* }
* },
* {
* name: 'Chrome Stable',
* testDir: './',
* use: {
* browserName: 'chromium',
* channel: 'chrome',
* }
* },
* ],
* });
* ```
*
* Use [testConfig.testDir](https://playwright.dev/docs/api/class-testconfig#test-config-test-dir) to change this
* option for all projects.
*/
testDir?: string;
/**
* Files 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.
*
* Use [testConfig.testIgnore](https://playwright.dev/docs/api/class-testconfig#test-config-test-ignore) to change
* this option for all projects.
*/
testIgnore?: string|RegExp|Array<string|RegExp>;
/**
* Only 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`.
*
* Use [testConfig.testMatch](https://playwright.dev/docs/api/class-testconfig#test-config-test-match) to change this
* option for all projects.
*/
testMatch?: string|RegExp|Array<string|RegExp>;
/**
* Timeout for each test in milliseconds. Defaults to 30 seconds.
*
* This is a base timeout for all tests. Each test can configure its own timeout with
* [test.setTimeout(timeout)](https://playwright.dev/docs/api/class-test#test-set-timeout). Each file or a group of
* tests can configure the timeout with
* [test.describe.configure([options])](https://playwright.dev/docs/api/class-test#test-describe-configure).
*
* Use [testConfig.timeout](https://playwright.dev/docs/api/class-testconfig#test-config-timeout) to change this
* option for all projects.
*/
timeout?: number;
/**
* The maximum number of concurrent worker processes to use for parallelizing tests from this project. Can also be set
* as percentage of logical CPU cores, e.g. `'50%'.`
*
* This could be useful, for example, when all tests from a project share a single resource like a test account, and
* therefore cannot be executed in parallel. Limiting workers to one for such a project will prevent simultaneous use
* of the shared resource.
*
* Note that the global [testConfig.workers](https://playwright.dev/docs/api/class-testconfig#test-config-workers)
* limit applies to the total number of worker processes. However, Playwright will limit the number of workers used
* for this project by the value of
* [testProject.workers](https://playwright.dev/docs/api/class-testproject#test-project-workers).
*
* By default, there is no limit per project. See
* [testConfig.workers](https://playwright.dev/docs/api/class-testconfig#test-config-workers) for the default of the
* total worker limit.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* workers: 10, // total workers limit
*
* projects: [
* {
* name: 'runs in parallel',
* },
* {
* name: 'one at a time',
* workers: 1, // workers limit for this project
* },
* ],
* });
* ```
*
*/
workers?: number|string;
}
export interface Project<TestArgs = {}, WorkerArgs = {}> extends TestProject<TestArgs, WorkerArgs> {
}
/**
* Runtime representation of the test project configuration. It is accessible in the tests via
* [testInfo.project](https://playwright.dev/docs/api/class-testinfo#test-info-project) and
* [workerInfo.project](https://playwright.dev/docs/api/class-workerinfo#worker-info-project) and is passed to the
* test reporters. To see the format of the project in the Playwright configuration file please see
* [TestProject](https://playwright.dev/docs/api/class-testproject) instead.
*/
export interface FullProject<TestArgs = {}, WorkerArgs = {}> {
/**
* See [testProject.use](https://playwright.dev/docs/api/class-testproject#test-project-use).
*/
use: UseOptions<PlaywrightTestOptions & TestArgs, PlaywrightWorkerOptions & WorkerArgs>;
/**
* See [testProject.dependencies](https://playwright.dev/docs/api/class-testproject#test-project-dependencies).
*/
dependencies: Array<string>;
/**
* See [testProject.grep](https://playwright.dev/docs/api/class-testproject#test-project-grep).
*/
grep: RegExp|Array<RegExp>;
/**
* See [testProject.grepInvert](https://playwright.dev/docs/api/class-testproject#test-project-grep-invert).
*/
grepInvert: null|RegExp|Array<RegExp>;
/**
* See [testProject.ignoreSnapshots](https://playwright.dev/docs/api/class-testproject#test-project-ignore-snapshots).
*/
ignoreSnapshots: boolean;
/**
* See [testProject.metadata](https://playwright.dev/docs/api/class-testproject#test-project-metadata).
*/
metadata: Metadata;
/**
* See [testProject.name](https://playwright.dev/docs/api/class-testproject#test-project-name).
*/
name: string;
/**
* See [testProject.outputDir](https://playwright.dev/docs/api/class-testproject#test-project-output-dir).
*/
outputDir: string;
/**
* See [testProject.repeatEach](https://playwright.dev/docs/api/class-testproject#test-project-repeat-each).
*/
repeatEach: number;
/**
* See [testProject.retries](https://playwright.dev/docs/api/class-testproject#test-project-retries).
*/
retries: number;
/**
* See [testProject.snapshotDir](https://playwright.dev/docs/api/class-testproject#test-project-snapshot-dir).
*/
snapshotDir: string;
/**
* See [testProject.teardown](https://playwright.dev/docs/api/class-testproject#test-project-teardown).
*/
teardown?: string;
/**
* See [testProject.testDir](https://playwright.dev/docs/api/class-testproject#test-project-test-dir).
*/
testDir: string;
/**
* See [testProject.testIgnore](https://playwright.dev/docs/api/class-testproject#test-project-test-ignore).
*/
testIgnore: string|RegExp|Array<string|RegExp>;
/**
* See [testProject.testMatch](https://playwright.dev/docs/api/class-testproject#test-project-test-match).
*/
testMatch: string|RegExp|Array<string|RegExp>;
/**
* See [testProject.timeout](https://playwright.dev/docs/api/class-testproject#test-project-timeout).
*/
timeout: number;
}
type LiteralUnion<T extends U, U = string> = T | (U & { zz_IGNORE_ME?: never });
/**
* 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](https://playwright.dev/docs/api/class-testconfig)
* object in the [configuration file](https://playwright.dev/docs/test-configuration). This type describes format of the configuration file,
* to access resolved configuration parameters at run time use
* [FullConfig](https://playwright.dev/docs/api/class-fullconfig).
*
* Playwright Test supports running multiple test projects at the same time. Project-specific options should be put to
* [testConfig.projects](https://playwright.dev/docs/api/class-testconfig#test-config-projects), but top-level
* [TestConfig](https://playwright.dev/docs/api/class-testconfig) can also define base options shared between all
* projects.
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* timeout: 30000,
* globalTimeout: 600000,
* reporter: 'list',
* testDir: './tests',
* });
* ```
*
*/
interface TestConfig<TestArgs = {}, WorkerArgs = {}> {
/**
* Playwright Test supports running multiple test projects at the same time. See
* [TestProject](https://playwright.dev/docs/api/class-testproject) for more information.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig, devices } from '@playwright/test';
*
* export default defineConfig({
* projects: [
* { name: 'chromium', use: devices['Desktop Chrome'] }
* ]
* });
* ```
*
*/
projects?: Project<TestArgs, WorkerArgs>[];
/**
* The 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' }]`. If the property
* is not specified, Playwright uses the `'dot'` reporter when the CI environment variable is set, and the `'list'`
* reporter otherwise.
*
* Learn more in the [reporters guide](https://playwright.dev/docs/test-reporters).
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* reporter: 'line',
* });
* ```
*
*/
reporter?: LiteralUnion<'list'|'dot'|'line'|'github'|'json'|'junit'|'null'|'html', string> | ReporterDescription[];
/**
* Global options for all tests, for example
* [testOptions.browserName](https://playwright.dev/docs/api/class-testoptions#test-options-browser-name). Learn more
* about [configuration](https://playwright.dev/docs/test-configuration) and see
* [available options][TestOptions](https://playwright.dev/docs/api/class-testoptions).
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* browserName: 'chromium',
* },
* });
* ```
*
*/
use?: UseOptions<TestArgs, WorkerArgs>;
/**
* Launch 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](https://playwright.dev/docs/api/class-testoptions#test-options-base-url). 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](https://playwright.dev/docs/api/class-testoptions#test-options-base-url) in the config, so
* that tests could use relative urls.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
* export default defineConfig({
* webServer: {
* command: 'npm run start',
* url: 'http://localhost:3000',
* timeout: 120 * 1000,
* reuseExistingServer: !process.env.CI,
* },
* use: {
* baseURL: 'http://localhost:3000/',
* },
* });
* ```
*
* Now you can use a relative path when navigating the page:
*
* ```js
* // 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:
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
* export default defineConfig({
* webServer: [
* {
* command: 'npm run start',
* url: 'http://localhost:3000',
* name: 'Frontend',
* timeout: 120 * 1000,
* reuseExistingServer: !process.env.CI,
* },
* {
* command: 'npm run backend',
* url: 'http://localhost:3333',
* name: 'Backend',
* timeout: 120 * 1000,
* reuseExistingServer: !process.env.CI,
* }
* ],
* use: {
* baseURL: 'http://localhost:3000',
* },
* });
* ```
*
* If your webserver runs on varying ports, use `wait` to capture the port:
*
* ```js
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* webServer: {
* command: 'npm run start',
* wait: {
* stdout: /Listening on port (?<my_server_port>\d+)/
* },
* },
* });
* ```
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.use({ baseUrl: `http://localhost:${process.env.MY_SERVER_PORT ?? 3000}` });
*
* test('homepage', async ({ page }) => {
* await page.goto('/');
* });
* ```
*
*/
webServer?: TestConfigWebServer | TestConfigWebServer[];
/**
* Playwright transpiler configuration.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* build: {
* external: ['**\/*bundle.js'],
* },
* });
* ```
*
*/
build?: {
/**
* Paths to exclude from the transpilation expressed as a list of glob patterns. Typically heavy JS bundles that your
* test uses are listed here.
*/
external?: Array<string>;
};
/**
* These settings control whether git information is captured and stored in the config
* [testConfig.metadata](https://playwright.dev/docs/api/class-testconfig#test-config-metadata).
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* captureGitInfo: { commit: true, diff: true }
* });
* ```
*
* **Details**
* - Capturing `commit` information is useful when you'd like to see it in your HTML (or a third party) report.
* - Capturing `diff` information is useful to enrich the report with the actual source diff. This information can
* be used to provide intelligent advice on how to fix the test.
*
* **NOTE** Default values for these settings depend on the environment. When tests run as a part of CI where it is
* safe to obtain git information, the default value is `true`, `false` otherwise.
*
* **NOTE** The structure of the git commit metadata is subject to change.
*
*/
captureGitInfo?: {
/**
* Whether to capture commit and pull request information such as hash, author, timestamp.
*/
commit?: boolean;
/**
* Whether to capture commit diff.
*/
diff?: boolean;
};
/**
* Configuration for the `expect` assertion library. Learn more about [various timeouts](https://playwright.dev/docs/test-timeouts).
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* expect: {
* timeout: 10000,
* toMatchSnapshot: {
* maxDiffPixels: 10,
* },
* },
* });
* ```
*
*/
expect?: {
/**
* Default timeout for async expect matchers in milliseconds, defaults to 5000ms.
*/
timeout?: number;
/**
* Configuration for the
* [expect(page).toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1)
* method.
*/
toHaveScreenshot?: {
/**
* See [`animations`](https://playwright.dev/docs/api/class-page#page-screenshot-option-animations) in
* [page.screenshot([options])](https://playwright.dev/docs/api/class-page#page-screenshot). Defaults to `"disabled"`.
*/
animations?: "allow"|"disabled";
/**
* See [`caret`](https://playwright.dev/docs/api/class-page#page-screenshot-option-caret) in
* [page.screenshot([options])](https://playwright.dev/docs/api/class-page#page-screenshot). Defaults to `"hide"`.
*/
caret?: "hide"|"initial";
/**
* An acceptable amount of pixels that could be different, unset by default.
*/
maxDiffPixels?: number;
/**
* An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by
* default.
*/
maxDiffPixelRatio?: number;
/**
* See [`scale`](https://playwright.dev/docs/api/class-page#page-screenshot-option-scale) in
* [page.screenshot([options])](https://playwright.dev/docs/api/class-page#page-screenshot). Defaults to `"css"`.
*/
scale?: "css"|"device";
/**
* See [`style`](https://playwright.dev/docs/api/class-page#page-screenshot-option-style) in
* [page.screenshot([options])](https://playwright.dev/docs/api/class-page#page-screenshot).
*/
stylePath?: string|Array<string>;
/**
* An 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](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`.
*/
threshold?: number;
/**
* A template controlling location of the screenshots. See
* [testConfig.snapshotPathTemplate](https://playwright.dev/docs/api/class-testconfig#test-config-snapshot-path-template)
* for details.
*/
pathTemplate?: string;
};
/**
* Configuration for the
* [expect(locator).toMatchAriaSnapshot([options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-match-aria-snapshot-2)
* method.
*/
toMatchAriaSnapshot?: {
/**
* A template controlling location of the aria snapshots. See
* [testConfig.snapshotPathTemplate](https://playwright.dev/docs/api/class-testconfig#test-config-snapshot-path-template)
* for details.
*/
pathTemplate?: string;
/**
* Controls how children of the snapshot root are matched against the actual accessibility tree. This is equivalent to
* adding a `/children` property at the top of every aria snapshot template. Individual snapshots can override this by
* including an explicit `/children` property.
*/
children?: "contain"|"equal"|"deep-equal";
};
/**
* Configuration for the
* [expect(value).toMatchSnapshot(name[, options])](https://playwright.dev/docs/api/class-snapshotassertions#snapshot-assertions-to-match-snapshot-1)
* method.
*/
toMatchSnapshot?: {
/**
* An acceptable amount of pixels that could be different, unset by default.
*/
maxDiffPixels?: number;
/**
* An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by
* default.
*/
maxDiffPixelRatio?: number;
/**
* An 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](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`.
*/
threshold?: number;
};
/**
* Configuration for the [expect(value).toPass()](https://playwright.dev/docs/test-assertions#expecttopass) method.
*/
toPass?: {
/**
* Probe intervals for toPass method in milliseconds.
*/
intervals?: Array<number>;
/**
* Timeout for toPass method in milliseconds.
*/
timeout?: number;
};
};
/**
* Whether to exit with an error if any tests are marked as flaky. Useful on CI.
*
* Also available in the [command line](https://playwright.dev/docs/test-cli) with the `--fail-on-flaky-tests` option.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* failOnFlakyTests: !!process.env.CI,
* });
* ```
*
*/
failOnFlakyTests?: boolean;
/**
* Whether to exit with an error if any tests or groups are marked as
* [test.only(title[, details, body])](https://playwright.dev/docs/api/class-test#test-only) or
* [test.describe.only([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-only).
* Useful on CI.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* forbidOnly: !!process.env.CI,
* });
* ```
*
*/
forbidOnly?: boolean;
/**
* Playwright 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**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* fullyParallel: true,
* });
* ```
*
*/
fullyParallel?: boolean;
/**
* Path 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](https://playwright.dev/docs/api/class-fullconfig) argument. Pass an array of
* paths to specify multiple global setup files.
*
* Learn more about [global setup and teardown](https://playwright.dev/docs/test-global-setup-teardown).
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* globalSetup: './global-setup',
* });
* ```
*
*/
globalSetup?: string|Array<string>;
/**
* Path 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](https://playwright.dev/docs/api/class-testconfig#test-config-global-setup). Pass an array
* of paths to specify multiple global teardown files.
*
* Learn more about [global setup and teardown](https://playwright.dev/docs/test-global-setup-teardown).
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* globalTeardown: './global-teardown',
* });
* ```
*
*/
globalTeardown?: string|Array<string>;
/**
* Maximum 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](https://playwright.dev/docs/test-timeouts).
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* globalTimeout: process.env.CI ? 60 * 60 * 1000 : undefined,
* });
* ```
*
*/
globalTimeout?: number;
/**
* Filter 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](https://playwright.dev/docs/test-cli) 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](https://playwright.dev/docs/test-annotations#tag-tests).
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* grep: /smoke/,
* });
* ```
*
*/
grep?: RegExp|Array<RegExp>;
/**
* Filter to only run tests with a title **not** matching one of the patterns. This is the opposite of
* [testConfig.grep](https://playwright.dev/docs/api/class-testconfig#test-config-grep). Also available in the
* [command line](https://playwright.dev/docs/test-cli) with the `--grep-invert` option.
*
* `grepInvert` option is also useful for [tagging tests](https://playwright.dev/docs/test-annotations#tag-tests).
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* grepInvert: /manual/,
* });
* ```
*
*/
grepInvert?: RegExp|Array<RegExp>;
/**
* Whether to skip snapshot expectations, such as `expect(value).toMatchSnapshot()` and `await
* expect(page).toHaveScreenshot()`.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* ignoreSnapshots: !process.env.CI,
* });
* ```
*
*/
ignoreSnapshots?: boolean;
/**
* The maximum number of test failures for the whole test suite run. After reaching this number, t