docs: improve documentation for assertions and test config (#9890)

2025-06-26 21:40:17 +00:00 · 2021-10-29 15:25:52 -07:00 · 2021-10-29 15:25:52 -07:00 · 49337890d2
commit 49337890d2
parent bff84c5391
5 changed files with 566 additions and 43 deletions
--- a/docs/src/test-api/class-testconfig.md
+++ b/docs/src/test-api/class-testconfig.md
@ -35,16 +35,71 @@ export default config;

 ## property: TestConfig.expect
 - type: <[Object]>
+  - `timeout` <[int]> Default timeout for async expect matchers in milliseconds, defaults to 5000ms.
  - `toMatchSnapshot` <[Object]>
    - `threshold` <[float]> Image matching threshold between zero (strict) and one (lax).

 Configuration for the `expect` assertion library.

+```js js-flavor=js
+// playwright.config.js
+// @ts-check
+
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
+  expect: {
+    timeout: 10000,
+    toMatchSnapshot: {
+      threshold: 0.3,
+    },
+  },
+};
+
+module.exports = config;
+```
+
+```js js-flavor=ts
+// playwright.config.ts
+import { PlaywrightTestConfig } from '@playwright/test';
+
+const config: PlaywrightTestConfig = {
+  expect: {
+    timeout: 10000,
+    toMatchSnapshot: {
+      threshold: 0.3,
+    },
+  },
+};
+export default config;
+```
+
 ## property: TestConfig.forbidOnly
 - 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.

+```js js-flavor=js
+// playwright.config.js
+// @ts-check
+
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
+  forbidOnly: !!process.env.CI,
+};
+
+module.exports = config;
+```
+
+```js js-flavor=ts
+// playwright.config.ts
+import { PlaywrightTestConfig } from '@playwright/test';
+
+const config: PlaywrightTestConfig = {
+  forbidOnly: !!process.env.CI,
+};
+export default config;
+```
+
 ## property: TestConfig.globalSetup
 - type: <[string]>

@ -81,12 +136,54 @@ Path to the global teardown file. This file will be required and run after all t

 Learn more about [global setup and teardown](./test-advanced.md#global-setup-and-teardown).

+```js js-flavor=js
+// playwright.config.js
+// @ts-check
+
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
+  globalTeardown: './global-teardown',
+};
+
+module.exports = config;
+```
+
+```js js-flavor=ts
+// playwright.config.ts
+import { PlaywrightTestConfig, devices } from '@playwright/test';
+
+const config: PlaywrightTestConfig = {
+  globalTeardown: './global-teardown',
+};
+export default config;
+```

 ## property: TestConfig.globalTimeout
 - 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.

+```js js-flavor=js
+// playwright.config.js
+// @ts-check
+
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
+  globalTimeout: process.env.CI ? 60 * 60 * 1000 : undefined,
+};
+
+module.exports = config;
+```
+
+```js js-flavor=ts
+// playwright.config.ts
+import { PlaywrightTestConfig } from '@playwright/test';
+
+const config: PlaywrightTestConfig = {
+  globalTimeout: process.env.CI ? 60 * 60 * 1000 : undefined,
+};
+export default config;
+```

 ## property: TestConfig.grep
 - type: <[RegExp]|[Array]<[RegExp]>>
@ -111,6 +208,28 @@ The maximum number of test failures for the whole test suite run. After reaching

 Also available in the [command line](./test-cli.md) with the `--max-failures` and `-x` options.

+```js js-flavor=js
+// playwright.config.js
+// @ts-check
+
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
+  maxFailures: process.env.CI ? 1 : 0,
+};
+
+module.exports = config;
+```
+
+```js js-flavor=ts
+// playwright.config.ts
+import { PlaywrightTestConfig } from '@playwright/test';
+
+const config: PlaywrightTestConfig = {
+  maxFailures: process.env.CI ? 1 : 0,
+};
+export default config;
+```
+
 ## property: TestConfig.metadata
 - type: <[Object]>

@ -121,8 +240,29 @@ Any JSON-serializable metadata that will be put directly to the test report.

 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 [`property: TestConfig.outputDir`] is created, guaranteeing that test running in parallel do not conflict. This directory can be accessed by [`property: TestInfo.outputDir`] and [`method: TestInfo.outputPath`].
+```js js-flavor=js
+// playwright.config.js
+// @ts-check

+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
+  outputDir: './test-results',
+};
+
+module.exports = config;
+```
+
+```js js-flavor=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 [`property: TestConfig.outputDir`] is created, guaranteeing that test running in parallel do not conflict. This directory can be accessed by [`property: TestInfo.outputDir`] and [`method: TestInfo.outputPath`].

 Here is an example that uses [`method: TestInfo.outputPath`] to create a temporary file.

@ -221,6 +361,28 @@ Tests that took more than `threshold` milliseconds are considered slow, and the

 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).

+```js js-flavor=js
+// playwright.config.js
+// @ts-check
+
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
+  retries: 2,
+};
+
+module.exports = config;
+```
+
+```js js-flavor=ts
+// playwright.config.ts
+import { PlaywrightTestConfig } from '@playwright/test';
+
+const config: PlaywrightTestConfig = {
+  retries: 2,
+};
+export default config;
+```
+
 ## property: TestConfig.shard
 - type: <[Object]>
  - `total` <[int]> The total number of shards.
@ -235,6 +397,28 @@ Learn more about [parallelism and sharding](./test-parallel.md) with Playwright

 Directory that will be recursively scanned for test files. Defaults to the directory of the configuration file.

+```js js-flavor=js
+// playwright.config.js
+// @ts-check
+
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
+  testDir: './tests/playwright',
+};
+
+module.exports = config;
+```
+
+```js js-flavor=ts
+// playwright.config.ts
+import { PlaywrightTestConfig } from '@playwright/test';
+
+const config: PlaywrightTestConfig = {
+  testDir: './tests/playwright',
+};
+export default config;
+```
+
 ## property: TestConfig.testIgnore
 - type: <[string]|[RegExp]|[Array]<[string]>|[Array]<[RegExp]>>

@ -242,6 +426,28 @@ Files matching one of these patterns are not executed as test files. Matching is

 For example, `'**/test-assets/**'` will ignore any files in the `test-assets` directory.

+```js js-flavor=js
+// playwright.config.js
+// @ts-check
+
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
+  testIgnore: '**/test-assets/**',
+};
+
+module.exports = config;
+```
+
+```js js-flavor=ts
+// playwright.config.ts
+import { PlaywrightTestConfig, devices } from '@playwright/test';
+
+const config: PlaywrightTestConfig = {
+  testIgnore: '**/test-assets/**',
+};
+export default config;
+```
+
 ## property: TestConfig.testMatch
 - type: <[string]|[RegExp]|[Array]<[string]>|[Array]<[RegExp]>>

@ -249,6 +455,28 @@ Only the files matching one of these patterns are executed as test files. Matchi

 By default, Playwright Test looks for files matching `.*(test|spec)\.(js|ts|mjs)`.

+```js js-flavor=js
+// playwright.config.js
+// @ts-check
+
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
+  testMatch: /.*\.e2e\.js/,
+};
+
+module.exports = config;
+```
+
+```js js-flavor=ts
+// playwright.config.ts
+import { PlaywrightTestConfig, devices } from '@playwright/test';
+
+const config: PlaywrightTestConfig = {
+  testMatch: /.*\.e2e\.js/,
+};
+export default config;
+```
+
 ## property: TestConfig.timeout
 - type: <[int]>

@ -256,6 +484,28 @@ 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 [`method: Test.setTimeout`].

+```js js-flavor=js
+// playwright.config.js
+// @ts-check
+
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
+  timeout: 5 * 60 * 1000,
+};
+
+module.exports = config;
+```
+
+```js js-flavor=ts
+// playwright.config.ts
+import { PlaywrightTestConfig } from '@playwright/test';
+
+const config: PlaywrightTestConfig = {
+  timeout: 5 * 60 * 1000,
+};
+export default config;
+```
+
 ## property: TestConfig.updateSnapshots
 - type: <[UpdateSnapshots]<"all"|"none"|"missing">>

@ -305,3 +555,25 @@ 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](./test-parallel.md) with Playwright Test.
+
+```js js-flavor=js
+// playwright.config.js
+// @ts-check
+
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
+  workers: 3,
+};
+
+module.exports = config;
+```
+
+```js js-flavor=ts
+// playwright.config.ts
+import { PlaywrightTestConfig } from '@playwright/test';
+
+const config: PlaywrightTestConfig = {
+  workers: 3,
+};
+export default config;
+```
--- a/docs/src/test-api/class-testproject.md
+++ b/docs/src/test-api/class-testproject.md
@ -106,12 +106,14 @@ export default config;

 ## property: TestProject.expect
 - type: <[Object]>
-  - `timeout` <[float]> Default timeout for async expect matchers in milliseconds, defaults to 5000ms.
+  - `timeout` <[int]> Default timeout for async expect matchers in milliseconds, defaults to 5000ms.
  - `toMatchSnapshot` <[Object]>
    - `threshold` <[float]> Image matching threshold between zero (strict) and one (lax).

 Configuration for the `expect` assertion library.

+Use [`property: TestConfig.expect`] to change this option for all projects.
+
 ## property: TestProject.metadata
 - type: <[Object]>

@ -151,16 +153,22 @@ test('example test', async ({}, testInfo) => {
 });
 ```

+Use [`property: TestConfig.outputDir`] to change this option for all projects.
+
 ## property: TestProject.repeatEach
 - 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]>

 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]>

@ -250,6 +258,7 @@ const config: PlaywrightTestConfig = {
 export default config;
 ```

+Use [`property: TestConfig.testDir`] to change this option for all projects.

 ## property: TestProject.testIgnore
 - type: <[string]|[RegExp]|[Array]<[string]>|[Array]<[RegExp]>>
@ -258,6 +267,7 @@ Files matching one of these patterns are not executed as test files. Matching is

 For example, `'**/test-assets/**'` will ignore any files in the `test-assets` directory.

+Use [`property: TestConfig.testIgnore`] to change this option for all projects.

 ## property: TestProject.testMatch
 - type: <[string]|[RegExp]|[Array]<[string]>|[Array]<[RegExp]>>
@ -266,6 +276,7 @@ Only the files matching one of these patterns are executed as test files. Matchi

 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]>
@ -274,6 +285,8 @@ 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 [`method: Test.setTimeout`].

+Use [`property: TestConfig.timeout`] to change this option for all projects.
+
 ## property: TestProject.use
 - type: <[Fixtures]>

@ -314,3 +327,5 @@ const config: PlaywrightTestConfig = {
 };
 export default config;
 ```
+
+Use [`property: TestConfig.use`] to change this option for all projects.
--- a/docs/src/test-assertions-js.md
+++ b/docs/src/test-assertions-js.md
@ -31,14 +31,14 @@ await expect(page.locator('.status')).toHaveText('Submitted');

 Playwright Test will be re-testing the node with the selector `.status` until fetched Node has the `"Submitted"`
 text. It will be re-fetching the node and checking it over and over, until the condition is met or until the timeout is
-reached. You can either pass this timeout or configure it once via the [`property: TestProject.expect`] value
+reached. You can either pass this timeout or configure it once via the [`property: TestConfig.expect`] value
 in test config.

 By default, the timeout for assertions is set to 5 seconds.

-## expect(locator).toBeChecked
+## expect(locator).toBeChecked([options])
 - `options`
-  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestProject.expect`].
+  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestConfig.expect`].

 Ensures [Locator] points to the checked input.

@ -47,9 +47,9 @@ const locator = page.locator('.subscribe');
 await expect(locator).toBeChecked();
 ```

-## expect(locator).toBeDisabled
+## expect(locator).toBeDisabled([options])
 - `options`
-  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestProject.expect`].
+  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestConfig.expect`].

 Ensures [Locator] points to a disabled element.

@ -58,9 +58,9 @@ const locator = page.locator('button.submit');
 await expect(locator).toBeDisabled();
 ```

-## expect(locator).toBeEditable
+## expect(locator).toBeEditable([options])
 - `options`
-  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestProject.expect`].
+  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestConfig.expect`].

 Ensures [Locator] points to an editable element.

@ -69,9 +69,9 @@ const locator = page.locator('input');
 await expect(locator).toBeEditable();
 ```

-## expect(locator).toBeEmpty
+## expect(locator).toBeEmpty([options])
 - `options`
-  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestProject.expect`].
+  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestConfig.expect`].

 Ensures [Locator] points to an empty editable element or to a DOM node that has no text.

@ -80,9 +80,9 @@ const locator = page.locator('div.warning');
 await expect(locator).toBeEmpty();
 ```

-## expect(locator).toBeEnabled
+## expect(locator).toBeEnabled([options])
 - `options`
-  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestProject.expect`].
+  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestConfig.expect`].

 Ensures [Locator] points to an enabled element.

