diff --git a/docs/src/api/params.md b/docs/src/api/params.md index 3b11691d6d..9de21aa449 100644 --- a/docs/src/api/params.md +++ b/docs/src/api/params.md @@ -1361,6 +1361,8 @@ Allows locating elements by their title. For example, this method will find the This option configures a template controlling location of snapshots generated by [`method: PageAssertions.toHaveScreenshot#1`] and [`method: SnapshotAssertions.toMatchSnapshot#1`]. +**Usage** + ```js tab=js-ts // playwright.config.ts import type { PlaywrightTestConfig } from '@playwright/test'; @@ -1386,6 +1388,8 @@ const config = { module.exports = config; ``` +**Details** + The value might include some "tokens" that will be replaced with actual values during test execution. Consider the following file structure: diff --git a/docs/src/test-api/class-fixtures.md b/docs/src/test-api/class-fixtures.md index b68c101b4e..3d4383137f 100644 --- a/docs/src/test-api/class-fixtures.md +++ b/docs/src/test-api/class-fixtures.md @@ -34,12 +34,30 @@ Playwright Test comes with builtin fixtures listed below, and you can add your o Learn how to [configure browser](../test-configuration.md) and see [available options][TestOptions]. +**Usage** + +```js tab=js-js +test.beforeAll(async ({ browser }) => { + const page = await browser.newPage(); + // ... +}); +``` + +```js tab=js-ts +test.beforeAll(async ({ browser }) => { + const page = await browser.newPage(); + // ... +}); +``` + ## property: Fixtures.browserName * since: v1.10 - type: <[BrowserName]<"chromium"|"firefox"|"webkit">> Name of the browser that runs tests. Defaults to `'chromium'`. Useful to [annotate tests](../test-annotations.md) based on the browser. +**Usage** + ```js tab=js-js test('skip this test in Firefox', async ({ page, browserName }) => { test.skip(browserName === 'firefox', 'Still working on it'); @@ -64,6 +82,22 @@ Learn how to [configure context](../test-configuration.md) and see [available op Default [`property: Fixtures.page`] belongs to this context. +**Usage** + +```js tab=js-js +test('example test', async ({ page, context }) => { + await context.route('*external.com/*', route => route.abort()); + // ... +}); +``` + +```js tab=js-ts +test('example test', async ({ page, context }) => { + await context.route('*external.com/*', route => route.abort()); + // ... +}); +``` + ## property: Fixtures.page * since: v1.10 - type: <[Page]> @@ -72,6 +106,8 @@ Isolated [Page] instance, created for each test. Pages are isolated between test This is the most common fixture used in a test. +**Usage** + ```js tab=js-js const { test, expect } = require('@playwright/test'); @@ -102,6 +138,8 @@ test('basic test', async ({ page }) => { Isolated [APIRequestContext] instance for each test. +**Usage** + ```js tab=js-js const { test, expect } = require('@playwright/test'); diff --git a/docs/src/test-api/class-test.md b/docs/src/test-api/class-test.md index a8ce1d6a5d..a286ebab0a 100644 --- a/docs/src/test-api/class-test.md +++ b/docs/src/test-api/class-test.md @@ -29,13 +29,14 @@ test('basic test', async ({ page }) => { Declares a test. +**Usage** + ```js tab=js-js const { test, expect } = require('@playwright/test'); test('basic test', async ({ page }) => { await page.goto('https://playwright.dev/'); - const name = await page.innerText('.navbar__title'); - expect(name).toBe('Playwright'); + // ... }); ``` @@ -44,8 +45,7 @@ import { test, expect } from '@playwright/test'; test('basic test', async ({ page }) => { await page.goto('https://playwright.dev/'); - const name = await page.innerText('.navbar__title'); - expect(name).toBe('Playwright'); + // ... }); ``` @@ -66,10 +66,30 @@ Test function that takes one or two arguments: an object with fixtures and optio ## method: Test.afterAll * since: v1.10 -Declares an `afterAll` hook that is executed once per worker after all tests. When called in the scope of a test file, runs after all tests in the file. When called inside a [`method: Test.describe#1`] group, runs after all tests in the group. If multiple `afterAll` hooks are added, they will run in the order of their registration. +Declares an `afterAll` hook that is executed once per worker after all tests. + +**Details** + +When called in the scope of a test file, runs after all tests in the file. When called inside a [`method: Test.describe#1`] group, runs after all tests in the group. If multiple `afterAll` hooks are added, they will run in the order of their registration. Note that worker process is restarted on test failures, and `afterAll` hook runs again in the new worker. Learn more about [workers and failures](../test-retries.md). +**Usage** + +```js tab=js-js +test.afterAll(async () => { + console.log('Done with tests'); + // ... +}); +``` + +```js tab=js-ts +test.afterAll(async () => { + console.log('Done with tests'); + // ... +}); +``` + ### param: Test.afterAll.hookFunction * since: v1.10 - `hookFunction` <[function]\([Fixtures], [TestInfo]\)> @@ -81,10 +101,16 @@ Hook function that takes one or two arguments: an object with worker fixtures an ## method: Test.afterEach * since: v1.10 -Declares an `afterEach` hook that is executed after each test. When called in the scope of a test file, runs after each test in the file. When called inside a [`method: Test.describe#1`] group, runs after each test in the group. If multiple `afterEach` hooks are added, they will run in the order of their registration. +Declares an `afterEach` hook that is executed after each test. + +**Details** + +When called in the scope of a test file, runs after each test in the file. When called inside a [`method: Test.describe#1`] group, runs after each test in the group. If multiple `afterEach` hooks are added, they will run in the order of their registration. You can access all the same [Fixtures] as the test function itself, and also the [TestInfo] object that gives a lot of useful information. For example, you can check whether the test succeeded or failed. +**Usage** + ```js tab=js-js // example.spec.js const { test, expect } = require('@playwright/test'); @@ -127,7 +153,17 @@ Hook function that takes one or two arguments: an object with fixtures and optio ## method: Test.beforeAll * since: v1.10 -Declares a `beforeAll` hook that is executed once per worker process before all tests. When called in the scope of a test file, runs before all tests in the file. When called inside a [`method: Test.describe#1`] group, runs before all tests in the group. If multiple `beforeAll` hooks are added, they will run in the order of their registration. +Declares a `beforeAll` hook that is executed once per worker process before all tests. + +**Details** + +When called in the scope of a test file, runs before all tests in the file. When called inside a [`method: Test.describe#1`] group, runs before all tests in the group. If multiple `beforeAll` hooks are added, they will run in the order of their registration. + +Note that worker process is restarted on test failures, and `beforeAll` hook runs again in the new worker. Learn more about [workers and failures](../test-retries.md). + +You can use [`method: Test.afterAll`] to teardown any resources set up in `beforeAll`. + +**Usage** ```js tab=js-js // example.spec.js @@ -163,10 +199,6 @@ test('my test', async ({ page }) => { }); ``` -Note that worker process is restarted on test failures, and `beforeAll` hook runs again in the new worker. Learn more about [workers and failures](../test-retries.md). - -You can use [`method: Test.afterAll`] to teardown any resources set up in `beforeAll`. - ### param: Test.beforeAll.hookFunction * since: v1.10 - `hookFunction` <[function]\([Fixtures], [TestInfo]\)> @@ -178,10 +210,18 @@ Hook function that takes one or two arguments: an object with worker fixtures an ## method: Test.beforeEach * since: v1.10 -Declares a `beforeEach` hook that is executed before each test. When called in the scope of a test file, runs before each test in the file. When called inside a [`method: Test.describe#1`] group, runs before each test in the group. If multiple `beforeEach` hooks are added, they will run in the order of their registration. +Declares a `beforeEach` hook that is executed before each test. + +**Details** + +When called in the scope of a test file, runs before each test in the file. When called inside a [`method: Test.describe#1`] group, runs before each test in the group. If multiple `beforeEach` hooks are added, they will run in the order of their registration. You can access all the same [Fixtures] as the test function itself, and also the [TestInfo] object that gives a lot of useful information. For example, you can navigate the page before starting the test. +You can use [`method: Test.afterEach`] to teardown any resources set up in `beforeEach`. + +**Usage** + ```js tab=js-js // example.spec.js const { test, expect } = require('@playwright/test'); @@ -210,8 +250,6 @@ test('my test', async ({ page }) => { }); ``` -You can use [`method: Test.afterEach`] to teardown any resources set up in `beforeEach`. - ### param: Test.beforeEach.hookFunction * since: v1.10 - `hookFunction` <[function]\([Fixtures], [TestInfo]\)> @@ -226,6 +264,8 @@ Hook function that takes one or two arguments: an object with fixtures and optio Declares a group of tests. +**Usage** + ```js tab=js-js test.describe('two tests', () => { test('one', async ({ page }) => { @@ -268,6 +308,8 @@ A callback that is run immediately when calling [`method: Test.describe#1`]. Any Declares an anonymous group of tests. This is convenient to give a group of tests a common option with [`method: Test.use`]. +**Usage** + ```js tab=js-js test.describe(() => { test.use({ colorScheme: 'dark' }); @@ -311,53 +353,38 @@ Configures the enclosing scope. Can be executed either on the top level or insid Learn more about the execution modes [here](../test-parallel.md). -Running tests in parallel: +**Usage** -```js tab=js-js -// Run all the tests in the file concurrently using parallel workers. -test.describe.configure({ mode: 'parallel' }); -test('runs in parallel 1', async ({ page }) => {}); -test('runs in parallel 2', async ({ page }) => {}); -``` +* Running tests in parallel. -```js tab=js-ts -// Run all the tests in the file concurrently using parallel workers. -test.describe.configure({ mode: 'parallel' }); -test('runs in parallel 1', async ({ page }) => {}); -test('runs in parallel 2', async ({ page }) => {}); -``` + ```js + // Run all the tests in the file concurrently using parallel workers. + test.describe.configure({ mode: 'parallel' }); + test('runs in parallel 1', async ({ page }) => {}); + test('runs in parallel 2', async ({ page }) => {}); + ``` -Running tests sequentially: +* Running tests serially, retrying from the start. -```js tab=js-js -// Annotate tests as inter-dependent. -test.describe.configure({ mode: 'serial' }); -test('runs first', async ({ page }) => {}); -test('runs second', async ({ page }) => {}); -``` + :::note + Running serially is not recommended. It is usually better to make your tests isolated, so they can be run independently. + ::: -```js tab=js-ts -// Annotate tests as inter-dependent. -test.describe.configure({ mode: 'serial' }); -test('runs first', async ({ page }) => {}); -test('runs second', async ({ page }) => {}); -``` + ```js + // Annotate tests as inter-dependent. + test.describe.configure({ mode: 'serial' }); + test('runs first', async ({ page }) => {}); + test('runs second', async ({ page }) => {}); + ``` -Configuring retries and timeout for each test: +* Configuring retries and timeout for each test. -```js tab=js-js -// Each test in the file will be retried twice and have a timeout of 20 seconds. -test.describe.configure({ retries: 2, timeout: 20_000 }); -test('runs first', async ({ page }) => {}); -test('runs second', async ({ page }) => {}); -``` - -```js tab=js-ts -// Each test in the file will be retried twice and have a timeout of 20 seconds. -test.describe.configure({ retries: 2, timeout: 20_000 }); -test('runs first', async ({ page }) => {}); -test('runs second', async ({ page }) => {}); -``` + ```js + // Each test in the file will be retried twice and have a timeout of 20 seconds. + test.describe.configure({ retries: 2, timeout: 20_000 }); + test('runs first', async ({ page }) => {}); + test('runs second', async ({ page }) => {}); + ``` ### option: Test.describe.configure.mode * since: v1.10 @@ -383,6 +410,8 @@ Timeout for each test in milliseconds. Overrides [`property: TestProject.timeout Declares a test group similarly to [`method: Test.describe#1`]. Tests in this group are marked as "fixme" and will not be executed. +**Usage** + ```js tab=js-js test.describe.fixme('broken tests', () => { test('example', async ({ page }) => { @@ -418,6 +447,8 @@ A callback that is run immediately when calling [`method: Test.describe.fixme`]. Declares a focused group of tests. If there are some focused tests or suites, all of them will be run but nothing else. +**Usage** + ```js tab=js-js test.describe.only('focused group', () => { test('in the focused group', async ({ page }) => { @@ -456,12 +487,11 @@ A callback that is run immediately when calling [`method: Test.describe.only`]. ## method: Test.describe.parallel * since: v1.10 +* discouraged: See [`method: Test.describe.configure`] for the preferred way of configuring the execution mode. Declares a group of tests that could be run in parallel. By default, tests in a single test file run one after another, but using [`method: Test.describe.parallel`] allows them to run in parallel. -:::note -See [`method: Test.describe.configure`] for the preferred way of configuring the execution mode. -::: +**Usage** ```js tab=js-js test.describe.parallel('group', () => { @@ -495,9 +525,26 @@ A callback that is run immediately when calling [`method: Test.describe.parallel ## method: Test.describe.parallel.only * since: v1.10 +* discouraged: See [`method: Test.describe.configure`] for the preferred way of configuring the execution mode. Declares a focused group of tests that could be run in parallel. This is similar to [`method: Test.describe.parallel`], but focuses the group. If there are some focused tests or suites, all of them will be run but nothing else. +**Usage** + +```js tab=js-js +test.describe.parallel.only('group', () => { + test('runs in parallel 1', async ({ page }) => {}); + test('runs in parallel 2', async ({ page }) => {}); +}); +``` + +```js tab=js-ts +test.describe.parallel.only('group', () => { + test('runs in parallel 1', async ({ page }) => {}); + test('runs in parallel 2', async ({ page }) => {}); +}); +``` + ### param: Test.describe.parallel.only.title * since: v1.10 - `title` <[string]> @@ -514,17 +561,16 @@ A callback that is run immediately when calling [`method: Test.describe.parallel ## method: Test.describe.serial * since: v1.10 +* discouraged: See [`method: Test.describe.configure`] for the preferred way of configuring the execution mode. Declares a group of tests that should always be run serially. If one of the tests fails, all subsequent tests are skipped. All tests in a group are retried together. -:::note -See [`method: Test.describe.configure`] for the preferred way of configuring the execution mode. -::: - :::note Using serial is not recommended. It is usually better to make your tests isolated, so they can be run independently. ::: +**Usage** + ```js tab=js-js test.describe.serial('group', () => { test('runs first', async ({ page }) => {}); @@ -555,6 +601,7 @@ A callback that is run immediately when calling [`method: Test.describe.serial`] ## method: Test.describe.serial.only * since: v1.10 +* discouraged: See [`method: Test.describe.configure`] for the preferred way of configuring the execution mode. Declares a focused group of tests that should always be run serially. If one of the tests fails, all subsequent tests are skipped. All tests in a group are retried together. If there are some focused tests or suites, all of them will be run but nothing else. @@ -562,6 +609,8 @@ Declares a focused group of tests that should always be run serially. If one of Using serial is not recommended. It is usually better to make your tests isolated, so they can be run independently. ::: +**Usage** + ```js tab=js-js test.describe.serial.only('group', () => { test('runs first', async ({ page }) => { @@ -600,6 +649,8 @@ A callback that is run immediately when calling [`method: Test.describe.serial.o Declares a skipped test group, similarly to [`method: Test.describe#1`]. Tests in the skipped group are never run. +**Usage** + ```js tab=js-js test.describe.skip('skipped group', () => { test('example', async ({ page }) => { @@ -634,9 +685,15 @@ A callback that is run immediately when calling [`method: Test.describe.skip`]. * since: v1.10 - type: <[Object]> -`expect` function can be used to create test assertions. Read [expect library documentation](https://jestjs.io/docs/expect) for more details. +`expect` function can be used to create test assertions. Read more about [test assertions](../test-assertions.md). +**Usage** +```js +test('example', async ({ page }) => { + await test.expect(page).toHaveTitle('Title'); +}); +``` @@ -646,6 +703,8 @@ A callback that is run immediately when calling [`method: Test.describe.skip`]. Extends the `test` object by defining fixtures and/or options that can be used in the tests. +**Usage** + First define a fixture and/or an option. ```js tab=js-js @@ -777,6 +836,8 @@ An object containing fixtures and/or options. Learn more about [fixtures format] Unconditonally marks a test as "should fail". Playwright Test runs this test and ensures that it is actually failing. This is useful for documentation purposes to acknowledge that some functionality is broken until it is fixed. +**Usage** + ```js tab=js-js const { test, expect } = require('@playwright/test'); @@ -800,6 +861,8 @@ test('not yet ready', async ({ page }) => { Conditionally mark a test as "should fail" with an optional description. +**Usage** + ```js tab=js-js const { test, expect } = require('@playwright/test'); @@ -836,6 +899,8 @@ Optional description that will be reflected in a test report. Conditionally mark all tests in a file or [`method: Test.describe#1`] group as "should fail". +**Usage** + ```js tab=js-js const { test, expect } = require('@playwright/test'); @@ -880,6 +945,8 @@ Optional description that will be reflected in a test report. Declares a test to be fixed, similarly to [`method: Test.(call)`]. This test will not be run. +**Usage** + ```js tab=js-js const { test, expect } = require('@playwright/test'); @@ -915,6 +982,8 @@ Test function that takes one or two arguments: an object with fixtures and optio Mark a test as "fixme", with the intention to fix it. Test is immediately aborted when you call [`method: Test.fixme#2`]. +**Usage** + ```js tab=js-js const { test, expect } = require('@playwright/test'); @@ -967,6 +1036,8 @@ test('test to be fixed 2', async ({ page }) => { Conditionally mark a test as "fixme" with an optional description. +**Usage** + ```js tab=js-js const { test, expect } = require('@playwright/test'); @@ -1006,6 +1077,8 @@ Optional description that will be reflected in a test report. Conditionally mark all tests in a file or [`method: Test.describe#1`] group as "fixme". +**Usage** + ```js tab=js-js const { test, expect } = require('@playwright/test'); @@ -1052,11 +1125,30 @@ Optional description that will be reflected in a test report. Returns information about the currently running test. This method can only be called during the test execution, otherwise it throws. +**Usage** + +```js tab=js-js +test('example test', async ({ page }) => { + // ... + await test.info().attach('screenshot', { body: await page.screenshot(), contentType: 'image/png' }); +}); +``` + +```js tab=js-ts +test('example test', async ({ page }) => { + // ... + await test.info().attach('screenshot', { body: await page.screenshot(), contentType: 'image/png' }); +}); +``` + + ## method: Test.only * since: v1.10 Declares a focused test. If there are some focused tests or suites, all of them will be run but nothing else. +**Usage** + ```js tab=js-js test.only('focus this test', async ({ page }) => { // Run only focused tests in the entire project. @@ -1089,94 +1181,50 @@ Test function that takes one or two arguments: an object with fixtures and optio Changes the timeout for the test. Zero means no timeout. Learn more about [various timeouts](../test-timeouts.md). -```js tab=js-js -const { test, expect } = require('@playwright/test'); - -test('very slow test', async ({ page }) => { - test.setTimeout(120000); - // ... -}); -``` - -```js tab=js-ts -import { test, expect } from '@playwright/test'; - -test('very slow test', async ({ page }) => { - test.setTimeout(120000); - // ... -}); -``` - -Changing timeout from a slow `beforeEach` or `afterEach` hook. Note that this affects the test timeout that is shared with `beforeEach`/`afterEach` hooks. - -```js tab=js-js -const { test, expect } = require('@playwright/test'); - -test.beforeEach(async ({ page }, testInfo) => { - // Extend timeout for all tests running this hook by 30 seconds. - test.setTimeout(testInfo.timeout + 30000); -}); -``` - -```js tab=js-ts -import { test, expect } from '@playwright/test'; - -test.beforeEach(async ({ page }, testInfo) => { - // Extend timeout for all tests running this hook by 30 seconds. - test.setTimeout(testInfo.timeout + 30000); -}); -``` - -Changing timeout for a `beforeAll` or `afterAll` hook. Note this affects the hook's timeout, not the test timeout. - -```js tab=js-js -const { test, expect } = require('@playwright/test'); - -test.beforeAll(async () => { - // Set timeout for this hook. - test.setTimeout(60000); -}); -``` - -```js tab=js-ts -import { test, expect } from '@playwright/test'; - -test.beforeAll(async () => { - // Set timeout for this hook. - test.setTimeout(60000); -}); -``` - -Changing timeout for all tests in a [`method: Test.describe#1`] group. - -```js tab=js-js -const { test, expect } = require('@playwright/test'); - -test.describe('group', () => { - // Applies to all tests in this group. - test.describe.configure({ timeout: 60000 }); - - test('test one', async () => { /* ... */ }); - test('test two', async () => { /* ... */ }); - test('test three', async () => { /* ... */ }); -}); -``` - -```js tab=js-ts -import { test, expect } from '@playwright/test'; - -test.describe('group', () => { - // Applies to all tests in this group. - test.describe.configure({ timeout: 60000 }); - - test('test one', async () => { /* ... */ }); - test('test two', async () => { /* ... */ }); - test('test three', async () => { /* ... */ }); -}); -``` - Timeout for the currently running test is available through [`property: TestInfo.timeout`]. +**Usage** + +* Changing test timeout. + + ```js tab=js-ts + test('very slow test', async ({ page }) => { + test.setTimeout(120000); + // ... + }); + ``` + +* Changing timeout from a slow `beforeEach` or `afterEach` hook. Note that this affects the test timeout that is shared with `beforeEach`/`afterEach` hooks. + + ```js tab=js-ts + test.beforeEach(async ({ page }, testInfo) => { + // Extend timeout for all tests running this hook by 30 seconds. + test.setTimeout(testInfo.timeout + 30000); + }); + ``` + +* Changing timeout for a `beforeAll` or `afterAll` hook. Note this affects the hook's timeout, not the test timeout. + + ```js tab=js-ts + test.beforeAll(async () => { + // Set timeout for this hook. + test.setTimeout(60000); + }); + ``` + +* Changing timeout for all tests in a [`method: Test.describe#1`] group. + + ```js tab=js-ts + test.describe('group', () => { + // Applies to all tests in this group. + test.describe.configure({ timeout: 60000 }); + + test('test one', async () => { /* ... */ }); + test('test two', async () => { /* ... */ }); + test('test three', async () => { /* ... */ }); + }); + ``` + ### param: Test.setTimeout.timeout * since: v1.10 - `timeout` <[int]> @@ -1190,6 +1238,8 @@ Timeout in milliseconds. Declares a skipped test, similarly to [`method: Test.(call)`]. Skipped test is never run. +**Usage** + ```js tab=js-js const { test, expect } = require('@playwright/test'); @@ -1225,6 +1275,8 @@ Test function that takes one or two arguments: an object with fixtures and optio Unconditionally skip a test. Test is immediately aborted when you call [`method: Test.skip#2`]. +**Usage** + ```js tab=js-js const { test, expect } = require('@playwright/test'); @@ -1277,6 +1329,8 @@ test('skipped test 2', async ({ page }) => { Conditionally skip a test with an optional description. +**Usage** + ```js tab=js-js const { test, expect } = require('@playwright/test'); @@ -1335,6 +1389,8 @@ Optional description that will be reflected in a test report. Conditionally skips all tests in a file or [`method: Test.describe#1`] group. +**Usage** + ```js tab=js-js const { test, expect } = require('@playwright/test'); @@ -1381,6 +1437,12 @@ Optional description that will be reflected in a test report. Unconditionally marks a test as "slow". Slow test will be given triple the default timeout. +**Details** + +[`method: Test.slow#1`] cannot be used in a `beforeAll` or `afterAll` hook. Use [`method: Test.setTimeout`] instead. + +**Usage** + ```js tab=js-js const { test, expect } = require('@playwright/test'); @@ -1399,15 +1461,13 @@ test('slow test', async ({ page }) => { }); ``` -:::note -[`method: Test.slow#1`] cannot be used in a `beforeAll` or `afterAll` hook. Use [`method: Test.setTimeout`] instead. -::: - ## method: Test.slow#2 * since: v1.10 Conditionally mark a test as "slow" with an optional description. Slow test will be given triple the default timeout. +**Usage** + ```js tab=js-js const { test, expect } = require('@playwright/test'); @@ -1444,6 +1504,8 @@ Optional description that will be reflected in a test report. Conditionally mark all tests in a file or [`method: Test.describe#1`] group as "slow". Slow tests will be given triple the default timeout. +**Usage** + ```js tab=js-js const { test, expect } = require('@playwright/test'); @@ -1489,6 +1551,8 @@ Optional description that will be reflected in a test report. Declares a test step. +**Usage** + ```js tab=js-js const { test, expect } = require('@playwright/test'); @@ -1509,7 +1573,9 @@ test('test', async ({ page }) => { }); ``` -The method returns value retuned by the step callback. +**Details** + +The method returns the value retuned by the step callback. ```js tab=js-js const { test, expect } = require('@playwright/test'); @@ -1553,7 +1619,9 @@ Step body. ## method: Test.use * since: v1.10 -Specifies options or fixtures to use in a single test file or a [`method: Test.describe#1`] group. Most useful to set an option, for example set `locale` to configure `context` fixture. `test.use` can be called either in the global scope or inside `test.describe`. It is an error to call it within `beforeEach` or `beforeAll`. +Specifies options or fixtures to use in a single test file or a [`method: Test.describe#1`] group. Most useful to set an option, for example set `locale` to configure `context` fixture. + +**Usage** ```js tab=js-js const { test, expect } = require('@playwright/test'); @@ -1575,6 +1643,10 @@ test('test with locale', async ({ page }) => { }); ``` +**Details** + +`test.use` can be called either in the global scope or inside `test.describe`. It is an error to call it within `beforeEach` or `beforeAll`. + It is also possible to override a fixture by providing a function. ```js tab=js-js diff --git a/docs/src/test-api/class-testconfig.md b/docs/src/test-api/class-testconfig.md index 61e4e256e2..ba6bfde7ec 100644 --- a/docs/src/test-api/class-testconfig.md +++ b/docs/src/test-api/class-testconfig.md @@ -39,7 +39,7 @@ export default config; - 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`. + - `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"`. @@ -52,6 +52,8 @@ export default config; Configuration for the `expect` assertion library. Learn more about [various timeouts](../test-timeouts.md). +**Usage** + ```js tab=js-js // playwright.config.js // @ts-check @@ -90,6 +92,8 @@ export default config; 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. +**Usage** + ```js tab=js-js // playwright.config.js // @ts-check @@ -121,6 +125,30 @@ 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. +**Usage** + +```js tab=js-js +// playwright.config.js +// @ts-check + +/** @type {import('@playwright/test').PlaywrightTestConfig} */ +const config = { + fullyParallel: true, +}; + +module.exports = config; +``` + +```js tab=js-ts +// playwright.config.ts +import type { PlaywrightTestConfig } from '@playwright/test'; + +const config: PlaywrightTestConfig = { + fullyParallel: true, +}; +export default config; +``` + ## property: TestConfig.globalSetup * since: v1.10 - type: ?<[string]> @@ -129,6 +157,8 @@ Path to the global setup file. This file will be required and run before all the Learn more about [global setup and teardown](../test-advanced.md#global-setup-and-teardown). +**Usage** + ```js tab=js-js // playwright.config.js // @ts-check @@ -159,6 +189,8 @@ 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). +**Usage** + ```js tab=js-js // playwright.config.js // @ts-check @@ -187,6 +219,8 @@ export default config; 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). +**Usage** + ```js tab=js-js // playwright.config.js // @ts-check @@ -217,6 +251,29 @@ Filter to only run tests with a title matching one of the patterns. For example, `grep` option is also useful for [tagging tests](../test-annotations.md#tag-tests). +**Usage** + +```js tab=js-js +// playwright.config.js +// @ts-check + +/** @type {import('@playwright/test').PlaywrightTestConfig} */ +const config = { + grep: /smoke/, +}; + +module.exports = config; +``` + +```js tab=js-ts +// playwright.config.ts +import type { PlaywrightTestConfig } from '@playwright/test'; + +const config: PlaywrightTestConfig = { + grep: /smoke/, +}; +export default config; +``` ## property: TestConfig.grepInvert * since: v1.10 @@ -226,12 +283,60 @@ Filter to only run tests with a title **not** matching one of the patterns. This `grepInvert` option is also useful for [tagging tests](../test-annotations.md#tag-tests). +**Usage** + +```js tab=js-js +// playwright.config.js +// @ts-check + +/** @type {import('@playwright/test').PlaywrightTestConfig} */ +const config = { + grepInvert: /manual/, +}; + +module.exports = config; +``` + +```js tab=js-ts +// playwright.config.ts +import type { PlaywrightTestConfig } from '@playwright/test'; + +const config: PlaywrightTestConfig = { + grepInvert: /manual/, +}; +export default config; +``` + ## property: TestConfig.ignoreSnapshots * since: v1.26 - type: ?<[boolean]> Whether to skip snapshot expectations, such as `expect(value).toMatchSnapshot()` and `await expect(page).toHaveScreenshot()`. +**Usage** + +```js tab=js-js +// playwright.config.js +// @ts-check + +/** @type {import('@playwright/test').PlaywrightTestConfig} */ +const config = { + ignoreSnapshots: !process.env.CI, +}; + +module.exports = config; +``` + +```js tab=js-ts +// playwright.config.ts +import type { PlaywrightTestConfig } from '@playwright/test'; + +const config: PlaywrightTestConfig = { + ignoreSnapshots: !process.env.CI, +}; +export default config; +``` + ## property: TestConfig.maxFailures * since: v1.10 - type: ?<[int]> @@ -240,6 +345,8 @@ 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. +**Usage** + ```js tab=js-js // playwright.config.js // @ts-check @@ -268,18 +375,68 @@ export default config; Metadata that will be put directly to the test report serialized as JSON. +**Usage** + +```js tab=js-js +// playwright.config.js +// @ts-check + +/** @type {import('@playwright/test').PlaywrightTestConfig} */ +const config = { + metadata: 'acceptance tests', +}; + +module.exports = config; +``` + +```js tab=js-ts +// playwright.config.ts +import type { PlaywrightTestConfig } from '@playwright/test'; + +const config: PlaywrightTestConfig = { + metadata: 'acceptance tests', +}; +export default config; +``` + ## property: TestConfig.name * since: v1.10 - type: ?<[string]> Config name is visible in the report and during test execution, unless overridden by [`property: TestProject.name`]. +**Usage** + +```js tab=js-js +// playwright.config.js +// @ts-check + +/** @type {import('@playwright/test').PlaywrightTestConfig} */ +const config = { + name: 'acceptance tests', +}; + +module.exports = config; +``` + +```js tab=js-ts +// playwright.config.ts +import type { PlaywrightTestConfig } from '@playwright/test'; + +const config: PlaywrightTestConfig = { + name: 'acceptance tests', +}; +export default config; +``` + ## property: TestConfig.outputDir * since: v1.10 - type: ?<[string]> The output directory for files created during test execution. Defaults to `/test-results`. +**Usage** + ```js tab=js-js // playwright.config.js // @ts-check @@ -302,6 +459,8 @@ const config: PlaywrightTestConfig = { export default config; ``` +**Details** + 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. @@ -329,15 +488,37 @@ test('example test', async ({}, testInfo) => { ## property: TestConfig.snapshotDir * since: v1.10 +* discouraged: Use [`property: TestConfig.snapshotPathTemplate`] to configure snapshot paths. - type: ?<[string]> -:::note -Use of [`property: TestConfig.snapshotDir`] is discouraged. Please use [`property: TestConfig.snapshotPathTemplate`] to configure -snapshot paths. -::: - The base directory, relative to the config file, for snapshot files created with `toMatchSnapshot`. Defaults to [`property: TestConfig.testDir`]. +**Usage** + +```js tab=js-js +// playwright.config.js +// @ts-check + +/** @type {import('@playwright/test').PlaywrightTestConfig} */ +const config = { + snapshotDir: './snapshots', +}; + +module.exports = config; +``` + +```js tab=js-ts +// playwright.config.ts +import { type PlaywrightTestConfig } from '@playwright/test'; + +const config: PlaywrightTestConfig = { + snapshotDir: './snapshots', +}; +export default config; +``` + +**Details** + The directory for each test can be accessed by [`property: TestInfo.snapshotDir`] and [`method: TestInfo.snapshotPath`]. 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`. @@ -355,6 +536,30 @@ Whether to preserve test output in the [`property: TestConfig.outputDir`]. Defau * `'failures-only'` - only preserve output for failed tests. +**Usage** + +```js tab=js-js +// playwright.config.js +// @ts-check + +/** @type {import('@playwright/test').PlaywrightTestConfig} */ +const config = { + preserveOutput: 'always', +}; + +module.exports = config; +``` + +```js tab=js-ts +// playwright.config.ts +import { type PlaywrightTestConfig } from '@playwright/test'; + +const config: PlaywrightTestConfig = { + preserveOutput: 'always', +}; +export default config; +``` + ## property: TestConfig.projects * since: v1.10 - type: ?<[Array]<[TestProject]>> @@ -362,18 +567,95 @@ Whether to preserve test output in the [`property: TestConfig.outputDir`]. Defau Playwright Test supports running multiple test projects at the same time. See [TestProject] for more information. +**Usage** + +```js tab=js-js +// playwright.config.js +// @ts-check +const { devices } = require('@playwright/test'); + +/** @type {import('@playwright/test').PlaywrightTestConfig} */ +const config = { + projects: [ + { name: 'chromium', use: devices['Desktop Chrome'] } + ] +}; + +module.exports = config; +``` + +```js tab=js-ts +// playwright.config.ts +import { type PlaywrightTestConfig, devices } from '@playwright/test'; + +const config: PlaywrightTestConfig = { + projects: [ + { name: 'chromium', use: devices['Desktop Chrome'] } + ] +}; +export default config; +``` + ## property: TestConfig.quiet * since: v1.10 - type: ?<[boolean]> Whether to suppress stdio and stderr output from the tests. +**Usage** + +```js tab=js-js +// playwright.config.js +// @ts-check + +/** @type {import('@playwright/test').PlaywrightTestConfig} */ +const config = { + quiet: !!process.env.CI, +}; + +module.exports = config; +``` + +```js tab=js-ts +// playwright.config.ts +import { type PlaywrightTestConfig } from '@playwright/test'; + +const config: PlaywrightTestConfig = { + quiet: !!process.env.CI, +}; +export default config; +``` + ## property: TestConfig.repeatEach * since: v1.10 - type: ?<[int]> The number of times to repeat each test, useful for debugging flaky tests. +**Usage** + +```js tab=js-js +// playwright.config.js +// @ts-check + +/** @type {import('@playwright/test').PlaywrightTestConfig} */ +const config = { + repeatEach: 3, +}; + +module.exports = config; +``` + +```js tab=js-ts +// playwright.config.ts +import { type PlaywrightTestConfig } from '@playwright/test'; + +const config: PlaywrightTestConfig = { + repeatEach: 3, +}; +export default config; +``` + ## property: TestConfig.reporter * since: v1.10 - type: ?<[string]|[Array]<[Object]>|[BuiltInReporter]<"list"|"dot"|"line"|"github"|"json"|"junit"|"null"|"html">> @@ -389,6 +671,8 @@ You can pass options to the reporter in a tuple like `['json', { outputFile: './ Learn more in the [reporters guide](../test-reporters.md). +**Usage** + ```js tab=js-js // playwright.config.js // @ts-check @@ -419,6 +703,32 @@ export default config; Whether to report slow test files. Pass `null` to disable this feature. +**Usage** + +```js tab=js-js +// playwright.config.js +// @ts-check + +/** @type {import('@playwright/test').PlaywrightTestConfig} */ +const config = { + reportSlowTests: null, +}; + +module.exports = config; +``` + +```js tab=js-ts +// playwright.config.ts +import { type PlaywrightTestConfig } from '@playwright/test'; + +const config: PlaywrightTestConfig = { + reportSlowTests: null, +}; +export default config; +``` + +**Details** + Test files that took more than `threshold` milliseconds are considered slow, and the slowest ones are reported, no more than `max` number of them. Passing zero as `max` reports all test files that exceed the threshold. ## property: TestConfig.retries @@ -427,6 +737,8 @@ Test files that took more than `threshold` milliseconds are considered slow, and 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). +**Usage** + ```js tab=js-js // playwright.config.js // @ts-check @@ -459,12 +771,38 @@ 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. +**Usage** + +```js tab=js-js +// playwright.config.js +// @ts-check + +/** @type {import('@playwright/test').PlaywrightTestConfig} */ +const config = { + shard: { total: 10, current: 3 }, +}; + +module.exports = config; +``` + +```js tab=js-ts +// playwright.config.ts +import { type PlaywrightTestConfig } from '@playwright/test'; + +const config: PlaywrightTestConfig = { + shard: { total: 10, current: 3 }, +}; +export default config; +``` + ## property: TestConfig.testDir * since: v1.10 - type: ?<[string]> Directory that will be recursively scanned for test files. Defaults to the directory of the configuration file. +**Usage** + ```js tab=js-js // playwright.config.js // @ts-check @@ -495,6 +833,8 @@ 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. +**Usage** + ```js tab=js-js // playwright.config.js // @ts-check @@ -525,6 +865,8 @@ 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)`. +**Usage** + ```js tab=js-js // playwright.config.js // @ts-check @@ -555,6 +897,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`]. Learn more about [various timeouts](../test-timeouts.md). +**Usage** + ```js tab=js-js // playwright.config.js // @ts-check @@ -588,12 +932,38 @@ Whether to update expected snapshots with the actual results produced by the tes Learn more about [snapshots](../test-snapshots.md). +**Usage** + +```js tab=js-js +// playwright.config.js +// @ts-check + +/** @type {import('@playwright/test').PlaywrightTestConfig} */ +const config = { + updateSnapshots: 'missing', +}; + +module.exports = config; +``` + +```js tab=js-ts +// playwright.config.ts +import { type PlaywrightTestConfig } from '@playwright/test'; + +const config: PlaywrightTestConfig = { + updateSnapshots: 'missing', +}; +export default config; +``` + ## property: TestConfig.use * since: v1.10 - type: ?<[TestOptions]> Global options for all tests, for example [`property: TestOptions.browserName`]. Learn more about [configuration](../test-configuration.md) and see [available options][TestOptions]. +**Usage** + ```js tab=js-js // playwright.config.js // @ts-check @@ -634,6 +1004,8 @@ export default config; Launch a development web server (or multiple) during the tests. +**Details** + If the port is specified, Playwright Test will wait for it to be available on `127.0.0.1` or `::1`, before running the tests. If the url is specified, Playwright Test will wait for the URL to return a 2xx, 3xx, 400, 401, 402, or 403 status code before running the tests. For continuous integration, you may want to use the `reuseExistingServer: !process.env.CI` option which does not use an existing server on the CI. To see the stdout, you can set the `DEBUG=pw:webserver` environment variable. @@ -644,6 +1016,8 @@ The `port` (but not the `url`) gets passed over to Playwright as a [`property: T It is also recommended to specify [`property: TestOptions.baseURL`] in the config, so that tests could use relative urls. ::: +**Usage** + ```js tab=js-ts // playwright.config.ts import type { PlaywrightTestConfig } from '@playwright/test'; @@ -764,6 +1138,8 @@ Playwright Test uses worker processes to run tests. There is always at least one Defaults to half of the number of logical CPU cores. Learn more about [parallelism and sharding](../test-parallel.md) with Playwright Test. +**Usage** + ```js tab=js-js // playwright.config.js // @ts-check diff --git a/packages/playwright-test/types/test.d.ts b/packages/playwright-test/types/test.d.ts index 361230b18b..4b7962ca87 100644 --- a/packages/playwright-test/types/test.d.ts +++ b/packages/playwright-test/types/test.d.ts @@ -413,6 +413,8 @@ interface TestConfig { * * Learn more in the [reporters guide](https://playwright.dev/docs/test-reporters). * + * **Usage** + * * ```js * // playwright.config.ts * import type { PlaywrightTestConfig } from '@playwright/test'; @@ -428,6 +430,8 @@ interface TestConfig { /** * Launch a development web server (or multiple) during the tests. * + * **Details** + * * If the port is specified, Playwright Test will wait for it to be available on `127.0.0.1` or `::1`, before running * the tests. If the url is specified, Playwright Test will wait for the URL to return a 2xx, 3xx, 400, 401, 402, or * 403 status code before running the tests. @@ -444,6 +448,8 @@ interface TestConfig { * [testOptions.baseURL](https://playwright.dev/docs/api/class-testoptions#test-options-base-url) in the config, so * that tests could use relative urls. * + * **Usage** + * * ```js * // playwright.config.ts * import type { PlaywrightTestConfig } from '@playwright/test'; @@ -505,6 +511,8 @@ interface TestConfig { /** * Configuration for the `expect` assertion library. Learn more about [various timeouts](https://playwright.dev/docs/test-timeouts). * + * **Usage** + * * ```js * // playwright.config.ts * import type { PlaywrightTestConfig } from '@playwright/test'; @@ -601,6 +609,8 @@ interface TestConfig { * [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. * + * **Usage** + * * ```js * // playwright.config.ts * import type { PlaywrightTestConfig } from '@playwright/test'; @@ -620,6 +630,19 @@ interface TestConfig { * worker process. * * You can configure entire test run to concurrently execute all tests in all files using this option. + * + * **Usage** + * + * ```js + * // playwright.config.ts + * import type { PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * fullyParallel: true, + * }; + * export default config; + * ``` + * */ fullyParallel?: boolean; @@ -629,6 +652,8 @@ interface TestConfig { * * Learn more about [global setup and teardown](https://playwright.dev/docs/test-advanced#global-setup-and-teardown). * + * **Usage** + * * ```js * // playwright.config.ts * import { type PlaywrightTestConfig } from '@playwright/test'; @@ -649,6 +674,8 @@ interface TestConfig { * * Learn more about [global setup and teardown](https://playwright.dev/docs/test-advanced#global-setup-and-teardown). * + * **Usage** + * * ```js * // playwright.config.ts * import { type PlaywrightTestConfig } from '@playwright/test'; @@ -667,6 +694,8 @@ interface TestConfig { * CI to prevent broken setup from running too long and wasting resources. Learn more about * [various timeouts](https://playwright.dev/docs/test-timeouts). * + * **Usage** + * * ```js * // playwright.config.ts * import type { PlaywrightTestConfig } from '@playwright/test'; @@ -685,6 +714,19 @@ interface TestConfig { * 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). + * + * **Usage** + * + * ```js + * // playwright.config.ts + * import type { PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * grep: /smoke/, + * }; + * export default config; + * ``` + * */ grep?: RegExp|Array; @@ -694,12 +736,38 @@ interface TestConfig { * [command line](https://playwright.dev/docs/test-cli) with the `--grep-invert` option. * * `grepInvert` option is also useful for [tagging tests](https://playwright.dev/docs/test-annotations#tag-tests). + * + * **Usage** + * + * ```js + * // playwright.config.ts + * import type { PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * grepInvert: /manual/, + * }; + * export default config; + * ``` + * */ grepInvert?: RegExp|Array; /** * Whether to skip snapshot expectations, such as `expect(value).toMatchSnapshot()` and `await * expect(page).toHaveScreenshot()`. + * + * **Usage** + * + * ```js + * // playwright.config.ts + * import type { PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * ignoreSnapshots: !process.env.CI, + * }; + * export default config; + * ``` + * */ ignoreSnapshots?: boolean; @@ -709,6 +777,8 @@ interface TestConfig { * * Also available in the [command line](https://playwright.dev/docs/test-cli) with the `--max-failures` and `-x` options. * + * **Usage** + * * ```js * // playwright.config.ts * import type { PlaywrightTestConfig } from '@playwright/test'; @@ -724,18 +794,46 @@ interface TestConfig { /** * Metadata that will be put directly to the test report serialized as JSON. + * + * **Usage** + * + * ```js + * // playwright.config.ts + * import type { PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * metadata: 'acceptance tests', + * }; + * export default config; + * ``` + * */ metadata?: Metadata; /** * 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). + * + * **Usage** + * + * ```js + * // playwright.config.ts + * import type { PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * name: 'acceptance tests', + * }; + * export default config; + * ``` + * */ name?: string; /** * The output directory for files created during test execution. Defaults to `/test-results`. * + * **Usage** + * * ```js * // playwright.config.ts * import { type PlaywrightTestConfig } from '@playwright/test'; @@ -746,6 +844,8 @@ interface TestConfig { * export default config; * ``` * + * **Details** + * * 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 @@ -770,14 +870,27 @@ interface TestConfig { outputDir?: string; /** - * **NOTE** Use of [testConfig.snapshotDir](https://playwright.dev/docs/api/class-testconfig#test-config-snapshot-dir) - * is discouraged. Please use + * **NOTE** Use * [testConfig.snapshotPathTemplate](https://playwright.dev/docs/api/class-testconfig#test-config-snapshot-path-template) * to configure snapshot paths. * * 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). * + * **Usage** + * + * ```js + * // playwright.config.ts + * import { type PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * snapshotDir: './snapshots', + * }; + * export default config; + * ``` + * + * **Details** + * * 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). @@ -794,6 +907,8 @@ interface TestConfig { * and * [snapshotAssertions.toMatchSnapshot(name[, options])](https://playwright.dev/docs/api/class-snapshotassertions#snapshot-assertions-to-match-snapshot-1). * + * **Usage** + * * ```js * // playwright.config.ts * import type { PlaywrightTestConfig } from '@playwright/test'; @@ -806,6 +921,8 @@ interface TestConfig { * export default config; * ``` * + * **Details** + * * The value might include some "tokens" that will be replaced with actual values during test execution. * * Consider the following file structure: @@ -892,27 +1009,95 @@ interface TestConfig { * - `'always'` - preserve output for all tests; * - `'never'` - do not preserve output for any tests; * - `'failures-only'` - only preserve output for failed tests. + * + * **Usage** + * + * ```js + * // playwright.config.ts + * import { type PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * preserveOutput: 'always', + * }; + * export default config; + * ``` + * */ preserveOutput?: "always"|"never"|"failures-only"; /** * Playwright Test supports running multiple test projects at the same time. See [TestProject] for more information. + * + * **Usage** + * + * ```js + * // playwright.config.ts + * import { type PlaywrightTestConfig, devices } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * projects: [ + * { name: 'chromium', use: devices['Desktop Chrome'] } + * ] + * }; + * export default config; + * ``` + * */ projects?: Array; /** * Whether to suppress stdio and stderr output from the tests. + * + * **Usage** + * + * ```js + * // playwright.config.ts + * import { type PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * quiet: !!process.env.CI, + * }; + * export default config; + * ``` + * */ quiet?: boolean; /** * The number of times to repeat each test, useful for debugging flaky tests. + * + * **Usage** + * + * ```js + * // playwright.config.ts + * import { type PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * repeatEach: 3, + * }; + * export default config; + * ``` + * */ repeatEach?: number; /** * Whether to report slow test files. Pass `null` to disable this feature. * + * **Usage** + * + * ```js + * // playwright.config.ts + * import { type PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * reportSlowTests: null, + * }; + * export default config; + * ``` + * + * **Details** + * * Test files that took more than `threshold` milliseconds are considered slow, and the slowest ones are reported, no * more than `max` number of them. Passing zero as `max` reports all test files that exceed the threshold. */ @@ -932,6 +1117,8 @@ 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). * + * **Usage** + * * ```js * // playwright.config.ts * import type { PlaywrightTestConfig } from '@playwright/test'; @@ -949,6 +1136,19 @@ interface TestConfig { * 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. + * + * **Usage** + * + * ```js + * // playwright.config.ts + * import { type PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * shard: { total: 10, current: 3 }, + * }; + * export default config; + * ``` + * */ shard?: null|{ /** @@ -965,6 +1165,8 @@ interface TestConfig { /** * Directory that will be recursively scanned for test files. Defaults to the directory of the configuration file. * + * **Usage** + * * ```js * // playwright.config.ts * import type { PlaywrightTestConfig } from '@playwright/test'; @@ -984,6 +1186,8 @@ interface TestConfig { * * For example, `'**\/test-assets/**'` will ignore any files in the `test-assets` directory. * + * **Usage** + * * ```js * // playwright.config.ts * import { type PlaywrightTestConfig } from '@playwright/test'; @@ -1003,6 +1207,8 @@ interface TestConfig { * * By default, Playwright Test looks for files matching `.*(test|spec)\.(js|ts|mjs)`. * + * **Usage** + * * ```js * // playwright.config.ts * import { type PlaywrightTestConfig } from '@playwright/test'; @@ -1023,6 +1229,8 @@ interface TestConfig { * [test.setTimeout(timeout)](https://playwright.dev/docs/api/class-test#test-set-timeout). Learn more about * [various timeouts](https://playwright.dev/docs/test-timeouts). * + * **Usage** + * * ```js * // playwright.config.ts * import type { PlaywrightTestConfig } from '@playwright/test'; @@ -1045,6 +1253,19 @@ interface TestConfig { * time. This is the default. * * Learn more about [snapshots](https://playwright.dev/docs/test-snapshots). + * + * **Usage** + * + * ```js + * // playwright.config.ts + * import { type PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * updateSnapshots: 'missing', + * }; + * export default config; + * ``` + * */ updateSnapshots?: "all"|"none"|"missing"; @@ -1058,6 +1279,8 @@ interface TestConfig { * Defaults to half of the number of logical CPU cores. Learn more about * [parallelism and sharding](https://playwright.dev/docs/test-parallel) with Playwright Test. * + * **Usage** + * * ```js * // playwright.config.ts * import type { PlaywrightTestConfig } from '@playwright/test'; @@ -1097,6 +1320,21 @@ interface TestConfig { export interface Config extends TestConfig { /** * Playwright Test supports running multiple test projects at the same time. See [TestProject] for more information. + * + * **Usage** + * + * ```js + * // playwright.config.ts + * import { type PlaywrightTestConfig, devices } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * projects: [ + * { name: 'chromium', use: devices['Desktop Chrome'] } + * ] + * }; + * export default config; + * ``` + * */ projects?: Project[]; /** @@ -1104,6 +1342,8 @@ export interface Config extends TestConfig { * [testOptions.browserName](https://playwright.dev/docs/api/class-testoptions#test-options-browser-name). Learn more * about [configuration](https://playwright.dev/docs/test-configuration) and see [available options][TestOptions]. * + * **Usage** + * * ```js * // playwright.config.ts * import type { PlaywrightTestConfig } from '@playwright/test'; @@ -1151,6 +1391,8 @@ export interface FullConfig { * [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. * + * **Usage** + * * ```js * // playwright.config.ts * import type { PlaywrightTestConfig } from '@playwright/test'; @@ -1169,6 +1411,19 @@ export interface FullConfig { * worker process. * * You can configure entire test run to concurrently execute all tests in all files using this option. + * + * **Usage** + * + * ```js + * // playwright.config.ts + * import type { PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * fullyParallel: true, + * }; + * export default config; + * ``` + * */ fullyParallel: boolean; /** @@ -1177,6 +1432,8 @@ export interface FullConfig { * * Learn more about [global setup and teardown](https://playwright.dev/docs/test-advanced#global-setup-and-teardown). * + * **Usage** + * * ```js * // playwright.config.ts * import { type PlaywrightTestConfig } from '@playwright/test'; @@ -1196,6 +1453,8 @@ export interface FullConfig { * * Learn more about [global setup and teardown](https://playwright.dev/docs/test-advanced#global-setup-and-teardown). * + * **Usage** + * * ```js * // playwright.config.ts * import { type PlaywrightTestConfig } from '@playwright/test'; @@ -1213,6 +1472,8 @@ export interface FullConfig { * CI to prevent broken setup from running too long and wasting resources. Learn more about * [various timeouts](https://playwright.dev/docs/test-timeouts). * + * **Usage** + * * ```js * // playwright.config.ts * import type { PlaywrightTestConfig } from '@playwright/test'; @@ -1230,6 +1491,19 @@ export interface FullConfig { * 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). + * + * **Usage** + * + * ```js + * // playwright.config.ts + * import type { PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * grep: /smoke/, + * }; + * export default config; + * ``` + * */ grep: RegExp | RegExp[]; /** @@ -1238,6 +1512,19 @@ export interface FullConfig { * [command line](https://playwright.dev/docs/test-cli) with the `--grep-invert` option. * * `grepInvert` option is also useful for [tagging tests](https://playwright.dev/docs/test-annotations#tag-tests). + * + * **Usage** + * + * ```js + * // playwright.config.ts + * import type { PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * grepInvert: /manual/, + * }; + * export default config; + * ``` + * */ grepInvert: RegExp | RegExp[] | null; /** @@ -1246,6 +1533,8 @@ export interface FullConfig { * * Also available in the [command line](https://playwright.dev/docs/test-cli) with the `--max-failures` and `-x` options. * + * **Usage** + * * ```js * // playwright.config.ts * import type { PlaywrightTestConfig } from '@playwright/test'; @@ -1260,6 +1549,19 @@ export interface FullConfig { maxFailures: number; /** * Metadata that will be put directly to the test report serialized as JSON. + * + * **Usage** + * + * ```js + * // playwright.config.ts + * import type { PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * metadata: 'acceptance tests', + * }; + * export default config; + * ``` + * */ metadata: Metadata; version: string; @@ -1270,10 +1572,38 @@ export interface FullConfig { * - `'always'` - preserve output for all tests; * - `'never'` - do not preserve output for any tests; * - `'failures-only'` - only preserve output for failed tests. + * + * **Usage** + * + * ```js + * // playwright.config.ts + * import { type PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * preserveOutput: 'always', + * }; + * export default config; + * ``` + * */ preserveOutput: 'always' | 'never' | 'failures-only'; /** * Playwright Test supports running multiple test projects at the same time. See [TestProject] for more information. + * + * **Usage** + * + * ```js + * // playwright.config.ts + * import { type PlaywrightTestConfig, devices } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * projects: [ + * { name: 'chromium', use: devices['Desktop Chrome'] } + * ] + * }; + * export default config; + * ``` + * */ projects: FullProject[]; /** @@ -1286,6 +1616,8 @@ export interface FullConfig { * * Learn more in the [reporters guide](https://playwright.dev/docs/test-reporters). * + * **Usage** + * * ```js * // playwright.config.ts * import type { PlaywrightTestConfig } from '@playwright/test'; @@ -1301,6 +1633,20 @@ export interface FullConfig { /** * Whether to report slow test files. Pass `null` to disable this feature. * + * **Usage** + * + * ```js + * // playwright.config.ts + * import { type PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * reportSlowTests: null, + * }; + * export default config; + * ``` + * + * **Details** + * * Test files that took more than `threshold` milliseconds are considered slow, and the slowest ones are reported, no * more than `max` number of them. Passing zero as `max` reports all test files that exceed the threshold. */ @@ -1308,12 +1654,38 @@ export interface FullConfig { rootDir: string; /** * Whether to suppress stdio and stderr output from the tests. + * + * **Usage** + * + * ```js + * // playwright.config.ts + * import { type PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * quiet: !!process.env.CI, + * }; + * export default config; + * ``` + * */ quiet: boolean; /** * 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. + * + * **Usage** + * + * ```js + * // playwright.config.ts + * import { type PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * shard: { total: 10, current: 3 }, + * }; + * export default config; + * ``` + * */ shard: { total: number, current: number } | null; /** @@ -1325,6 +1697,19 @@ export interface FullConfig { * time. This is the default. * * Learn more about [snapshots](https://playwright.dev/docs/test-snapshots). + * + * **Usage** + * + * ```js + * // playwright.config.ts + * import { type PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * updateSnapshots: 'missing', + * }; + * export default config; + * ``` + * */ updateSnapshots: 'all' | 'none' | 'missing'; /** @@ -1337,6 +1722,8 @@ export interface FullConfig { * Defaults to half of the number of logical CPU cores. Learn more about * [parallelism and sharding](https://playwright.dev/docs/test-parallel) with Playwright Test. * + * **Usage** + * * ```js * // playwright.config.ts * import type { PlaywrightTestConfig } from '@playwright/test'; @@ -1352,6 +1739,8 @@ export interface FullConfig { /** * Launch a development web server (or multiple) during the tests. * + * **Details** + * * If the port is specified, Playwright Test will wait for it to be available on `127.0.0.1` or `::1`, before running * the tests. If the url is specified, Playwright Test will wait for the URL to return a 2xx, 3xx, 400, 401, 402, or * 403 status code before running the tests. @@ -1368,6 +1757,8 @@ export interface FullConfig { * [testOptions.baseURL](https://playwright.dev/docs/api/class-testoptions#test-options-base-url) in the config, so * that tests could use relative urls. * + * **Usage** + * * ```js * // playwright.config.ts * import type { PlaywrightTestConfig } from '@playwright/test'; @@ -1916,6 +2307,8 @@ interface SuiteFunction { /** * Declares a group of tests. * + * **Usage** + * * ```js * test.describe('two tests', () => { * test('one', async ({ page }) => { @@ -1938,6 +2331,8 @@ interface SuiteFunction { * Declares an anonymous group of tests. This is convenient to give a group of tests a common option with * [test.use(options)](https://playwright.dev/docs/api/class-test#test-use). * + * **Usage** + * * ```js * test.describe(() => { * test.use({ colorScheme: 'dark' }); @@ -1982,6 +2377,8 @@ export interface TestType { * // Run only focused tests in the entire project. @@ -1995,6 +2392,8 @@ export interface TestType { * test('one', async ({ page }) => { @@ -2017,6 +2416,8 @@ export interface TestType { * test('in the focused group', async ({ page }) => { @@ -2039,6 +2440,8 @@ export interface TestType { * test('example', async ({ page }) => { @@ -2058,6 +2461,8 @@ export interface TestType { * test('example', async ({ page }) => { @@ -2073,16 +2478,17 @@ export interface TestType { * test('runs first', async ({ page }) => {}); @@ -2097,6 +2503,9 @@ export interface TestType { * test('runs first', async ({ page }) => { @@ -2121,14 +2532,15 @@ export interface TestType { @@ -2146,9 +2558,22 @@ export interface TestType { + * test('runs in parallel 1', async ({ page }) => {}); + * test('runs in parallel 2', async ({ page }) => {}); + * }); + * ``` + * * @param title Group title. * @param callback A callback that is run immediately when calling * [test.describe.parallel.only(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-parallel-only). @@ -2162,32 +2587,36 @@ export interface TestType {}); - * test('runs in parallel 2', async ({ page }) => {}); - * ``` + * ```js + * // Run all the tests in the file concurrently using parallel workers. + * test.describe.configure({ mode: 'parallel' }); + * test('runs in parallel 1', async ({ page }) => {}); + * test('runs in parallel 2', async ({ page }) => {}); + * ``` * - * Running tests sequentially: + * - Running tests serially, retrying from the start. * - * ```js - * // Annotate tests as inter-dependent. - * test.describe.configure({ mode: 'serial' }); - * test('runs first', async ({ page }) => {}); - * test('runs second', async ({ page }) => {}); - * ``` + * **NOTE** Running serially is not recommended. It is usually better to make your tests isolated, so they can be + * run independently. * - * Configuring retries and timeout for each test: + * ```js + * // Annotate tests as inter-dependent. + * test.describe.configure({ mode: 'serial' }); + * test('runs first', async ({ page }) => {}); + * test('runs second', async ({ page }) => {}); + * ``` * - * ```js - * // Each test in the file will be retried twice and have a timeout of 20 seconds. - * test.describe.configure({ retries: 2, timeout: 20_000 }); - * test('runs first', async ({ page }) => {}); - * test('runs second', async ({ page }) => {}); - * ``` + * - Configuring retries and timeout for each test. + * + * ```js + * // Each test in the file will be retried twice and have a timeout of 20 seconds. + * test.describe.configure({ retries: 2, timeout: 20_000 }); + * test('runs first', async ({ page }) => {}); + * test('runs second', async ({ page }) => {}); + * ``` * * @param options */ @@ -2198,6 +2627,8 @@ export interface TestType { - * test.setTimeout(120000); - * // ... - * }); - * ``` - * - * Changing timeout from a slow `beforeEach` or `afterEach` hook. Note that this affects the test timeout that is - * shared with `beforeEach`/`afterEach` hooks. - * - * ```js - * import { test, expect } from '@playwright/test'; - * - * test.beforeEach(async ({ page }, testInfo) => { - * // Extend timeout for all tests running this hook by 30 seconds. - * test.setTimeout(testInfo.timeout + 30000); - * }); - * ``` - * - * Changing timeout for a `beforeAll` or `afterAll` hook. Note this affects the hook's timeout, not the test timeout. - * - * ```js - * import { test, expect } from '@playwright/test'; - * - * test.beforeAll(async () => { - * // Set timeout for this hook. - * test.setTimeout(60000); - * }); - * ``` - * - * Changing timeout for all tests in a - * [test.describe(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-1) group. - * - * ```js - * import { test, expect } from '@playwright/test'; - * - * test.describe('group', () => { - * // Applies to all tests in this group. - * test.describe.configure({ timeout: 60000 }); - * - * test('test one', async () => { /* ... *\/ }); - * test('test two', async () => { /* ... *\/ }); - * test('test three', async () => { /* ... *\/ }); - * }); - * ``` - * * Timeout for the currently running test is available through * [testInfo.timeout](https://playwright.dev/docs/api/class-testinfo#test-info-timeout). + * + * **Usage** + * - Changing test timeout. + * + * ```js + * test('very slow test', async ({ page }) => { + * test.setTimeout(120000); + * // ... + * }); + * ``` + * + * - Changing timeout from a slow `beforeEach` or `afterEach` hook. Note that this affects the test timeout that is + * shared with `beforeEach`/`afterEach` hooks. + * + * ```js + * test.beforeEach(async ({ page }, testInfo) => { + * // Extend timeout for all tests running this hook by 30 seconds. + * test.setTimeout(testInfo.timeout + 30000); + * }); + * ``` + * + * - Changing timeout for a `beforeAll` or `afterAll` hook. Note this affects the hook's timeout, not the test + * timeout. + * + * ```js + * test.beforeAll(async () => { + * // Set timeout for this hook. + * test.setTimeout(60000); + * }); + * ``` + * + * - Changing timeout for all tests in a + * [test.describe(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-1) group. + * + * ```js + * test.describe('group', () => { + * // Applies to all tests in this group. + * test.describe.configure({ timeout: 60000 }); + * + * test('test one', async () => { /* ... *\/ }); + * test('test two', async () => { /* ... *\/ }); + * test('test three', async () => { /* ... *\/ }); + * }); + * ``` + * * @param timeout Timeout in milliseconds. */ setTimeout(timeout: number): void; /** - * Declares a `beforeEach` hook that is executed before each test. When called in the scope of a test file, runs - * before each test in the file. When called inside a + * Declares a `beforeEach` hook that is executed before each test. + * + * **Details** + * + * When called in the scope of a test file, runs before each test in the file. When called inside a * [test.describe(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-1) group, runs before * each test in the group. If multiple `beforeEach` hooks are added, they will run in the order of their * registration. @@ -2554,6 +3013,11 @@ export interface TestType Promise | any): void; /** - * Declares an `afterEach` hook that is executed after each test. When called in the scope of a test file, runs after - * each test in the file. When called inside a + * Declares an `afterEach` hook that is executed after each test. + * + * **Details** + * + * When called in the scope of a test file, runs after each test in the file. When called inside a * [test.describe(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-1) group, runs after each * test in the group. If multiple `afterEach` hooks are added, they will run in the order of their registration. * * You can access all the same [Fixtures] as the test function itself, and also the [TestInfo] object that gives a lot * of useful information. For example, you can check whether the test succeeded or failed. * + * **Usage** + * * ```js * // example.spec.ts * import { test, expect } from '@playwright/test'; @@ -2602,11 +3069,22 @@ export interface TestType Promise | any): void; /** - * Declares a `beforeAll` hook that is executed once per worker process before all tests. When called in the scope of - * a test file, runs before all tests in the file. When called inside a + * Declares a `beforeAll` hook that is executed once per worker process before all tests. + * + * **Details** + * + * When called in the scope of a test file, runs before all tests in the file. When called inside a * [test.describe(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-1) group, runs before all * tests in the group. If multiple `beforeAll` hooks are added, they will run in the order of their registration. * + * Note that worker process is restarted on test failures, and `beforeAll` hook runs again in the new worker. Learn + * more about [workers and failures](https://playwright.dev/docs/test-retries). + * + * You can use [test.afterAll(hookFunction)](https://playwright.dev/docs/api/class-test#test-after-all) to teardown + * any resources set up in `beforeAll`. + * + * **Usage** + * * ```js * // example.spec.ts * import { test, expect } from '@playwright/test'; @@ -2624,30 +3102,39 @@ export interface TestType Promise | any): void; /** - * Declares an `afterAll` hook that is executed once per worker after all tests. When called in the scope of a test - * file, runs after all tests in the file. When called inside a + * Declares an `afterAll` hook that is executed once per worker after all tests. + * + * **Details** + * + * When called in the scope of a test file, runs after all tests in the file. When called inside a * [test.describe(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-1) group, runs after all * tests in the group. If multiple `afterAll` hooks are added, they will run in the order of their registration. * * Note that worker process is restarted on test failures, and `afterAll` hook runs again in the new worker. Learn * more about [workers and failures](https://playwright.dev/docs/test-retries). + * + * **Usage** + * + * ```js + * test.afterAll(async () => { + * console.log('Done with tests'); + * // ... + * }); + * ``` + * * @param hookFunction Hook function that takes one or two arguments: an object with worker fixtures and optional [TestInfo]. */ afterAll(inner: (args: TestArgs & WorkerArgs, testInfo: TestInfo) => Promise | any): void; /** * Specifies options or fixtures to use in a single test file or a * [test.describe(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-1) group. Most useful to - * set an option, for example set `locale` to configure `context` fixture. `test.use` can be called either in the - * global scope or inside `test.describe`. It is an error to call it within `beforeEach` or `beforeAll`. + * set an option, for example set `locale` to configure `context` fixture. + * + * **Usage** * * ```js * import { test, expect } from '@playwright/test'; @@ -2659,6 +3146,11 @@ export interface TestType(title: string, body: () => Promise): Promise; /** - * `expect` function can be used to create test assertions. Read - * [expect library documentation](https://jestjs.io/docs/expect) for more details. + * `expect` function can be used to create test assertions. Read more about [test assertions](https://playwright.dev/docs/test-assertions). + * + * **Usage** + * + * ```js + * test('example', async ({ page }) => { + * await test.expect(page).toHaveTitle('Title'); + * }); + * ``` + * */ expect: Expect; /** * Extends the `test` object by defining fixtures and/or options that can be used in the tests. * + * **Usage** + * * First define a fixture and/or an option. * * ```js @@ -2786,6 +3292,16 @@ export interface TestType { + * // ... + * await test.info().attach('screenshot', { body: await page.screenshot(), contentType: 'image/png' }); + * }); + * ``` + * */ info(): TestInfo; } @@ -3208,6 +3724,16 @@ export interface PlaywrightWorkerArgs { * efficient. However, each test runs in an isolated [BrowserContext] and gets a fresh environment. * * Learn how to [configure browser](https://playwright.dev/docs/test-configuration) and see [available options][TestOptions]. + * + * **Usage** + * + * ```js + * test.beforeAll(async ({ browser }) => { + * const page = await browser.newPage(); + * // ... + * }); + * ``` + * */ browser: Browser; } @@ -3245,6 +3771,16 @@ export interface PlaywrightTestArgs { * Learn how to [configure context](https://playwright.dev/docs/test-configuration) and see [available options][TestOptions]. * * Default [fixtures.page](https://playwright.dev/docs/api/class-fixtures#fixtures-page) belongs to this context. + * + * **Usage** + * + * ```js + * test('example test', async ({ page, context }) => { + * await context.route('*external.com/*', route => route.abort()); + * // ... + * }); + * ``` + * */ context: BrowserContext; /** @@ -3253,6 +3789,8 @@ export interface PlaywrightTestArgs { * * This is the most common fixture used in a test. * + * **Usage** + * * ```js * import { test, expect } from '@playwright/test'; * @@ -3270,6 +3808,8 @@ export interface PlaywrightTestArgs { /** * Isolated [APIRequestContext] instance for each test. * + * **Usage** + * * ```js * import { test, expect } from '@playwright/test'; * @@ -4739,6 +5279,8 @@ interface TestProject { * and * [snapshotAssertions.toMatchSnapshot(name[, options])](https://playwright.dev/docs/api/class-snapshotassertions#snapshot-assertions-to-match-snapshot-1). * + * **Usage** + * * ```js * // playwright.config.ts * import type { PlaywrightTestConfig } from '@playwright/test'; @@ -4751,6 +5293,8 @@ interface TestProject { * export default config; * ``` * + * **Details** + * * The value might include some "tokens" that will be replaced with actual values during test execution. * * Consider the following file structure: