From e2f7acea1e76cbcb1d957e8887dcdde9edd51f14 Mon Sep 17 00:00:00 2001 From: Yury Semikhatsky Date: Wed, 24 Apr 2024 15:18:43 -0700 Subject: [PATCH] docs: fix capitalization and alphabetic order in TestConfig (#30523) --- docs/src/api/params.md | 16 +-- docs/src/test-api/class-testconfig.md | 28 ++--- packages/playwright/types/test.d.ts | 150 +++++++++++++------------- 3 files changed, 97 insertions(+), 97 deletions(-) diff --git a/docs/src/api/params.md b/docs/src/api/params.md index e105f2fd14..9bc70c1232 100644 --- a/docs/src/api/params.md +++ b/docs/src/api/params.md @@ -1731,13 +1731,17 @@ test.describe('suite', () => { The list of supported tokens: -* `{testDir}` - Project's [`property: TestConfig.testDir`]. - * Value: `/home/playwright/tests` (absolute path is since `testDir` is resolved relative to directory with config) -* `{snapshotDir}` - Project's [`property: TestConfig.snapshotDir`]. - * Value: `/home/playwright/tests` (since `snapshotDir` is not provided in config, it defaults to `testDir`) +* `{arg}` - Relative snapshot path **without extension**. These come from the arguments passed to the `toHaveScreenshot()` and `toMatchSnapshot()` calls; if called without arguments, this will be an auto-generated snapshot name. + * Value: `foo/bar/baz` +* `{ext}` - snapshot extension (with dots) + * Value: `.png` * `{platform}` - The value of `process.platform`. * `{projectName}` - Project's file-system-sanitized name, if any. * Value: `''` (empty string). +* `{snapshotDir}` - Project's [`property: TestConfig.snapshotDir`]. + * Value: `/home/playwright/tests` (since `snapshotDir` is not provided in config, it defaults to `testDir`) +* `{testDir}` - Project's [`property: TestConfig.testDir`]. + * Value: `/home/playwright/tests` (absolute path is since `testDir` is resolved relative to directory with config) * `{testFileDir}` - Directories in relative path from `testDir` to **test file**. * Value: `page` * `{testFileName}` - Test file name with extension. @@ -1746,10 +1750,6 @@ The list of supported tokens: * Value: `page/page-click.spec.ts` * `{testName}` - File-system-sanitized test title, including parent describes but excluding file name. * Value: `suite-test-should-work` -* `{arg}` - Relative snapshot path **without extension**. These come from the arguments passed to the `toHaveScreenshot()` and `toMatchSnapshot()` calls; if called without arguments, this will be an auto-generated snapshot name. - * Value: `foo/bar/baz` -* `{ext}` - snapshot extension (with dots) - * Value: `.png` Each token can be preceded with a single character that will be used **only if** this token has non-empty value. diff --git a/docs/src/test-api/class-testconfig.md b/docs/src/test-api/class-testconfig.md index e19a11f815..a36b7437d2 100644 --- a/docs/src/test-api/class-testconfig.md +++ b/docs/src/test-api/class-testconfig.md @@ -41,20 +41,20 @@ export default defineConfig({ - type: ?<[Object]> - `timeout` ?<[int]> Default timeout for async expect matchers in milliseconds, defaults to 5000ms. - `toHaveScreenshot` ?<[Object]> Configuration for the [`method: PageAssertions.toHaveScreenshot#1`] method. - - `threshold` ?<[float]> an acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and `1` (lax). `"pixelmatch"` comparator computes color difference in [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`. - - `maxDiffPixels` ?<[int]> an acceptable amount of pixels that could be different, unset by default. - - `maxDiffPixelRatio` ?<[float]> an acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by default. - `animations` ?<[ScreenshotAnimations]<"allow"|"disabled">> See [`option: animations`] in [`method: Page.screenshot`]. Defaults to `"disabled"`. - `caret` ?<[ScreenshotCaret]<"hide"|"initial">> See [`option: caret`] in [`method: Page.screenshot`]. Defaults to `"hide"`. + - `maxDiffPixels` ?<[int]> An acceptable amount of pixels that could be different, unset by default. + - `maxDiffPixelRatio` ?<[float]> An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by default. - `scale` ?<[ScreenshotScale]<"css"|"device">> See [`option: scale`] in [`method: Page.screenshot`]. Defaults to `"css"`. - `stylePath` ?<[string]|[Array]<[string]>> See [`option: style`] in [`method: Page.screenshot`]. + - `threshold` ?<[float]> An acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and `1` (lax). `"pixelmatch"` comparator computes color difference in [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`. - `toMatchSnapshot` ?<[Object]> Configuration for the [`method: SnapshotAssertions.toMatchSnapshot#1`] method. - - `threshold` ?<[float]> an acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and `1` (lax). `"pixelmatch"` comparator computes color difference in [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`. - - `maxDiffPixels` ?<[int]> an acceptable amount of pixels that could be different, unset by default. - - `maxDiffPixelRatio` ?<[float]> an acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by default. + - `maxDiffPixels` ?<[int]> An acceptable amount of pixels that could be different, unset by default. + - `maxDiffPixelRatio` ?<[float]> An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by default. + - `threshold` ?<[float]> An acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and `1` (lax). `"pixelmatch"` comparator computes color difference in [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`. - `toPass` ?<[Object]> Configuration for the [expect(value).toPass()](../test-assertions.md#expecttopass) method. - - `timeout` ?<[int]> timeout for toPass method in milliseconds. - - `intervals` ?<[Array]<[int]>> probe intervals for toPass method in milliseconds. + - `intervals` ?<[Array]<[int]>> Probe intervals for toPass method in milliseconds. + - `timeout` ?<[int]> Timeout for toPass method in milliseconds. Configuration for the `expect` assertion library. Learn more about [various timeouts](../test-timeouts.md). @@ -458,8 +458,8 @@ export default defineConfig({ ## property: TestConfig.shard * since: v1.10 - type: ?<[null]|[Object]> - - `total` <[int]> The total number of shards. - `current` <[int]> The index of the shard to execute, one-based. + - `total` <[int]> The total number of shards. Shard tests and execute only the selected shard. Specify in the one-based form like `{ total: 5, current: 2 }`. @@ -589,15 +589,15 @@ export default defineConfig({ * since: v1.10 - type: ?<[Object]|[Array]<[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. Either `port` or `url` should be specified. - - `url` ?<[string]> The url on your http server that is expected to return a 2xx, 3xx, 400, 401, 402, or 403 status code when the server is ready to accept connections. Redirects (3xx status codes) are being followed and the new location is checked. Either `port` or `url` should be specified. + - `cwd` ?<[string]> Current working directory of the spawned process, defaults to the directory of the configuration file. + - `env` ?<[Object]<[string], [string]>> Environment variables to set for the command, `process.env` by default. - `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. + - `port` ?<[int]> The port that your http server is expected to appear on. It does wait until it accepts connections. Either `port` or `url` should be specified. - `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. - `stdout` ?<["pipe"|"ignore"]> If `"pipe"`, it will pipe the stdout of the command to the process stdout. If `"ignore"`, it will ignore the stdout of the command. Default to `"ignore"`. - `stderr` ?<["pipe"|"ignore"]> Whether to pipe the stderr of the command to the process stderr or ignore it. Defaults to `"pipe"`. - - `cwd` ?<[string]> Current working directory of the spawned process, defaults to the directory of the configuration file. - - `env` ?<[Object]<[string], [string]>> Environment variables to set for the command, `process.env` by default. + - `timeout` ?<[int]> How long to wait for the process to start up and be available in milliseconds. Defaults to 60000. + - `url` ?<[string]> The url on your http server that is expected to return a 2xx, 3xx, 400, 401, 402, or 403 status code when the server is ready to accept connections. Redirects (3xx status codes) are being followed and the new location is checked. Either `port` or `url` should be specified. Launch a development web server (or multiple) during the tests. diff --git a/packages/playwright/types/test.d.ts b/packages/playwright/types/test.d.ts index 1a31c166b9..993e7addd1 100644 --- a/packages/playwright/types/test.d.ts +++ b/packages/playwright/types/test.d.ts @@ -434,16 +434,22 @@ interface TestProject { * ``` * * The list of supported tokens: + * - `{arg}` - Relative snapshot path **without extension**. These come from the arguments passed to the + * `toHaveScreenshot()` and `toMatchSnapshot()` calls; if called without arguments, this will be an auto-generated + * snapshot name. + * - Value: `foo/bar/baz` + * - `{ext}` - snapshot extension (with dots) + * - Value: `.png` + * - `{platform}` - The value of `process.platform`. + * - `{projectName}` - Project's file-system-sanitized name, if any. + * - Value: `''` (empty string). + * - `{snapshotDir}` - Project's + * [testConfig.snapshotDir](https://playwright.dev/docs/api/class-testconfig#test-config-snapshot-dir). + * - Value: `/home/playwright/tests` (since `snapshotDir` is not provided in config, it defaults to `testDir`) * - `{testDir}` - Project's * [testConfig.testDir](https://playwright.dev/docs/api/class-testconfig#test-config-test-dir). * - Value: `/home/playwright/tests` (absolute path is since `testDir` is resolved relative to directory with * config) - * - `{snapshotDir}` - Project's - * [testConfig.snapshotDir](https://playwright.dev/docs/api/class-testconfig#test-config-snapshot-dir). - * - Value: `/home/playwright/tests` (since `snapshotDir` is not provided in config, it defaults to `testDir`) - * - `{platform}` - The value of `process.platform`. - * - `{projectName}` - Project's file-system-sanitized name, if any. - * - Value: `''` (empty string). * - `{testFileDir}` - Directories in relative path from `testDir` to **test file**. * - Value: `page` * - `{testFileName}` - Test file name with extension. @@ -452,12 +458,6 @@ interface TestProject { * - Value: `page/page-click.spec.ts` * - `{testName}` - File-system-sanitized test title, including parent describes but excluding file name. * - Value: `suite-test-should-work` - * - `{arg}` - Relative snapshot path **without extension**. These come from the arguments passed to the - * `toHaveScreenshot()` and `toMatchSnapshot()` calls; if called without arguments, this will be an auto-generated - * snapshot name. - * - Value: `foo/bar/baz` - * - `{ext}` - snapshot extension (with dots) - * - Value: `.png` * * Each token can be preceded with a single character that will be used **only if** this token has non-empty value. * @@ -934,24 +934,6 @@ interface TestConfig { * method. */ toHaveScreenshot?: { - /** - * an acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and - * `1` (lax). `"pixelmatch"` comparator computes color difference in - * [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`. - */ - threshold?: number; - - /** - * an acceptable amount of pixels that could be different, unset by default. - */ - maxDiffPixels?: number; - - /** - * an acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by - * default. - */ - maxDiffPixelRatio?: number; - /** * See `animations` in [page.screenshot([options])](https://playwright.dev/docs/api/class-page#page-screenshot). * Defaults to `"disabled"`. @@ -964,6 +946,17 @@ interface TestConfig { */ caret?: "hide"|"initial"; + /** + * An acceptable amount of pixels that could be different, unset by default. + */ + maxDiffPixels?: number; + + /** + * An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by + * default. + */ + maxDiffPixelRatio?: number; + /** * See `scale` in [page.screenshot([options])](https://playwright.dev/docs/api/class-page#page-screenshot). Defaults * to `"css"`. @@ -974,6 +967,13 @@ interface TestConfig { * See `style` in [page.screenshot([options])](https://playwright.dev/docs/api/class-page#page-screenshot). */ stylePath?: string|Array; + + /** + * An acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and + * `1` (lax). `"pixelmatch"` comparator computes color difference in + * [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`. + */ + threshold?: number; }; /** @@ -983,22 +983,22 @@ interface TestConfig { */ toMatchSnapshot?: { /** - * an acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and - * `1` (lax). `"pixelmatch"` comparator computes color difference in - * [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`. - */ - threshold?: number; - - /** - * an acceptable amount of pixels that could be different, unset by default. + * 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 + * An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by * default. */ maxDiffPixelRatio?: number; + + /** + * An acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and + * `1` (lax). `"pixelmatch"` comparator computes color difference in + * [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`. + */ + threshold?: number; }; /** @@ -1006,14 +1006,14 @@ interface TestConfig { */ toPass?: { /** - * timeout for toPass method in milliseconds. - */ - timeout?: number; - - /** - * probe intervals for toPass method in milliseconds. + * Probe intervals for toPass method in milliseconds. */ intervals?: Array; + + /** + * Timeout for toPass method in milliseconds. + */ + timeout?: number; }; }; @@ -1397,15 +1397,15 @@ interface TestConfig { * */ shard?: null|{ - /** - * The total number of shards. - */ - total: number; - /** * The index of the shard to execute, one-based. */ current: number; + + /** + * The total number of shards. + */ + total: number; }; /** @@ -1484,16 +1484,22 @@ interface TestConfig { * ``` * * The list of supported tokens: + * - `{arg}` - Relative snapshot path **without extension**. These come from the arguments passed to the + * `toHaveScreenshot()` and `toMatchSnapshot()` calls; if called without arguments, this will be an auto-generated + * snapshot name. + * - Value: `foo/bar/baz` + * - `{ext}` - snapshot extension (with dots) + * - Value: `.png` + * - `{platform}` - The value of `process.platform`. + * - `{projectName}` - Project's file-system-sanitized name, if any. + * - Value: `''` (empty string). + * - `{snapshotDir}` - Project's + * [testConfig.snapshotDir](https://playwright.dev/docs/api/class-testconfig#test-config-snapshot-dir). + * - Value: `/home/playwright/tests` (since `snapshotDir` is not provided in config, it defaults to `testDir`) * - `{testDir}` - Project's * [testConfig.testDir](https://playwright.dev/docs/api/class-testconfig#test-config-test-dir). * - Value: `/home/playwright/tests` (absolute path is since `testDir` is resolved relative to directory with * config) - * - `{snapshotDir}` - Project's - * [testConfig.snapshotDir](https://playwright.dev/docs/api/class-testconfig#test-config-snapshot-dir). - * - Value: `/home/playwright/tests` (since `snapshotDir` is not provided in config, it defaults to `testDir`) - * - `{platform}` - The value of `process.platform`. - * - `{projectName}` - Project's file-system-sanitized name, if any. - * - Value: `''` (empty string). * - `{testFileDir}` - Directories in relative path from `testDir` to **test file**. * - Value: `page` * - `{testFileName}` - Test file name with extension. @@ -1502,12 +1508,6 @@ interface TestConfig { * - Value: `page/page-click.spec.ts` * - `{testName}` - File-system-sanitized test title, including parent describes but excluding file name. * - Value: `suite-test-should-work` - * - `{arg}` - Relative snapshot path **without extension**. These come from the arguments passed to the - * `toHaveScreenshot()` and `toMatchSnapshot()` calls; if called without arguments, this will be an auto-generated - * snapshot name. - * - Value: `foo/bar/baz` - * - `{ext}` - snapshot extension (with dots) - * - Value: `.png` * * Each token can be preceded with a single character that will be used **only if** this token has non-empty value. * @@ -8401,17 +8401,14 @@ interface TestConfigWebServer { command: string; /** - * The port that your http server is expected to appear on. It does wait until it accepts connections. Either `port` - * or `url` should be specified. + * Current working directory of the spawned process, defaults to the directory of the configuration file. */ - port?: number; + cwd?: string; /** - * The url on your http server that is expected to return a 2xx, 3xx, 400, 401, 402, or 403 status code when the - * server is ready to accept connections. Redirects (3xx status codes) are being followed and the new location is - * checked. Either `port` or `url` should be specified. + * Environment variables to set for the command, `process.env` by default. */ - url?: string; + env?: { [key: string]: string; }; /** * Whether to ignore HTTPS errors when fetching the `url`. Defaults to `false`. @@ -8419,9 +8416,10 @@ interface TestConfigWebServer { ignoreHTTPSErrors?: boolean; /** - * How long to wait for the process to start up and be available in milliseconds. Defaults to 60000. + * The port that your http server is expected to appear on. It does wait until it accepts connections. Either `port` + * or `url` should be specified. */ - timeout?: number; + port?: number; /** * If true, it will re-use an existing server on the `port` or `url` when available. If no server is running on that @@ -8443,13 +8441,15 @@ interface TestConfigWebServer { stderr?: "pipe"|"ignore"; /** - * Current working directory of the spawned process, defaults to the directory of the configuration file. + * How long to wait for the process to start up and be available in milliseconds. Defaults to 60000. */ - cwd?: string; + timeout?: number; /** - * Environment variables to set for the command, `process.env` by default. + * The url on your http server that is expected to return a 2xx, 3xx, 400, 401, 402, or 403 status code when the + * server is ready to accept connections. Redirects (3xx status codes) are being followed and the new location is + * checked. Either `port` or `url` should be specified. */ - env?: { [key: string]: string; }; + url?: string; }