@ -91,9 +91,9 @@ const locator = page.locator('button.submit');
 await expect(locator).toBeEnabled();
 ```

-## expect(locator).toBeFocused
+## expect(locator).toBeFocused([options])
 - `options`
-  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestProject.expect`].
+  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestConfig.expect`].

 Ensures [Locator] points to a focused DOM node.

@ -102,9 +102,9 @@ const locator = page.locator('input');
 await expect(locator).toBeFocused();
 ```

-## expect(locator).toBeHidden
+## expect(locator).toBeHidden([options])
 - `options`
-  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestProject.expect`].
+  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestConfig.expect`].

 Ensures [Locator] points to a hidden DOM node, which is the opposite of [visible](./actionability.md#visible).

@ -113,9 +113,9 @@ const locator = page.locator('.my-element');
 await expect(locator).toBeHidden();
 ```

-## expect(locator).toBeVisible
+## expect(locator).toBeVisible([options])
 - `options`
-  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestProject.expect`].
+  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestConfig.expect`].

 Ensures [Locator] points to a [visible](./actionability.md#visible) DOM node.

@ -124,10 +124,10 @@ const locator = page.locator('.my-element');
 await expect(locator).toBeVisible();
 ```

-## expect(locator).toContainText(expected, options?)
+## expect(locator).toContainText(expected[, options])
 - `expected` <[string] | [RegExp] | [Array]<[string]|[RegExp]>>
 - `options`
-  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestProject.expect`].
+  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestConfig.expect`].
  - `useInnerText` <[boolean]> Whether to use `element.innerText` instead of `element.textContent` when retrieving DOM node text.

 Ensures [Locator] points to an element that contains the given text. You can use regular expressions for the value as well.
@ -145,11 +145,11 @@ const locator = page.locator('list > .list-item');
 await expect(locator).toContainText(['Text 1', 'Text 4', 'Text 5']);
 ```

-## expect(locator).toHaveAttribute(name, value)
+## expect(locator).toHaveAttribute(name, value[, options])
 - `name` <[string]> Attribute name
 - `value` <[string]|[RegExp]> Attribute value
 - `options`
-  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestProject.expect`].
+  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestConfig.expect`].

 Ensures [Locator] points to an element with given attribute.

@ -158,10 +158,10 @@ const locator = page.locator('input');
 await expect(locator).toHaveAttribute('type', 'text');
 ```

-## expect(locator).toHaveClass(expected)
+## expect(locator).toHaveClass(expected[, options])
 - `expected` <[string] | [RegExp] | [Array]<[string]|[RegExp]>>
 - `options`
-  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestProject.expect`].
+  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestConfig.expect`].

 Ensures [Locator] points to an element with given CSS class.

@ -177,10 +177,10 @@ const locator = page.locator('list > .component');
 await expect(locator).toHaveClass(['component', 'component selected', 'component']);
 ```

-## expect(locator).toHaveCount(count)
+## expect(locator).toHaveCount(count[, options])
 - `count` <[number]>
 - `options`
-  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestProject.expect`].
+  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestConfig.expect`].

 Ensures [Locator] resolves to an exact number of DOM nodes.

@ -189,11 +189,11 @@ const list = page.locator('list > .component');
 await expect(list).toHaveCount(3);
 ```

