diff --git a/docs/src/test-api/class-testconfig.md b/docs/src/test-api/class-testconfig.md index bb9969fc5a..c622b260c1 100644 --- a/docs/src/test-api/class-testconfig.md +++ b/docs/src/test-api/class-testconfig.md @@ -84,7 +84,7 @@ export default config; ``` ## property: TestConfig.forbidOnly -- type: <[boolean]> +- type: ?<[boolean]> Whether to exit with an error if any tests or groups are marked as [`method: Test.only`] or [`method: Test.describe.only`]. Useful on CI. @@ -111,7 +111,7 @@ export default config; ``` ## property: TestConfig.fullyParallel -- type: <[boolean]> +- type: ?<[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. @@ -119,7 +119,7 @@ By default, **test files** are run in parallel. Tests in a single file are run i You can configure entire test run to concurrently execute all tests in all files using this option. ## property: TestConfig.globalSetup -- type: <[string]> +- type: ?<[string]> 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 [`TestConfig`] argument. @@ -148,7 +148,7 @@ export default config; ``` ## property: TestConfig.globalTeardown -- type: <[string]> +- type: ?<[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 [`property: TestConfig.globalSetup`]. @@ -177,7 +177,7 @@ export default config; ``` ## property: TestConfig.globalTimeout -- type: <[int]> +- type: ?<[int]> 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](../test-timeouts.md). @@ -204,7 +204,7 @@ export default config; ``` ## property: TestConfig.grep -- type: <[RegExp]|[Array]<[RegExp]>> +- type: ?<[RegExp]|[Array]<[RegExp]>> 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](../test-cli.md) with the `-g` option. @@ -212,7 +212,7 @@ Filter to only run tests with a title matching one of the patterns. For example, ## property: TestConfig.grepInvert -- type: <[RegExp]|[Array]<[RegExp]>> +- type: ?<[RegExp]|[Array]<[RegExp]>> Filter to only run tests with a title **not** matching one of the patterns. This is the opposite of [`property: TestConfig.grep`]. Also available in the [command line](../test-cli.md) with the `--grep-invert` option. @@ -220,7 +220,7 @@ Filter to only run tests with a title **not** matching one of the patterns. This ## property: TestConfig.maxFailures -- type: <[int]> +- type: ?<[int]> The 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. @@ -249,17 +249,17 @@ export default config; ``` ## property: TestConfig.metadata -- type: <[Object]> +- type: ?<[any]> Any JSON-serializable metadata that will be put directly to the test report. ## property: TestConfig.name -- type: <[string]> +- type: ?<[string]> Config name is visible in the report and during test execution, unless overridden by [`property: TestProject.name`]. ## property: TestConfig.outputDir -- type: <[string]> +- type: ?<[string]> The output directory for files created during test execution. Defaults to `/test-results`. @@ -311,7 +311,7 @@ test('example test', async ({}, testInfo) => { ## property: TestConfig.snapshotDir -- type: <[string]> +- type: ?<[string]> The base directory, relative to the config file, for snapshot files created with `toMatchSnapshot`. Defaults to [`property: TestConfig.testDir`]. @@ -320,7 +320,7 @@ The directory for each test can be accessed by [`property: TestInfo.snapshotDir` This path will serve as the base directory for each test file snapshot directory. Setting `snapshotDir` to `'snapshots'`, the [`property: TestInfo.snapshotDir`] would resolve to `snapshots/a.spec.js-snapshots`. ## property: TestConfig.preserveOutput -- type: <[PreserveOutput]<"always"|"never"|"failures-only">> +- type: ?<[PreserveOutput]<"always"|"never"|"failures-only">> Whether to preserve test output in the [`property: TestConfig.outputDir`]. Defaults to `'always'`. * `'always'` - preserve output for all tests; @@ -329,23 +329,23 @@ Whether to preserve test output in the [`property: TestConfig.outputDir`]. Defau ## property: TestConfig.projects -- type: <[Array]<[TestProject]>> +- type: ?<[Array]<[TestProject]>> Playwright Test supports running multiple test projects at the same time. See [TestProject] for more information. ## property: TestConfig.quiet -- type: <[boolean]> +- type: ?<[boolean]> Whether to suppress stdio and stderr output from the tests. ## property: TestConfig.repeatEach -- type: <[int]> +- type: ?<[int]> The number of times to repeat each test, useful for debugging flaky tests. ## property: TestConfig.reporter -- type: <[string]|[Array]<[Object]>|[BuiltInReporter]<"list"|"dot"|"line"|"github"|"json"|"junit"|"null"|"html">> +- type: ?<[string]|[Array]<[Object]>|[BuiltInReporter]<"list"|"dot"|"line"|"github"|"json"|"junit"|"null"|"html">> - `0` <[string]> Reporter name or module or file path - `1` <[Object]> An object with reporter options if any @@ -381,7 +381,7 @@ export default config; ``` ## property: TestConfig.reportSlowTests -- type: <[Object]> +- type: ?<[null]|[Object]> - `max` <[int]> The maximum number of slow test files to report. Defaults to `5`. - `threshold` <[float]> Test duration in milliseconds that is considered slow. Defaults to 15 seconds. @@ -390,7 +390,7 @@ Whether to report slow test files. Pass `null` to disable this feature. 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. ## property: TestConfig.retries -- type: <[int]> +- type: ?<[int]> The maximum number of retry attempts given to failed tests. By default failing tests are not retried. Learn more about [test retries](../test-retries.md#retries). @@ -453,7 +453,7 @@ where: * `Mobile Safari` and `Desktop Chrome` - project names ## property: TestConfig.shard -- type: <[Object]> +- type: ?<[null]|[Object]> - `total` <[int]> The total number of shards. - `current` <[int]> The index of the shard to execute, one-based. @@ -462,7 +462,7 @@ Shard tests and execute only the selected shard. Specify in the one-based form l Learn more about [parallelism and sharding](../test-parallel.md) with Playwright Test. ## property: TestConfig.testDir -- type: <[string]> +- type: ?<[string]> Directory that will be recursively scanned for test files. Defaults to the directory of the configuration file. @@ -489,7 +489,7 @@ export default config; ``` ## property: TestConfig.testIgnore -- type: <[string]|[RegExp]|[Array]<[string]>|[Array]<[RegExp]>> +- type: ?<[string]|[RegExp]|[Array]<[string]|[RegExp]>> 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. @@ -518,7 +518,7 @@ export default config; ``` ## property: TestConfig.testMatch -- type: <[string]|[RegExp]|[Array]<[string]>|[Array]<[RegExp]>> +- type: ?<[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. @@ -547,7 +547,7 @@ export default config; ``` ## property: TestConfig.timeout -- type: <[int]> +- type: ?<[int]> Timeout for each test in milliseconds. Defaults to 30 seconds. @@ -576,7 +576,7 @@ export default config; ``` ## property: TestConfig.updateSnapshots -- type: <[UpdateSnapshots]<"all"|"none"|"missing">> +- type: ?<[UpdateSnapshots]<"all"|"none"|"missing">> Whether 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. @@ -586,7 +586,7 @@ Whether to update expected snapshots with the actual results produced by the tes Learn more about [snapshots](../test-snapshots.md). ## property: TestConfig.use -- type: <[TestOptions]> +- type: ?<[TestOptions]> Global options for all tests, for example [`property: TestOptions.browserName`]. Learn more about [configuration](../test-configuration.md) and see [available options][TestOptions]. @@ -617,15 +617,15 @@ export default config; ``` ## property: TestConfig.webServer -- type: <[Object]> - - `command` <[string]> Command which gets executed - - `port` <[int]> Port to wait on for the web server (exactly one of `port` or `url` is required) - - `url` <[string]> URL to wait on for the web server (exactly one of `port` or `url` is required) - - `ignoreHTTPSErrors` <[boolean]> Whether to ignore HTTPS errors when fetching the `url`. Defaults to `false`. - - `timeout` <[int]> Maximum duration to wait on until the web server is ready - - `reuseExistingServer` <[boolean]> If true, reuse the existing server if it is already running, otherwise it will fail - - `cwd` <[string]> Working directory to run the command in - - `env` <[Object]<[string], [string]>> Environment variables to set for the command +- type: ?<[Object]> + - `command` <[string]> Shell command to start. For example `npm run start`.. + - `port` ?<[int]> The port that your http server is expected to appear on. It does wait until it accepts connections. Exactly one of `port` or `url` is required. + - `url` ?<[string]> The url on your http server that is expected to return a 2xx status code when the server is ready to accept connections. Exactly one of `port` or `url` is required. + - `ignoreHTTPSErrors` ?<[boolean]> Whether to ignore HTTPS errors when fetching the `url`. Defaults to `false`. + - `timeout` ?<[int]> How long to wait for the process to start up and be available in milliseconds. Defaults to 60000. + - `reuseExistingServer` ?<[boolean]> If true, it will re-use an existing server on the `port` or `url` when available. If no server is running on that `port` or `url`, it will run the command to start a new server. If `false`, it will throw if an existing process is listening on the `port` or `url`. This should be commonly set to `!process.env.CI` to allow the local dev server when running tests locally. + - `cwd` ?<[string]> Current working directory of the spawned process, `process.cwd()` by default. + - `env` ?<[Object]<[string], [string]>> Environment variables to set for the command, `process.env` by default. Launch a development web server during the tests. @@ -697,7 +697,7 @@ test('test', async ({ page }) => { ``` ## property: TestConfig.workers -- type: <[int]> +- type: ?<[int]> The maximum number of concurrent worker processes to use for parallelizing tests. diff --git a/docs/src/test-api/class-testproject.md b/docs/src/test-api/class-testproject.md index 56e28da374..4e2639f389 100644 --- a/docs/src/test-api/class-testproject.md +++ b/docs/src/test-api/class-testproject.md @@ -125,7 +125,7 @@ Configuration for the `expect` assertion library. Use [`property: TestConfig.expect`] to change this option for all projects. ## property: TestProject.fullyParallel -- type: <[boolean]> +- type: ?<[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. @@ -133,26 +133,26 @@ By default, **test files** are run in parallel. Tests in a single file are run i You can configure entire test project to concurrently run all tests in all files using this option. ## property: TestProject.grep -- type: <[RegExp]|[Array]<[RegExp]>> +- type: ?<[RegExp]|[Array]<[RegExp]>> 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](../test-cli.md) with the `-g` option. `grep` option is also useful for [tagging tests](../test-annotations.md#tag-tests). ## property: TestProject.grepInvert -- type: <[RegExp]|[Array]<[RegExp]>> +- type: ?<[RegExp]|[Array]<[RegExp]>> Filter to only run tests with a title **not** matching one of the patterns. This is the opposite of [`property: TestProject.grep`]. Also available globally and in the [command line](../test-cli.md) with the `--grep-invert` option. `grepInvert` option is also useful for [tagging tests](../test-annotations.md#tag-tests). ## property: TestProject.metadata -- type: <[Object]> +- type: ?<[any]> Any JSON-serializable metadata that will be put directly to the test report. ## property: TestProject.name -- type: <[string]> +- type: ?<[string]> Project name is visible in the report and during test execution. @@ -195,7 +195,7 @@ where: ## property: TestProject.snapshotDir -- type: <[string]> +- type: ?<[string]> The base directory, relative to the config file, for snapshot files created with `toMatchSnapshot`. Defaults to [`property: TestProject.testDir`]. @@ -204,7 +204,7 @@ The directory for each test can be accessed by [`property: TestInfo.snapshotDir` This path will serve as the base directory for each test file snapshot directory. Setting `snapshotDir` to `'snapshots'`, the [`property: TestInfo.snapshotDir`] would resolve to `snapshots/a.spec.js-snapshots`. ## property: TestProject.outputDir -- type: <[string]> +- type: ?<[string]> The output directory for files created during test execution. Defaults to `/test-results`. @@ -235,21 +235,21 @@ test('example test', async ({}, testInfo) => { Use [`property: TestConfig.outputDir`] to change this option for all projects. ## property: TestProject.repeatEach -- type: <[int]> +- type: ?<[int]> The number of times to repeat each test, useful for debugging flaky tests. Use [`property: TestConfig.repeatEach`] to change this option for all projects. ## property: TestProject.retries -- type: <[int]> +- type: ?<[int]> The maximum number of retry attempts given to failed tests. Learn more about [test retries](../test-retries.md#retries). Use [`property: TestConfig.retries`] to change this option for all projects. ## property: TestProject.testDir -- type: <[string]> +- type: ?<[string]> Directory that will be recursively scanned for test files. Defaults to the directory of the configuration file. @@ -340,7 +340,7 @@ export default config; Use [`property: TestConfig.testDir`] to change this option for all projects. ## property: TestProject.testIgnore -- type: <[string]|[RegExp]|[Array]<[string]>|[Array]<[RegExp]>> +- type: ?<[string]|[RegExp]|[Array]<[string]|[RegExp]>> 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. @@ -349,7 +349,7 @@ For example, `'**/test-assets/**'` will ignore any files in the `test-assets` di Use [`property: TestConfig.testIgnore`] to change this option for all projects. ## property: TestProject.testMatch -- type: <[string]|[RegExp]|[Array]<[string]>|[Array]<[RegExp]>> +- type: ?<[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. @@ -358,7 +358,7 @@ By default, Playwright Test looks for files matching `.*(test|spec)\.(js|ts|mjs) Use [`property: TestConfig.testMatch`] to change this option for all projects. ## property: TestProject.timeout -- type: <[int]> +- type: ?<[int]> Timeout for each test in milliseconds. Defaults to 30 seconds. diff --git a/packages/playwright-test/types/test.d.ts b/packages/playwright-test/types/test.d.ts index c5a6da4430..62182c399b 100644 --- a/packages/playwright-test/types/test.d.ts +++ b/packages/playwright-test/types/test.d.ts @@ -36,267 +36,6 @@ export type UpdateSnapshots = 'all' | 'none' | 'missing'; type UseOptions = { [K in keyof WorkerArgs]?: WorkerArgs[K] } & { [K in keyof TestArgs]?: TestArgs[K] }; -/** - * 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. - * - * `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] are available in the top-level - * [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. - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig, devices } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * // Options shared for all projects. - * timeout: 30000, - * use: { - * ignoreHTTPSErrors: true, - * }, - * - * // Options specific to each project. - * projects: [ - * { - * name: 'Desktop Chromium', - * use: { - * browserName: 'chromium', - * viewport: { width: 1280, height: 720 }, - * }, - * }, - * { - * name: 'Desktop Safari', - * use: { - * browserName: 'webkit', - * viewport: { width: 1280, height: 720 }, - * } - * }, - * { - * name: 'Desktop Firefox', - * use: { - * browserName: 'firefox', - * viewport: { width: 1280, height: 720 }, - * } - * }, - * { - * name: 'Mobile Chrome', - * use: devices['Pixel 5'], - * }, - * { - * name: 'Mobile Safari', - * use: devices['iPhone 12'], - * }, - * ], - * }; - * export default config; - * ``` - * - */ -interface TestProject { - /** - * 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. - * - * `grep` option is also useful for [tagging tests](https://playwright.dev/docs/test-annotations#tag-tests). - */ - grep?: RegExp | RegExp[]; - /** - * Filter to only run tests with a title **not** matching one 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 | RegExp[] | null; - /** - * Any JSON-serializable metadata that will be put directly to the test report. - */ - metadata?: any; - /** - * Project name is visible in the report and during test execution. - */ - name?: string; - /** - * 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(...pathSegments)](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; - /** - * The output directory for files created during test execution. Defaults to `/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. - * - * ```ts - * 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; - /** - * The maximum number of retry attempts given to failed tests. Learn more about [test retries](https://playwright.dev/docs/test-retries#retries). - * - * Use [testConfig.retries](https://playwright.dev/docs/api/class-testconfig#test-config-retries) to change this option for - * all projects. - */ - retries?: number; - /** - * 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. - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * 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', - * } - * }, - * ], - * }; - * export default config; - * ``` - * - * 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 | (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 Test looks for files matching `.*(test|spec)\.(js|ts|mjs)`. - * - * Use [testConfig.testMatch](https://playwright.dev/docs/api/class-testconfig#test-config-test-match) to change this - * option for all projects. - */ - testMatch?: string | RegExp | (string | RegExp)[]; - /** - * Timeout 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)](https://playwright.dev/docs/api/class-test#test-set-timeout). - * - * Use [testConfig.timeout](https://playwright.dev/docs/api/class-testconfig#test-config-timeout) to change this option for - * all projects. - */ - timeout?: number; - /** - * 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 - * [screenshotAssertions.toMatchSnapshot(name[, options])](https://playwright.dev/docs/api/class-screenshotassertions#screenshot-assertions-to-match-snapshot-1) - * method. - */ - toMatchSnapshot?: { - /** - * an acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the same - * pixel in compared images, between zero (strict) and one (lax). Defaults 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; - }; - };} - /** * 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. @@ -695,133 +434,6 @@ type LiteralUnion = T | (U & { zz_IGNORE_ME?: never }); * */ interface TestConfig { - /** - * Whether to exit with an error if any tests or groups are marked as - * [test.only(title, testFunction)](https://playwright.dev/docs/api/class-test#test-only) or - * [test.describe.only(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-only). Useful on CI. - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * forbidOnly: !!process.env.CI, - * }; - * export default config; - * ``` - * - */ - 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. - */ - 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 [`TestConfig`] argument. - * - * Learn more about [global setup and teardown](https://playwright.dev/docs/test-advanced#global-setup-and-teardown). - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig, devices } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * globalSetup: './global-setup', - * }; - * export default config; - * ``` - * - */ - globalSetup?: 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). - * - * Learn more about [global setup and teardown](https://playwright.dev/docs/test-advanced#global-setup-and-teardown). - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig, devices } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * globalTeardown: './global-teardown', - * }; - * export default config; - * ``` - * - */ - globalTeardown?: 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). - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * globalTimeout: process.env.CI ? 60 * 60 * 1000 : undefined, - * }; - * export default config; - * ``` - * - */ - 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. - * - * `grep` option is also useful for [tagging tests](https://playwright.dev/docs/test-annotations#tag-tests). - */ - grep?: RegExp | 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). - */ - grepInvert?: RegExp | RegExp[]; - /** - * The 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](https://playwright.dev/docs/test-cli) with the `--max-failures` and `-x` options. - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * maxFailures: process.env.CI ? 1 : 0, - * }; - * export default config; - * ``` - * - */ - maxFailures?: number; - /** - * Whether to preserve test output in the - * [testConfig.outputDir](https://playwright.dev/docs/api/class-testconfig#test-config-output-dir). 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. - */ - preserveOutput?: PreserveOutput; - /** - * Playwright Test supports running multiple test projects at the same time. See [TestProject] for more information. - */ - projects?: Project[]; - /** - * Whether to suppress stdio and stderr output from the tests. - */ - quiet?: boolean; /** * The list of reporters to use. Each reporter can be: * - A builtin reporter name like `'list'` or `'json'`. @@ -844,246 +456,6 @@ interface TestConfig { * */ reporter?: LiteralUnion<'list'|'dot'|'line'|'github'|'json'|'junit'|'null'|'html', string> | ReporterDescription[]; - /** - * Whether to report slow test files. Pass `null` to disable this feature. - * - * 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. - */ - reportSlowTests?: ReportSlowTests; - /** - * Shard tests and execute only the selected shard. Specify in the one-based form like `{ total: 5, current: 2 }`. - * - * Learn more about [parallelism and sharding](https://playwright.dev/docs/test-parallel) with Playwright Test. - */ - shard?: Shard; - /** - * Whether 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. - * - `'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](https://playwright.dev/docs/test-snapshots). - */ - updateSnapshots?: UpdateSnapshots; - /** - * Launch a development web server during the tests. - * - * If the port is specified, the server will wait for it to be available on `127.0.0.1` or `::1`, before running the tests. - * If the url is specified, the server will wait for the URL to return a 2xx 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`. - * - * > 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. - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig } from '@playwright/test'; - * const config: PlaywrightTestConfig = { - * webServer: { - * command: 'npm run start', - * port: 3000, - * timeout: 120 * 1000, - * reuseExistingServer: !process.env.CI, - * }, - * use: { - * baseURL: 'http://localhost:3000/', - * }, - * }; - * export default config; - * ``` - * - * Now you can use a relative path when navigating the page: - * - * ```ts - * // test.spec.ts - * import { test } from '@playwright/test'; - * - * test('test', async ({ page }) => { - * // This will result in http://localhost:3000/foo - * await page.goto('/foo'); - * }); - * ``` - * - */ - webServer?: WebServerConfig; - /** - * The maximum number of concurrent worker processes to use for parallelizing tests. - * - * 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 one half of the number of CPU cores. Learn more about [parallelism and sharding](https://playwright.dev/docs/test-parallel) with - * Playwright Test. - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * workers: 3, - * }; - * export default config; - * ``` - * - */ - workers?: number; - - /** - * Any JSON-serializable metadata that will be put directly to the test report. - */ - metadata?: any; - /** - * Config name is visible in the report and during test execution, unless overridden by - * [testProject.name](https://playwright.dev/docs/api/class-testproject#test-project-name). - */ - name?: string; - /** - * The base directory, relative to the config file, for snapshot files created with `toMatchSnapshot`. Defaults to - * [testConfig.testDir](https://playwright.dev/docs/api/class-testconfig#test-config-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(...pathSegments)](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; - /** - * The output directory for files created during test execution. Defaults to `/test-results`. - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig, devices } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * outputDir: './test-results', - * }; - * export default config; - * ``` - * - * This directory is cleaned at the start. When running a test, a unique subdirectory inside the - * [testConfig.outputDir](https://playwright.dev/docs/api/class-testconfig#test-config-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. - * - * ```ts - * 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'); - * }); - * ``` - * - */ - outputDir?: string; - /** - * The number of times to repeat each test, useful for debugging flaky tests. - */ - repeatEach?: number; - /** - * The maximum number of retry attempts given to failed tests. By default failing tests are not retried. Learn more about - * [test retries](https://playwright.dev/docs/test-retries#retries). - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * retries: 2, - * }; - * export default config; - * ``` - * - */ - retries?: number; - /** - * Directory that will be recursively scanned for test files. Defaults to the directory of the configuration file. - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * testDir: './tests/playwright', - * }; - * export default config; - * ``` - * - */ - 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. - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig, devices } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * testIgnore: '**\/test-assets/**', - * }; - * export default config; - * ``` - * - */ - testIgnore?: string | RegExp | (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 Test looks for files matching `.*(test|spec)\.(js|ts|mjs)`. - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig, devices } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * testMatch: /.*\.e2e\.js/, - * }; - * export default config; - * ``` - * - */ - testMatch?: string | RegExp | (string | RegExp)[]; - /** - * Timeout 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)](https://playwright.dev/docs/api/class-test#test-set-timeout). Learn more about - * [various timeouts](https://playwright.dev/docs/test-timeouts). - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * timeout: 5 * 60 * 1000, - * }; - * export default config; - * ``` - * - */ - timeout?: number; /** * Configuration for the `expect` assertion library. Learn more about [various timeouts](https://playwright.dev/docs/test-timeouts). * @@ -1131,7 +503,464 @@ interface TestConfig { */ maxDiffPixelRatio?: number; }; - };} + }; + + /** + * Whether to exit with an error if any tests or groups are marked as + * [test.only(title, testFunction)](https://playwright.dev/docs/api/class-test#test-only) or + * [test.describe.only(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-only). Useful on CI. + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * forbidOnly: !!process.env.CI, + * }; + * export default config; + * ``` + * + */ + 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. + */ + 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 [`TestConfig`] argument. + * + * Learn more about [global setup and teardown](https://playwright.dev/docs/test-advanced#global-setup-and-teardown). + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig, devices } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * globalSetup: './global-setup', + * }; + * export default config; + * ``` + * + */ + globalSetup?: 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). + * + * Learn more about [global setup and teardown](https://playwright.dev/docs/test-advanced#global-setup-and-teardown). + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig, devices } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * globalTeardown: './global-teardown', + * }; + * export default config; + * ``` + * + */ + globalTeardown?: 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). + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * globalTimeout: process.env.CI ? 60 * 60 * 1000 : undefined, + * }; + * export default config; + * ``` + * + */ + 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. + * + * `grep` option is also useful for [tagging tests](https://playwright.dev/docs/test-annotations#tag-tests). + */ + grep?: RegExp|Array; + + /** + * 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). + */ + grepInvert?: RegExp|Array; + + /** + * The 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](https://playwright.dev/docs/test-cli) with the `--max-failures` and `-x` options. + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * maxFailures: process.env.CI ? 1 : 0, + * }; + * export default config; + * ``` + * + */ + maxFailures?: number; + + /** + * Any JSON-serializable metadata that will be put directly to the test report. + */ + metadata?: any; + + /** + * Config name is visible in the report and during test execution, unless overridden by + * [testProject.name](https://playwright.dev/docs/api/class-testproject#test-project-name). + */ + name?: string; + + /** + * The output directory for files created during test execution. Defaults to `/test-results`. + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig, devices } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * outputDir: './test-results', + * }; + * export default config; + * ``` + * + * This directory is cleaned at the start. When running a test, a unique subdirectory inside the + * [testConfig.outputDir](https://playwright.dev/docs/api/class-testconfig#test-config-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. + * + * ```ts + * 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'); + * }); + * ``` + * + */ + outputDir?: string; + + /** + * The base directory, relative to the config file, for snapshot files created with `toMatchSnapshot`. Defaults to + * [testConfig.testDir](https://playwright.dev/docs/api/class-testconfig#test-config-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(...pathSegments)](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; + + /** + * Whether to preserve test output in the + * [testConfig.outputDir](https://playwright.dev/docs/api/class-testconfig#test-config-output-dir). 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. + */ + preserveOutput?: "always"|"never"|"failures-only"; + + /** + * Playwright Test supports running multiple test projects at the same time. See [TestProject] for more information. + */ + projects?: Array; + + /** + * Whether to suppress stdio and stderr output from the tests. + */ + quiet?: boolean; + + /** + * The number of times to repeat each test, useful for debugging flaky tests. + */ + repeatEach?: number; + + /** + * Whether to report slow test files. Pass `null` to disable this feature. + * + * 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. + */ + reportSlowTests?: null|{ + /** + * The maximum number of slow test files to report. Defaults to `5`. + */ + max: number; + + /** + * Test duration in milliseconds that is considered slow. Defaults to 15 seconds. + */ + threshold: number; + }; + + /** + * The maximum number of retry attempts given to failed tests. By default failing tests are not retried. Learn more about + * [test retries](https://playwright.dev/docs/test-retries#retries). + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * retries: 2, + * }; + * export default config; + * ``` + * + */ + retries?: number; + + /** + * Shard tests and execute only the selected shard. Specify in the one-based form like `{ total: 5, current: 2 }`. + * + * Learn more about [parallelism and sharding](https://playwright.dev/docs/test-parallel) with Playwright Test. + */ + shard?: null|{ + /** + * The total number of shards. + */ + total: number; + + /** + * The index of the shard to execute, one-based. + */ + current: number; + }; + + /** + * Directory that will be recursively scanned for test files. Defaults to the directory of the configuration file. + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * testDir: './tests/playwright', + * }; + * export default config; + * ``` + * + */ + 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. + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig, devices } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * testIgnore: '**\/test-assets/**', + * }; + * export default config; + * ``` + * + */ + testIgnore?: string|RegExp|Array; + + /** + * 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 Test looks for files matching `.*(test|spec)\.(js|ts|mjs)`. + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig, devices } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * testMatch: /.*\.e2e\.js/, + * }; + * export default config; + * ``` + * + */ + testMatch?: string|RegExp|Array; + + /** + * Timeout 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)](https://playwright.dev/docs/api/class-test#test-set-timeout). Learn more about + * [various timeouts](https://playwright.dev/docs/test-timeouts). + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * timeout: 5 * 60 * 1000, + * }; + * export default config; + * ``` + * + */ + timeout?: number; + + /** + * Whether 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. + * - `'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](https://playwright.dev/docs/test-snapshots). + */ + updateSnapshots?: "all"|"none"|"missing"; + + /** + * Launch a development web server during the tests. + * + * If the port is specified, the server will wait for it to be available on `127.0.0.1` or `::1`, before running the tests. + * If the url is specified, the server will wait for the URL to return a 2xx 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`. + * + * > 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. + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig } from '@playwright/test'; + * const config: PlaywrightTestConfig = { + * webServer: { + * command: 'npm run start', + * port: 3000, + * timeout: 120 * 1000, + * reuseExistingServer: !process.env.CI, + * }, + * use: { + * baseURL: 'http://localhost:3000/', + * }, + * }; + * export default config; + * ``` + * + * Now you can use a relative path when navigating the page: + * + * ```ts + * // test.spec.ts + * import { test } from '@playwright/test'; + * + * test('test', async ({ page }) => { + * // This will result in http://localhost:3000/foo + * await page.goto('/foo'); + * }); + * ``` + * + */ + webServer?: { + /** + * Shell command to start. For example `npm run start`.. + */ + command: string; + + /** + * The port that your http server is expected to appear on. It does wait until it accepts connections. Exactly one of + * `port` or `url` is required. + */ + port?: number; + + /** + * The url on your http server that is expected to return a 2xx status code when the server is ready to accept connections. + * Exactly one of `port` or `url` is required. + */ + url?: string; + + /** + * Whether to ignore HTTPS errors when fetching the `url`. Defaults to `false`. + */ + ignoreHTTPSErrors?: boolean; + + /** + * How long to wait for the process to start up and be available in milliseconds. Defaults to 60000. + */ + timeout?: number; + + /** + * If true, it will re-use an existing server on the `port` or `url` when available. If no server is running on that `port` + * or `url`, it will run the command to start a new server. If `false`, it will throw if an existing process is listening + * on the `port` or `url`. This should be commonly set to `!process.env.CI` to allow the local dev server when running + * tests locally. + */ + reuseExistingServer?: boolean; + + /** + * Current working directory of the spawned process, `process.cwd()` by default. + */ + cwd?: string; + + /** + * Environment variables to set for the command, `process.env` by default. + */ + env?: { [key: string]: string; }; + }; + + /** + * The maximum number of concurrent worker processes to use for parallelizing tests. + * + * 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 one half of the number of CPU cores. Learn more about [parallelism and sharding](https://playwright.dev/docs/test-parallel) with + * Playwright Test. + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * workers: 3, + * }; + * export default config; + * ``` + * + */ + workers?: number;} /** * Playwright Test provides many options to configure how your tests are collected and executed, for example `timeout` or @@ -3892,4 +3721,279 @@ export interface TestError { value?: string; } +/** + * 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. + * + * `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] are available in the top-level + * [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. + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig, devices } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * // Options shared for all projects. + * timeout: 30000, + * use: { + * ignoreHTTPSErrors: true, + * }, + * + * // Options specific to each project. + * projects: [ + * { + * name: 'Desktop Chromium', + * use: { + * browserName: 'chromium', + * viewport: { width: 1280, height: 720 }, + * }, + * }, + * { + * name: 'Desktop Safari', + * use: { + * browserName: 'webkit', + * viewport: { width: 1280, height: 720 }, + * } + * }, + * { + * name: 'Desktop Firefox', + * use: { + * browserName: 'firefox', + * viewport: { width: 1280, height: 720 }, + * } + * }, + * { + * name: 'Mobile Chrome', + * use: devices['Pixel 5'], + * }, + * { + * name: 'Mobile Safari', + * use: devices['iPhone 12'], + * }, + * ], + * }; + * export default config; + * ``` + * + */ +interface TestProject { + /** + * 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 + * [screenshotAssertions.toMatchSnapshot(name[, options])](https://playwright.dev/docs/api/class-screenshotassertions#screenshot-assertions-to-match-snapshot-1) + * method. + */ + toMatchSnapshot?: { + /** + * an acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the same + * pixel in compared images, between zero (strict) and one (lax). Defaults 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; + }; + }; + + /** + * 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. + * + * `grep` option is also useful for [tagging tests](https://playwright.dev/docs/test-annotations#tag-tests). + */ + grep?: RegExp|Array; + + /** + * Filter to only run tests with a title **not** matching one 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; + + /** + * Any JSON-serializable metadata that will be put directly to the test report. + */ + metadata?: any; + + /** + * Project name is visible in the report and during test execution. + */ + name?: string; + + /** + * 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(...pathSegments)](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; + + /** + * The output directory for files created during test execution. Defaults to `/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. + * + * ```ts + * 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; + + /** + * The maximum number of retry attempts given to failed tests. Learn more about [test retries](https://playwright.dev/docs/test-retries#retries). + * + * Use [testConfig.retries](https://playwright.dev/docs/api/class-testconfig#test-config-retries) to change this option for + * all projects. + */ + retries?: number; + + /** + * 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. + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * 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', + * } + * }, + * ], + * }; + * export default config; + * ``` + * + * 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; + + /** + * 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 Test looks for files matching `.*(test|spec)\.(js|ts|mjs)`. + * + * 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; + + /** + * Timeout 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)](https://playwright.dev/docs/api/class-test#test-set-timeout). + * + * Use [testConfig.timeout](https://playwright.dev/docs/api/class-testconfig#test-config-timeout) to change this option for + * all projects. + */ + timeout?: number; +} + diff --git a/tests/config/experimental.d.ts b/tests/config/experimental.d.ts index 3ada8dd771..3e55025be0 100644 --- a/tests/config/experimental.d.ts +++ b/tests/config/experimental.d.ts @@ -16164,350 +16164,6 @@ export type UpdateSnapshots = 'all' | 'none' | 'missing'; type UseOptions = { [K in keyof WorkerArgs]?: WorkerArgs[K] } & { [K in keyof TestArgs]?: TestArgs[K] }; -/** - * 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. - * - * `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] are available in the top-level - * [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. - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig, devices } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * // Options shared for all projects. - * timeout: 30000, - * use: { - * ignoreHTTPSErrors: true, - * }, - * - * // Options specific to each project. - * projects: [ - * { - * name: 'Desktop Chromium', - * use: { - * browserName: 'chromium', - * viewport: { width: 1280, height: 720 }, - * }, - * }, - * { - * name: 'Desktop Safari', - * use: { - * browserName: 'webkit', - * viewport: { width: 1280, height: 720 }, - * } - * }, - * { - * name: 'Desktop Firefox', - * use: { - * browserName: 'firefox', - * viewport: { width: 1280, height: 720 }, - * } - * }, - * { - * name: 'Mobile Chrome', - * use: devices['Pixel 5'], - * }, - * { - * name: 'Mobile Safari', - * use: devices['iPhone 12'], - * }, - * ], - * }; - * export default config; - * ``` - * - */ -interface TestProject { - /** - * 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. - * - * `grep` option is also useful for [tagging tests](https://playwright.dev/docs/test-annotations#tag-tests). - */ - grep?: RegExp | RegExp[]; - /** - * Filter to only run tests with a title **not** matching one 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 | RegExp[] | null; - /** - * Any JSON-serializable metadata that will be put directly to the test report. - */ - metadata?: any; - /** - * Project name is visible in the report and during test execution. - */ - name?: string; - /** - * 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(...pathSegments)](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; - /** - * The output directory for files created during test execution. Defaults to `/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. - * - * ```ts - * 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; - /** - * The maximum number of retry attempts given to failed tests. Learn more about [test retries](https://playwright.dev/docs/test-retries#retries). - * - * Use [testConfig.retries](https://playwright.dev/docs/api/class-testconfig#test-config-retries) to change this option for - * all projects. - */ - retries?: number; - /** - * 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. - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * 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', - * } - * }, - * ], - * }; - * export default config; - * ``` - * - * 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 | (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 Test looks for files matching `.*(test|spec)\.(js|ts|mjs)`. - * - * Use [testConfig.testMatch](https://playwright.dev/docs/api/class-testconfig#test-config-test-match) to change this - * option for all projects. - */ - testMatch?: string | RegExp | (string | RegExp)[]; - /** - * Timeout 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)](https://playwright.dev/docs/api/class-test#test-set-timeout). - * - * Use [testConfig.timeout](https://playwright.dev/docs/api/class-testconfig#test-config-timeout) to change this option for - * all projects. - */ - timeout?: number; - /** - * 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 - * [pageAssertions.toHaveScreenshot([options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot) - * method. - */ - toHaveScreenshot?: { - /** - * an acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the same - * pixel in compared images, between zero (strict) and one (lax). Defaults 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` in [page.screenshot([options])](https://playwright.dev/docs/api/class-page#page-screenshot). Defaults - * to `"disable"`. - */ - animations?: "allow"|"disable"; - - /** - * See `caret` in [page.screenshot([options])](https://playwright.dev/docs/api/class-page#page-screenshot). Defaults to - * `"hide"`. - */ - caret?: "hide"|"initial"; - - /** - * See `fonts` in [page.screenshot([options])](https://playwright.dev/docs/api/class-page#page-screenshot). Defaults to - * `"ready"`. - */ - fonts?: "ready"|"nowait"; - - /** - * See `scale` in [page.screenshot([options])](https://playwright.dev/docs/api/class-page#page-screenshot). Defaults to - * `"css"`. - */ - scale?: "css"|"device"; - }; - - /** - * Configuration for the - * [screenshotAssertions.toMatchSnapshot(name[, options])](https://playwright.dev/docs/api/class-screenshotassertions#screenshot-assertions-to-match-snapshot-1) - * method. - */ - toMatchSnapshot?: { - /** - * an acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the same - * pixel in compared images, between zero (strict) and one (lax). Defaults 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; - }; - }; - - /** - * The base directory, relative to the config file, for screenshot files created with `toHaveScreenshot`. Defaults to - * - * ``` - * /__screenshots__// - * ``` - * - * This path will serve as the base directory for each test file screenshot directory. For example, the following test - * structure: - * - * ``` - * smoke-tests/ - * └── basic.spec.ts - * ``` - * - * will result in the following screenshots folder structure: - * - * ``` - * __screenshots__/ - * └── darwin/ - * ├── Mobile Safari/ - * │ └── smoke-tests/ - * │ └── basic.spec.ts/ - * │ └── screenshot-expectation.png - * └── Desktop Chrome/ - * └── smoke-tests/ - * └── basic.spec.ts/ - * └── screenshot-expectation.png - * ``` - * - * where: - * - `darwin/` - a platform name folder - * - `Mobile Safari` and `Desktop Chrome` - project names - */ - screenshotsDir?: string;} - /** * 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. @@ -16906,133 +16562,6 @@ type LiteralUnion = T | (U & { zz_IGNORE_ME?: never }); * */ interface TestConfig { - /** - * Whether to exit with an error if any tests or groups are marked as - * [test.only(title, testFunction)](https://playwright.dev/docs/api/class-test#test-only) or - * [test.describe.only(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-only). Useful on CI. - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * forbidOnly: !!process.env.CI, - * }; - * export default config; - * ``` - * - */ - 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. - */ - 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 [`TestConfig`] argument. - * - * Learn more about [global setup and teardown](https://playwright.dev/docs/test-advanced#global-setup-and-teardown). - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig, devices } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * globalSetup: './global-setup', - * }; - * export default config; - * ``` - * - */ - globalSetup?: 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). - * - * Learn more about [global setup and teardown](https://playwright.dev/docs/test-advanced#global-setup-and-teardown). - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig, devices } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * globalTeardown: './global-teardown', - * }; - * export default config; - * ``` - * - */ - globalTeardown?: 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). - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * globalTimeout: process.env.CI ? 60 * 60 * 1000 : undefined, - * }; - * export default config; - * ``` - * - */ - 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. - * - * `grep` option is also useful for [tagging tests](https://playwright.dev/docs/test-annotations#tag-tests). - */ - grep?: RegExp | 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). - */ - grepInvert?: RegExp | RegExp[]; - /** - * The 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](https://playwright.dev/docs/test-cli) with the `--max-failures` and `-x` options. - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * maxFailures: process.env.CI ? 1 : 0, - * }; - * export default config; - * ``` - * - */ - maxFailures?: number; - /** - * Whether to preserve test output in the - * [testConfig.outputDir](https://playwright.dev/docs/api/class-testconfig#test-config-output-dir). 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. - */ - preserveOutput?: PreserveOutput; - /** - * Playwright Test supports running multiple test projects at the same time. See [TestProject] for more information. - */ - projects?: Project[]; - /** - * Whether to suppress stdio and stderr output from the tests. - */ - quiet?: boolean; /** * The list of reporters to use. Each reporter can be: * - A builtin reporter name like `'list'` or `'json'`. @@ -17055,246 +16584,6 @@ interface TestConfig { * */ reporter?: LiteralUnion<'list'|'dot'|'line'|'github'|'json'|'junit'|'null'|'html', string> | ReporterDescription[]; - /** - * Whether to report slow test files. Pass `null` to disable this feature. - * - * 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. - */ - reportSlowTests?: ReportSlowTests; - /** - * Shard tests and execute only the selected shard. Specify in the one-based form like `{ total: 5, current: 2 }`. - * - * Learn more about [parallelism and sharding](https://playwright.dev/docs/test-parallel) with Playwright Test. - */ - shard?: Shard; - /** - * Whether 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. - * - `'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](https://playwright.dev/docs/test-snapshots). - */ - updateSnapshots?: UpdateSnapshots; - /** - * Launch a development web server during the tests. - * - * If the port is specified, the server will wait for it to be available on `127.0.0.1` or `::1`, before running the tests. - * If the url is specified, the server will wait for the URL to return a 2xx 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`. - * - * > 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. - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig } from '@playwright/test'; - * const config: PlaywrightTestConfig = { - * webServer: { - * command: 'npm run start', - * port: 3000, - * timeout: 120 * 1000, - * reuseExistingServer: !process.env.CI, - * }, - * use: { - * baseURL: 'http://localhost:3000/', - * }, - * }; - * export default config; - * ``` - * - * Now you can use a relative path when navigating the page: - * - * ```ts - * // test.spec.ts - * import { test } from '@playwright/test'; - * - * test('test', async ({ page }) => { - * // This will result in http://localhost:3000/foo - * await page.goto('/foo'); - * }); - * ``` - * - */ - webServer?: WebServerConfig; - /** - * The maximum number of concurrent worker processes to use for parallelizing tests. - * - * 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 one half of the number of CPU cores. Learn more about [parallelism and sharding](https://playwright.dev/docs/test-parallel) with - * Playwright Test. - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * workers: 3, - * }; - * export default config; - * ``` - * - */ - workers?: number; - - /** - * Any JSON-serializable metadata that will be put directly to the test report. - */ - metadata?: any; - /** - * Config name is visible in the report and during test execution, unless overridden by - * [testProject.name](https://playwright.dev/docs/api/class-testproject#test-project-name). - */ - name?: string; - /** - * The base directory, relative to the config file, for snapshot files created with `toMatchSnapshot`. Defaults to - * [testConfig.testDir](https://playwright.dev/docs/api/class-testconfig#test-config-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(...pathSegments)](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; - /** - * The output directory for files created during test execution. Defaults to `/test-results`. - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig, devices } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * outputDir: './test-results', - * }; - * export default config; - * ``` - * - * This directory is cleaned at the start. When running a test, a unique subdirectory inside the - * [testConfig.outputDir](https://playwright.dev/docs/api/class-testconfig#test-config-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. - * - * ```ts - * 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'); - * }); - * ``` - * - */ - outputDir?: string; - /** - * The number of times to repeat each test, useful for debugging flaky tests. - */ - repeatEach?: number; - /** - * The maximum number of retry attempts given to failed tests. By default failing tests are not retried. Learn more about - * [test retries](https://playwright.dev/docs/test-retries#retries). - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * retries: 2, - * }; - * export default config; - * ``` - * - */ - retries?: number; - /** - * Directory that will be recursively scanned for test files. Defaults to the directory of the configuration file. - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * testDir: './tests/playwright', - * }; - * export default config; - * ``` - * - */ - 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. - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig, devices } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * testIgnore: '**\/test-assets/**', - * }; - * export default config; - * ``` - * - */ - testIgnore?: string | RegExp | (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 Test looks for files matching `.*(test|spec)\.(js|ts|mjs)`. - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig, devices } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * testMatch: /.*\.e2e\.js/, - * }; - * export default config; - * ``` - * - */ - testMatch?: string | RegExp | (string | RegExp)[]; - /** - * Timeout 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)](https://playwright.dev/docs/api/class-test#test-set-timeout). Learn more about - * [various timeouts](https://playwright.dev/docs/test-timeouts). - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * timeout: 5 * 60 * 1000, - * }; - * export default config; - * ``` - * - */ - timeout?: number; /** * Configuration for the `expect` assertion library. Learn more about [various timeouts](https://playwright.dev/docs/test-timeouts). * @@ -17391,6 +16680,245 @@ interface TestConfig { }; }; + /** + * Whether to exit with an error if any tests or groups are marked as + * [test.only(title, testFunction)](https://playwright.dev/docs/api/class-test#test-only) or + * [test.describe.only(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-only). Useful on CI. + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * forbidOnly: !!process.env.CI, + * }; + * export default config; + * ``` + * + */ + 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. + */ + 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 [`TestConfig`] argument. + * + * Learn more about [global setup and teardown](https://playwright.dev/docs/test-advanced#global-setup-and-teardown). + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig, devices } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * globalSetup: './global-setup', + * }; + * export default config; + * ``` + * + */ + globalSetup?: 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). + * + * Learn more about [global setup and teardown](https://playwright.dev/docs/test-advanced#global-setup-and-teardown). + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig, devices } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * globalTeardown: './global-teardown', + * }; + * export default config; + * ``` + * + */ + globalTeardown?: 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). + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * globalTimeout: process.env.CI ? 60 * 60 * 1000 : undefined, + * }; + * export default config; + * ``` + * + */ + 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. + * + * `grep` option is also useful for [tagging tests](https://playwright.dev/docs/test-annotations#tag-tests). + */ + grep?: RegExp|Array; + + /** + * 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). + */ + grepInvert?: RegExp|Array; + + /** + * The 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](https://playwright.dev/docs/test-cli) with the `--max-failures` and `-x` options. + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * maxFailures: process.env.CI ? 1 : 0, + * }; + * export default config; + * ``` + * + */ + maxFailures?: number; + + /** + * Any JSON-serializable metadata that will be put directly to the test report. + */ + metadata?: any; + + /** + * Config name is visible in the report and during test execution, unless overridden by + * [testProject.name](https://playwright.dev/docs/api/class-testproject#test-project-name). + */ + name?: string; + + /** + * The output directory for files created during test execution. Defaults to `/test-results`. + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig, devices } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * outputDir: './test-results', + * }; + * export default config; + * ``` + * + * This directory is cleaned at the start. When running a test, a unique subdirectory inside the + * [testConfig.outputDir](https://playwright.dev/docs/api/class-testconfig#test-config-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. + * + * ```ts + * 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'); + * }); + * ``` + * + */ + outputDir?: string; + + /** + * The base directory, relative to the config file, for snapshot files created with `toMatchSnapshot`. Defaults to + * [testConfig.testDir](https://playwright.dev/docs/api/class-testconfig#test-config-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(...pathSegments)](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; + + /** + * Whether to preserve test output in the + * [testConfig.outputDir](https://playwright.dev/docs/api/class-testconfig#test-config-output-dir). 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. + */ + preserveOutput?: "always"|"never"|"failures-only"; + + /** + * Playwright Test supports running multiple test projects at the same time. See [TestProject] for more information. + */ + projects?: Array; + + /** + * Whether to suppress stdio and stderr output from the tests. + */ + quiet?: boolean; + + /** + * The number of times to repeat each test, useful for debugging flaky tests. + */ + repeatEach?: number; + + /** + * Whether to report slow test files. Pass `null` to disable this feature. + * + * 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. + */ + reportSlowTests?: null|{ + /** + * The maximum number of slow test files to report. Defaults to `5`. + */ + max: number; + + /** + * Test duration in milliseconds that is considered slow. Defaults to 15 seconds. + */ + threshold: number; + }; + + /** + * The maximum number of retry attempts given to failed tests. By default failing tests are not retried. Learn more about + * [test retries](https://playwright.dev/docs/test-retries#retries). + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * retries: 2, + * }; + * export default config; + * ``` + * + */ + retries?: number; + /** * The base directory, relative to the config file, for screenshot files created with * [pageAssertions.toHaveScreenshot([options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot). @@ -17427,7 +16955,225 @@ interface TestConfig { * - `darwin/` - a platform name folder * - `Mobile Safari` and `Desktop Chrome` - project names */ - screenshotsDir?: string;} + screenshotsDir?: string; + + /** + * Shard tests and execute only the selected shard. Specify in the one-based form like `{ total: 5, current: 2 }`. + * + * Learn more about [parallelism and sharding](https://playwright.dev/docs/test-parallel) with Playwright Test. + */ + shard?: null|{ + /** + * The total number of shards. + */ + total: number; + + /** + * The index of the shard to execute, one-based. + */ + current: number; + }; + + /** + * Directory that will be recursively scanned for test files. Defaults to the directory of the configuration file. + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * testDir: './tests/playwright', + * }; + * export default config; + * ``` + * + */ + 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. + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig, devices } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * testIgnore: '**\/test-assets/**', + * }; + * export default config; + * ``` + * + */ + testIgnore?: string|RegExp|Array; + + /** + * 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 Test looks for files matching `.*(test|spec)\.(js|ts|mjs)`. + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig, devices } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * testMatch: /.*\.e2e\.js/, + * }; + * export default config; + * ``` + * + */ + testMatch?: string|RegExp|Array; + + /** + * Timeout 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)](https://playwright.dev/docs/api/class-test#test-set-timeout). Learn more about + * [various timeouts](https://playwright.dev/docs/test-timeouts). + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * timeout: 5 * 60 * 1000, + * }; + * export default config; + * ``` + * + */ + timeout?: number; + + /** + * Whether 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. + * - `'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](https://playwright.dev/docs/test-snapshots). + */ + updateSnapshots?: "all"|"none"|"missing"; + + /** + * Launch a development web server during the tests. + * + * If the port is specified, the server will wait for it to be available on `127.0.0.1` or `::1`, before running the tests. + * If the url is specified, the server will wait for the URL to return a 2xx 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`. + * + * > 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. + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig } from '@playwright/test'; + * const config: PlaywrightTestConfig = { + * webServer: { + * command: 'npm run start', + * port: 3000, + * timeout: 120 * 1000, + * reuseExistingServer: !process.env.CI, + * }, + * use: { + * baseURL: 'http://localhost:3000/', + * }, + * }; + * export default config; + * ``` + * + * Now you can use a relative path when navigating the page: + * + * ```ts + * // test.spec.ts + * import { test } from '@playwright/test'; + * + * test('test', async ({ page }) => { + * // This will result in http://localhost:3000/foo + * await page.goto('/foo'); + * }); + * ``` + * + */ + webServer?: { + /** + * Shell command to start. For example `npm run start`.. + */ + command: string; + + /** + * The port that your http server is expected to appear on. It does wait until it accepts connections. Exactly one of + * `port` or `url` is required. + */ + port?: number; + + /** + * The url on your http server that is expected to return a 2xx status code when the server is ready to accept connections. + * Exactly one of `port` or `url` is required. + */ + url?: string; + + /** + * Whether to ignore HTTPS errors when fetching the `url`. Defaults to `false`. + */ + ignoreHTTPSErrors?: boolean; + + /** + * How long to wait for the process to start up and be available in milliseconds. Defaults to 60000. + */ + timeout?: number; + + /** + * If true, it will re-use an existing server on the `port` or `url` when available. If no server is running on that `port` + * or `url`, it will run the command to start a new server. If `false`, it will throw if an existing process is listening + * on the `port` or `url`. This should be commonly set to `!process.env.CI` to allow the local dev server when running + * tests locally. + */ + reuseExistingServer?: boolean; + + /** + * Current working directory of the spawned process, `process.cwd()` by default. + */ + cwd?: string; + + /** + * Environment variables to set for the command, `process.env` by default. + */ + env?: { [key: string]: string; }; + }; + + /** + * The maximum number of concurrent worker processes to use for parallelizing tests. + * + * 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 one half of the number of CPU cores. Learn more about [parallelism and sharding](https://playwright.dev/docs/test-parallel) with + * Playwright Test. + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * workers: 3, + * }; + * export default config; + * ``` + * + */ + workers?: number;} /** * Playwright Test provides many options to configure how your tests are collected and executed, for example `timeout` or @@ -20374,6 +20120,364 @@ export interface TestError { value?: string; } +/** + * 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. + * + * `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] are available in the top-level + * [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. + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig, devices } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * // Options shared for all projects. + * timeout: 30000, + * use: { + * ignoreHTTPSErrors: true, + * }, + * + * // Options specific to each project. + * projects: [ + * { + * name: 'Desktop Chromium', + * use: { + * browserName: 'chromium', + * viewport: { width: 1280, height: 720 }, + * }, + * }, + * { + * name: 'Desktop Safari', + * use: { + * browserName: 'webkit', + * viewport: { width: 1280, height: 720 }, + * } + * }, + * { + * name: 'Desktop Firefox', + * use: { + * browserName: 'firefox', + * viewport: { width: 1280, height: 720 }, + * } + * }, + * { + * name: 'Mobile Chrome', + * use: devices['Pixel 5'], + * }, + * { + * name: 'Mobile Safari', + * use: devices['iPhone 12'], + * }, + * ], + * }; + * export default config; + * ``` + * + */ +interface TestProject { + /** + * 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 + * [pageAssertions.toHaveScreenshot([options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot) + * method. + */ + toHaveScreenshot?: { + /** + * an acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the same + * pixel in compared images, between zero (strict) and one (lax). Defaults 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` in [page.screenshot([options])](https://playwright.dev/docs/api/class-page#page-screenshot). Defaults + * to `"disable"`. + */ + animations?: "allow"|"disable"; + + /** + * See `caret` in [page.screenshot([options])](https://playwright.dev/docs/api/class-page#page-screenshot). Defaults to + * `"hide"`. + */ + caret?: "hide"|"initial"; + + /** + * See `fonts` in [page.screenshot([options])](https://playwright.dev/docs/api/class-page#page-screenshot). Defaults to + * `"ready"`. + */ + fonts?: "ready"|"nowait"; + + /** + * See `scale` in [page.screenshot([options])](https://playwright.dev/docs/api/class-page#page-screenshot). Defaults to + * `"css"`. + */ + scale?: "css"|"device"; + }; + + /** + * Configuration for the + * [screenshotAssertions.toMatchSnapshot(name[, options])](https://playwright.dev/docs/api/class-screenshotassertions#screenshot-assertions-to-match-snapshot-1) + * method. + */ + toMatchSnapshot?: { + /** + * an acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the same + * pixel in compared images, between zero (strict) and one (lax). Defaults 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; + }; + }; + + /** + * 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. + * + * `grep` option is also useful for [tagging tests](https://playwright.dev/docs/test-annotations#tag-tests). + */ + grep?: RegExp|Array; + + /** + * Filter to only run tests with a title **not** matching one 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; + + /** + * Any JSON-serializable metadata that will be put directly to the test report. + */ + metadata?: any; + + /** + * Project name is visible in the report and during test execution. + */ + name?: string; + + /** + * The base directory, relative to the config file, for screenshot files created with `toHaveScreenshot`. Defaults to + * + * ``` + * /__screenshots__// + * ``` + * + * This path will serve as the base directory for each test file screenshot directory. For example, the following test + * structure: + * + * ``` + * smoke-tests/ + * └── basic.spec.ts + * ``` + * + * will result in the following screenshots folder structure: + * + * ``` + * __screenshots__/ + * └── darwin/ + * ├── Mobile Safari/ + * │ └── smoke-tests/ + * │ └── basic.spec.ts/ + * │ └── screenshot-expectation.png + * └── Desktop Chrome/ + * └── smoke-tests/ + * └── basic.spec.ts/ + * └── screenshot-expectation.png + * ``` + * + * where: + * - `darwin/` - a platform name folder + * - `Mobile Safari` and `Desktop Chrome` - project names + */ + screenshotsDir?: string; + + /** + * 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(...pathSegments)](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; + + /** + * The output directory for files created during test execution. Defaults to `/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. + * + * ```ts + * 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; + + /** + * The maximum number of retry attempts given to failed tests. Learn more about [test retries](https://playwright.dev/docs/test-retries#retries). + * + * Use [testConfig.retries](https://playwright.dev/docs/api/class-testconfig#test-config-retries) to change this option for + * all projects. + */ + retries?: number; + + /** + * 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. + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * 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', + * } + * }, + * ], + * }; + * export default config; + * ``` + * + * 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; + + /** + * 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 Test looks for files matching `.*(test|spec)\.(js|ts|mjs)`. + * + * 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; + + /** + * Timeout 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)](https://playwright.dev/docs/api/class-test#test-set-timeout). + * + * Use [testConfig.timeout](https://playwright.dev/docs/api/class-testconfig#test-config-timeout) to change this option for + * all projects. + */ + timeout?: number; +} + } diff --git a/utils/generate_types/index.js b/utils/generate_types/index.js index 491464c3ed..becb935020 100644 --- a/utils/generate_types/index.js +++ b/utils/generate_types/index.js @@ -574,7 +574,7 @@ class TypesGenerator { 'PlaywrightWorkerArgs.playwright', 'Matchers', ]), - doNotExportClassNames: new Set(assertionClasses), + doNotExportClassNames: new Set([...assertionClasses, 'TestProject']), includeExperimental, }); return await generator.generateTypes(path.join(__dirname, 'overrides-test.d.ts')); diff --git a/utils/generate_types/overrides-test.d.ts b/utils/generate_types/overrides-test.d.ts index 9c13b2019b..4e14294562 100644 --- a/utils/generate_types/overrides-test.d.ts +++ b/utils/generate_types/overrides-test.d.ts @@ -35,22 +35,6 @@ export type UpdateSnapshots = 'all' | 'none' | 'missing'; type UseOptions = { [K in keyof WorkerArgs]?: WorkerArgs[K] } & { [K in keyof TestArgs]?: TestArgs[K] }; -interface TestProject { - fullyParallel?: boolean; - grep?: RegExp | RegExp[]; - grepInvert?: RegExp | RegExp[] | null; - metadata?: any; - name?: string; - snapshotDir?: string; - outputDir?: string; - repeatEach?: number; - retries?: number; - testDir?: string; - testIgnore?: string | RegExp | (string | RegExp)[]; - testMatch?: string | RegExp | (string | RegExp)[]; - timeout?: number; -} - export interface Project extends TestProject { use?: UseOptions; } @@ -118,34 +102,7 @@ export type WebServerConfig = { type LiteralUnion = T | (U & { zz_IGNORE_ME?: never }); interface TestConfig { - forbidOnly?: boolean; - fullyParallel?: boolean; - globalSetup?: string; - globalTeardown?: string; - globalTimeout?: number; - grep?: RegExp | RegExp[]; - grepInvert?: RegExp | RegExp[]; - maxFailures?: number; - preserveOutput?: PreserveOutput; - projects?: Project[]; - quiet?: boolean; reporter?: LiteralUnion<'list'|'dot'|'line'|'github'|'json'|'junit'|'null'|'html', string> | ReporterDescription[]; - reportSlowTests?: ReportSlowTests; - shard?: Shard; - updateSnapshots?: UpdateSnapshots; - webServer?: WebServerConfig; - workers?: number; - - metadata?: any; - name?: string; - snapshotDir?: string; - outputDir?: string; - repeatEach?: number; - retries?: number; - testDir?: string; - testIgnore?: string | RegExp | (string | RegExp)[]; - testMatch?: string | RegExp | (string | RegExp)[]; - timeout?: number; } export interface Config extends TestConfig {