Filip/playwright
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

docs: add proper usage for some test apis (#19925)

Browse source
This commit is contained in:
Dmitry Gozman 2023-01-06 10:26:23 -08:00 committed by GitHub
parent c339e1615b
commit b376110b77
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 1295 additions and 261 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
docs/src/api/params.md
View file

@ -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:

38
docs/src/test-api/class-fixtures.md
View file

@ -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');

380
docs/src/test-api/class-test.md
View file

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

388
docs/src/test-api/class-testconfig.md
View file

@ -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 `<package.json-directory>/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

746
packages/playwright-test/types/test.d.ts vendored
View file

File diff suppressed because it is too large Load diff