-## expect(locator).toHaveCSS(name, value)
+## expect(locator).toHaveCSS(name, value[, options])
 - `name` <[string]> CSS property name
 - `value` <[string]|[RegExp]> CSS property value
 - `options`
-  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestProject.expect`].
+  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestConfig.expect`].

 Ensures [Locator] resolves to an element with the given computed CSS style.

@ -202,10 +202,10 @@ const locator = page.locator('button');
 await expect(locator).toHaveCSS('display', 'flex');
 ```

-## expect(locator).toHaveId(id)
+## expect(locator).toHaveId(id[, options])
 - `id` <[string]> Element id
 - `options`
-  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestProject.expect`].
+  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestConfig.expect`].

 Ensures [Locator] points to an element with the given DOM Node ID.

@ -214,11 +214,11 @@ const locator = page.locator('input');
 await expect(locator).toHaveId('lastname');
 ```

-## expect(locator).toHaveJSProperty(name, value)
+## expect(locator).toHaveJSProperty(name, value[, options])
 - `name` <[string]> Property name
 - `value` <[any]> Property value
 - `options`
-  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestProject.expect`].
+  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestConfig.expect`].

 Ensures [Locator] points to an element with given JavaScript property. Note that this property can be
 of a primitive type as well as a plain serializable JavaScript object.
@ -228,10 +228,10 @@ const locator = page.locator('.component');
 await expect(locator).toHaveJSProperty('loaded', true);
 ```

-## expect(locator).toHaveText(expected, options)
+## expect(locator).toHaveText(expected[, options])
 - `expected` <[string] | [RegExp] | [Array]<[string]|[RegExp]>>
 - `options`
-  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestProject.expect`].
+  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestConfig.expect`].
  - `useInnerText` <[boolean]> Whether to use `element.innerText` instead of `element.textContent` when retrieving DOM node text.

 Ensures [Locator] points to an element with the given text. You can use regular expressions for the value as well.
@ -249,10 +249,10 @@ const locator = page.locator('list > .component');
 await expect(locator).toHaveText(['Text 1', 'Text 2', 'Text 3']);
 ```

-## expect(locator).toHaveValue(value)
+## expect(locator).toHaveValue(value[, options])
 - `value` <[string] | [RegExp]>
 - `options`
-  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestProject.expect`].
+  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestConfig.expect`].

 Ensures [Locator] points to an element with the given input value. You can use regular expressions for the value as well.

@ -261,10 +261,10 @@ const locator = page.locator('input[type=number]');
 await expect(locator).toHaveValue(/[0-9]/);
 ```

-## expect(page).toHaveTitle(title)
+## expect(page).toHaveTitle(title[, options])
 - `title` <[string] | [RegExp]>
 - `options`
-  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestProject.expect`].
+  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestConfig.expect`].

 Ensures page has a given title.

@ -272,13 +272,34 @@ Ensures page has a given title.
 await expect(page).toHaveTitle(/.*checkout/);
 ```

-## expect(page).toHaveURL(url)
+## expect(page).toHaveURL(url[, options])
 - `url` <[string] | [RegExp]>
 - `options`
-  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestProject.expect`].
+  - `timeout` <[number]> Time to retry assertion for, defaults to `timeout` in [`property: TestConfig.expect`].

 Ensures page is navigated to a given URL.

 ```js
 await expect(page).toHaveURL(/.*checkout/);
 ```
+
+## expect(value).toMatchSnapshot(name[, options])
+- `name` <[string] | [Array]<[string]>> Snapshot name.
+- `options`
+  - `threshold` <[float]> Image matching threshold between zero (strict) and one (lax), default is configurable with [`property: TestConfig.expect`].
+
+Ensures that passed value, either a [string] or a [Buffer], matches the expected snapshot stored in the test snapshots directory.
+
+```js
+// Basic usage.
+expect(await page.screenshot()).toMatchSnapshot('landing-page.png');
+
+// Configure image matching threshold.
+expect(await page.screenshot()).toMatchSnapshot('landing-page.png', { threshold: 0.3 });
+
+// Bring some structure to your snapshot files by passing file path segments.
+expect(await page.screenshot()).toMatchSnapshot(['landing', 'step2.png']);
+expect(await page.screenshot()).toMatchSnapshot(['landing', 'step3.png']);
+```
+
+Learn more about [visual comparisons](./test-snapshots.md).
--- a/packages/playwright-test/types/test.d.ts
+++ b/packages/playwright-test/types/test.d.ts
@ -109,6 +109,9 @@ type ExpectSettings = {
 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?: ExpectSettings;
  /**
@ -142,14 +145,22 @@ interface TestProject {
   * });
   * ```
   *
+   * 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;
  /**
@ -198,6 +209,8 @@ interface TestProject {
   * 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;
  /**
@ -205,6 +218,9 @@ interface TestProject {
   * 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)[];
  /**
@ -212,6 +228,9 @@ interface TestProject {
   * 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)[];
  /**
@ -219,6 +238,9 @@ interface TestProject {
   *
   * 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;
 }
@ -306,6 +328,8 @@ export interface Project<TestArgs = {}, WorkerArgs = {}> extends TestProject {
   * export default config;
   * ```
   *
+   * Use [testConfig.use](https://playwright.dev/docs/api/class-testconfig#test-config-use) to change this option for all
+   * projects.
   */
  use?: UseOptions<TestArgs, WorkerArgs>;
 }
@ -371,6 +395,17 @@ 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;
  /**
@ -396,11 +431,33 @@ interface TestConfig {
   * 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.
+   *
+   * ```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;
  /**
@ -423,6 +480,17 @@ interface TestConfig {
   * 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;
  /**
@ -495,11 +563,38 @@ interface TestConfig {
   *
   * 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;

  /**
   * Configuration for the `expect` assertion library.
+   *
+   * ```ts
+   * // playwright.config.ts
+   * import { PlaywrightTestConfig } from '@playwright/test';
+   *
+   * const config: PlaywrightTestConfig = {
+   *   expect: {
+   *     timeout: 10000,
+   *     toMatchSnapshot: {
+   *       threshold: 0.3,
+   *     },
+   *   },
+   * };
+   * export default config;
+   * ```
+   *
   */
  expect?: ExpectSettings;
  /**
@ -510,6 +605,16 @@ interface TestConfig {
  /**
   * 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
@ -539,10 +644,32 @@ interface TestConfig {
  /**
   * 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;
  /**
@ -550,6 +677,17 @@ interface TestConfig {
   * 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)[];
  /**
@ -557,6 +695,17 @@ interface TestConfig {
   * 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)[];
  /**
@ -564,6 +713,17 @@ interface TestConfig {
   *
   * 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).
+   *
+   * ```ts
+   * // playwright.config.ts
+   * import { PlaywrightTestConfig } from '@playwright/test';
+   *
+   * const config: PlaywrightTestConfig = {
+   *   timeout: 5 * 60 * 1000,
+   * };
+   * export default config;
+   * ```
+   *
   */
  timeout?: number;
 }
@ -644,6 +804,17 @@ export interface FullConfig<TestArgs = {}, WorkerArgs = {}> {
   * 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;
  /**
@ -669,11 +840,33 @@ export interface FullConfig<TestArgs = {}, WorkerArgs = {}> {
   * 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 | null;
  /**
   * 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.
+   *
+   * ```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;
  /**
@ -696,6 +889,17 @@ export interface FullConfig<TestArgs = {}, WorkerArgs = {}> {
   * 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;
  version: string;
@ -769,6 +973,17 @@ export interface FullConfig<TestArgs = {}, WorkerArgs = {}> {
   *
   * 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;
  webServer: WebServerConfig | null;
--- a/packages/playwright-test/types/testExpect.d.ts
+++ b/packages/playwright-test/types/testExpect.d.ts
@ -58,13 +58,13 @@ declare global {
       * Match snapshot
       */
      toMatchSnapshot(options: {
-        name: string,
+        name: string | string[],
        threshold?: number
      }): R;
      /**
       * Match snapshot
       */
-      toMatchSnapshot(name: string, options?: {
+      toMatchSnapshot(name: string | string[], options?: {
        threshold?: number
      }): R;