From fb29d90052a5169325fcd50a1e6f98c340d6040d Mon Sep 17 00:00:00 2001 From: Dmitry Gozman Date: Mon, 5 Feb 2024 19:03:04 -0800 Subject: [PATCH] docs: remove overloads from test.* APIs (#29376) --- docs/src/puppeteer-js.md | 2 +- docs/src/release-notes-js.md | 2 +- docs/src/test-annotations-js.md | 8 +- docs/src/test-api/class-test.md | 887 +++++------ docs/src/test-api/class-testinfo.md | 28 +- docs/src/test-reporter-api/class-suite.md | 6 +- docs/src/test-reporter-api/class-testcase.md | 8 +- docs/src/test-retries-js.md | 2 +- docs/src/test-timeouts-js.md | 2 +- packages/playwright/types/test.d.ts | 1494 +++++++++++++++--- packages/playwright/types/testReporter.d.ts | 35 +- utils/generate_types/index.js | 2 +- utils/generate_types/overrides-test.d.ts | 4 +- 13 files changed, 1675 insertions(+), 805 deletions(-) diff --git a/docs/src/puppeteer-js.md b/docs/src/puppeteer-js.md index 3c3f5d5c99..e620bed9ea 100644 --- a/docs/src/puppeteer-js.md +++ b/docs/src/puppeteer-js.md @@ -135,7 +135,7 @@ test.describe('Playwright homepage', () => { 1. Each Playwright Test file has explicit import of the `test` and `expect` functions 1. Test function is marked with `async` 1. Playwright Test is given a `page` as one of its parameters. This is one of the many [useful fixtures](./api/class-fixtures) in Playwright Test. -Playwright Test creates an isolated [Page] object for each test. However, if you'd like to reuse a single [Page] object between multiple tests, you can create your own in [`method: Test.beforeAll#1`] and close it in [`method: Test.afterAll#1`]. +Playwright Test creates an isolated [Page] object for each test. However, if you'd like to reuse a single [Page] object between multiple tests, you can create your own in [`method: Test.beforeAll`] and close it in [`method: Test.afterAll`]. 1. Locator creation with [`method: Page.locator`] is one of the few methods that is sync. 1. Use [assertions](./test-assertions) to verify the state instead of `page.$eval()`. diff --git a/docs/src/release-notes-js.md b/docs/src/release-notes-js.md index 5debb1c84c..d774faf496 100644 --- a/docs/src/release-notes-js.md +++ b/docs/src/release-notes-js.md @@ -1110,7 +1110,7 @@ Linux support looks like this: ### 🕵️ Anonymous Describe -It is now possible to call [`method: Test.describe#2`] to create suites without a title. This is useful for giving a group of tests a common option with [`method: Test.use`]. +It is now possible to call [`method: Test.describe`] to create suites without a title. This is useful for giving a group of tests a common option with [`method: Test.use`]. ```ts test.describe(() => { diff --git a/docs/src/test-annotations-js.md b/docs/src/test-annotations-js.md index f9e8c0678c..15a7f0529b 100644 --- a/docs/src/test-annotations-js.md +++ b/docs/src/test-annotations-js.md @@ -6,10 +6,10 @@ title: "Annotations" ## Introduction Playwright Test supports test annotations to deal with failures, flakiness, skip, focus and tag tests: -- [`method: Test.skip#1`] marks the test as irrelevant. Playwright Test does not run such a test. Use this annotation when the test is not applicable in some configuration. -- [`method: Test.fail#1`] marks the test as failing. Playwright Test will run this test and ensure it does indeed fail. If the test does not fail, Playwright Test will complain. -- [`method: Test.fixme#1`] marks the test as failing. Playwright Test will not run this test, as opposed to the `fail` annotation. Use `fixme` when running the test is slow or crashes. -- [`method: Test.slow#1`] marks the test as slow and triples the test timeout. +- [`method: Test.skip`] marks the test as irrelevant. Playwright Test does not run such a test. Use this annotation when the test is not applicable in some configuration. +- [`method: Test.fail`] marks the test as failing. Playwright Test will run this test and ensure it does indeed fail. If the test does not fail, Playwright Test will complain. +- [`method: Test.fixme`] marks the test as failing. Playwright Test will not run this test, as opposed to the `fail` annotation. Use `fixme` when running the test is slow or crashes. +- [`method: Test.slow`] marks the test as slow and triples the test timeout. Annotations can be used on a single test or a group of tests. Annotations can be conditional, in which case they apply when the condition is truthy. Annotations may depend on test fixtures. There could be multiple annotations on the same test, possibly in different configurations. diff --git a/docs/src/test-api/class-test.md b/docs/src/test-api/class-test.md index 764447cee4..583373fac9 100644 --- a/docs/src/test-api/class-test.md +++ b/docs/src/test-api/class-test.md @@ -36,27 +36,32 @@ test('basic test', async ({ page }) => { Test title. -### param: Test.(call).testFunction +### param: Test.(call).body * since: v1.10 -- `testFunction` <[function]\([Fixtures], [TestInfo]\)> +- `body` <[function]\([Fixtures], [TestInfo]\)> -Test function that takes one or two arguments: an object with fixtures and optional [TestInfo]. +Test body that takes one or two arguments: an object with fixtures and optional [TestInfo]. -## method: Test.afterAll#1 +## 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`] group, runs after all tests in the group. + **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. +When 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). Playwright will continue running all applicable hooks even if some of them have failed. +* `test.afterAll(hookFunction)` +* `test.afterAll(title, hookFunction)` + **Usage** ```js @@ -66,23 +71,7 @@ test.afterAll(async () => { }); ``` -### param: Test.afterAll#1.hookFunction -* since: v1.10 -- `hookFunction` <[function]\([Fixtures], [TestInfo]\)> - -Hook function that takes one or two arguments: an object with worker fixtures and optional [TestInfo]. - - -## method: Test.afterAll#2 -* since: v1.38 - -Declares an `afterAll` hook with a title that is executed once per worker after all tests. - -**Details** - -See [`method: Test.afterAll#1`]. - -**Usage** +Alternatively, you can declare a hook **with a title**. ```js test.afterAll('Teardown', async () => { @@ -91,42 +80,48 @@ test.afterAll('Teardown', async () => { }); ``` -### param: Test.afterAll#2.title +### param: Test.afterAll.title * since: v1.38 -- `title` <[string]> +- `title` ?<[string]> Hook title. -### param: Test.afterAll#2.hookFunction -* since: v1.38 +### param: Test.afterAll.hookFunction +* since: v1.10 - `hookFunction` <[function]\([Fixtures], [TestInfo]\)> Hook function that takes one or two arguments: an object with worker fixtures and optional [TestInfo]. -## method: Test.afterEach#1 +## 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`] group, runs after each test in the group. + +You can access all the same [Fixtures] as the test body itself, and also the [TestInfo] object that gives a lot of useful information. For example, you can check whether the test succeeded or failed. + +* `test.afterEach(hookFunction)` +* `test.afterEach(title, hookFunction)` + **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. +When multiple `afterEach` hooks are added, they will run in the order of their registration. Playwright will continue running all applicable hooks even if some of them have failed. **Usage** + ```js title="example.spec.ts" import { test, expect } from '@playwright/test'; -test.afterEach(async ({ page }, testInfo) => { - console.log(`Finished ${testInfo.title} with status ${testInfo.status}`); +test.afterEach(async ({ page }) => { + console.log(`Finished ${test.info().title} with status ${test.info().status}`); - if (testInfo.status !== testInfo.expectedStatus) + if (test.info().status !== test.info().expectedStatus) console.log(`Did not run as expected, ended up at ${page.url()}`); }); @@ -135,70 +130,52 @@ test('my test', async ({ page }) => { }); ``` -### param: Test.afterEach#1.hookFunction +Alternatively, you can delcare a hook **with a title**. + +```js title="example.spec.ts" +test.afterEach('Status check', async ({ page }) => { + if (test.info().status !== test.info().expectedStatus) + console.log(`Did not run as expected, ended up at ${page.url()}`); +}); +``` + +### param: Test.afterEach.title +* since: v1.38 +- `title` ?<[string]> + +Hook title. + +### param: Test.afterEach.hookFunction * since: v1.10 - `hookFunction` <[function]\([Fixtures], [TestInfo]\)> Hook function that takes one or two arguments: an object with fixtures and optional [TestInfo]. -## method: Test.afterEach#2 -* since: v1.38 -Declares an `afterEach` hook with a title that is executed after each test. - -**Details** - -See [`method: Test.afterEach#1`]. - -**Usage** - -```js title="example.spec.ts" -import { test, expect } from '@playwright/test'; - -test.afterEach('Status check', async ({ page }, testInfo) => { - console.log(`Finished ${testInfo.title} with status ${testInfo.status}`); - - if (testInfo.status !== testInfo.expectedStatus) - console.log(`Did not run as expected, ended up at ${page.url()}`); -}); - -test('my test', async ({ page }) => { - // ... -}); -``` - -### param: Test.afterEach#2.title -* since: v1.38 -- `title` <[string]> - -Hook title. - -### param: Test.afterEach#2.hookFunction -* since: v1.38 -- `hookFunction` <[function]\([Fixtures], [TestInfo]\)> - -Hook function that takes one or two arguments: an object with fixtures and optional [TestInfo]. - - - -## method: Test.beforeAll#1 +## 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`] group, runs before all tests in the group. + +You can use [`method: Test.afterAll`] to teardown any resources set up in `beforeAll`. + +* `test.beforeAll(hookFunction)` +* `test.beforeAll(title, hookFunction)` + **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. +When 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). Playwright will continue running all applicable hooks even if some of them have failed. -You can use [`method: Test.afterAll#1`] to teardown any resources set up in `beforeAll`. - **Usage** + ```js title="example.spec.ts" import { test, expect } from '@playwright/test'; @@ -215,72 +192,55 @@ test('my test', async ({ page }) => { }); ``` -### param: Test.beforeAll#1.hookFunction + +Alternatively, you can declare a hook **with a title**. + +```js title="example.spec.ts" +test.beforeAll('Setup', async () => { + console.log('Before tests'); +}); +``` + +### param: Test.beforeAll.title +* since: v1.38 +- `title` ?<[string]> + +Hook title. + +### param: Test.beforeAll.hookFunction * since: v1.10 - `hookFunction` <[function]\([Fixtures], [TestInfo]\)> Hook function that takes one or two arguments: an object with worker fixtures and optional [TestInfo]. -## method: Test.beforeAll#2 -* since: v1.38 - -Declares a `beforeAll` hook with a title that is executed once per worker process before all tests. - -**Details** - -See [`method: Test.beforeAll#1`]. - -**Usage** - -```js title="example.spec.ts" -import { test, expect } from '@playwright/test'; - -test.beforeAll('Setup', async () => { - console.log('Before tests'); -}); - -test('my test', async ({ page }) => { - // ... -}); -``` - -### param: Test.beforeAll#2.title -* since: v1.38 -- `title` <[string]> - -Hook title. - -### param: Test.beforeAll#2.hookFunction -* since: v1.38 -- `hookFunction` <[function]\([Fixtures], [TestInfo]\)> - -Hook function that takes one or two arguments: an object with worker fixtures and optional [TestInfo]. - - - -## method: Test.beforeEach#1 +## 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`] group, runs before each test in the group. + +You can access all the same [Fixtures] as the test body 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`. + +* `test.beforeEach(hookFunction)` +* `test.beforeEach(title, hookFunction)` + **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. +When multiple `beforeEach` hooks are added, they will run in the order of their registration. Playwright will continue running all applicable hooks even if some of them have failed. -You can use [`method: Test.afterEach#1`] to teardown any resources set up in `beforeEach`. - **Usage** ```js title="example.spec.ts" import { test, expect } from '@playwright/test'; -test.beforeEach(async ({ page }, testInfo) => { - console.log(`Running ${testInfo.title}`); +test.beforeEach(async ({ page }) => { + console.log(`Running ${test.info().title}`); await page.goto('https://my.start.url/'); }); @@ -289,58 +249,41 @@ test('my test', async ({ page }) => { }); ``` -### param: Test.beforeEach#1.hookFunction +Alternatively, you can declare a hook **with a title**. + +```js title="example.spec.ts" +test.beforeEach('Open start URL', async ({ page }) => { + console.log(`Running ${test.info().title}`); + await page.goto('https://my.start.url/'); +}); +``` + +### param: Test.beforeEach.title +* since: v1.38 +- `title` ?<[string]> + +Hook title. + +### param: Test.beforeEach.hookFunction * since: v1.10 - `hookFunction` <[function]\([Fixtures], [TestInfo]\)> Hook function that takes one or two arguments: an object with fixtures and optional [TestInfo]. -## method: Test.beforeEach#2 -* since: v1.38 -Declares a `beforeEach` hook with a title that is executed before each test. - -**Details** - -See [`method: Test.beforeEach#1`]. - -**Usage** - -```js title="example.spec.ts" -import { test, expect } from '@playwright/test'; - -test.beforeEach('Open start URL', async ({ page }, testInfo) => { - console.log(`Running ${testInfo.title}`); - await page.goto('https://my.start.url/'); -}); - -test('my test', async ({ page }) => { - expect(page.url()).toBe('https://my.start.url/'); -}); -``` - -### param: Test.beforeEach#2.title -* since: v1.38 -- `title` <[string]> - -Hook title. - -### param: Test.beforeEach#2.hookFunction -* since: v1.38 -- `hookFunction` <[function]\([Fixtures], [TestInfo]\)> - -Hook function that takes one or two arguments: an object with fixtures and optional [TestInfo]. - - - -## method: Test.describe#1 +## method: Test.describe * since: v1.10 Declares a group of tests. +* `test.describe(title, callback)` +* `test.describe(callback)` + **Usage** +You can declare a group of tests with a title. The title will be visible in the test report as a part of each test's title. + ```js test.describe('two tests', () => { test('one', async ({ page }) => { @@ -353,25 +296,7 @@ test.describe('two tests', () => { }); ``` -### param: Test.describe#1.title -* since: v1.10 -- `title` <[string]> - -Group title. - -### param: Test.describe#1.callback -* since: v1.10 -- `callback` <[function]> - -A callback that is run immediately when calling [`method: Test.describe#1`]. Any tests added in this callback will belong to the group. - - -## method: Test.describe#2 -* since: v1.24 - -Declares an anonymous group of tests. This is convenient to give a group of tests a common option with [`method: Test.use`]. - -**Usage** +Without a title, this method declares an **anonymous** group of tests. This is convenient to give a group of tests a common option with [`method: Test.use`]. ```js test.describe(() => { @@ -387,11 +312,17 @@ test.describe(() => { }); ``` -### param: Test.describe#2.callback -* since: v1.24 +### param: Test.describe.title +* since: v1.10 +- `title` ?<[string]> + +Group title. + +### param: Test.describe.callback +* since: v1.10 - `callback` <[function]> -A callback that is run immediately when calling [`method: Test.describe#2`]. Any tests added in this callback will belong to the group. +A callback that is run immediately when calling [`method: Test.describe`]. Any tests declared in this callback will belong to the group. @@ -475,21 +406,32 @@ Timeout for each test in milliseconds. Overrides [`property: TestProject.timeout ## method: Test.describe.fixme * since: v1.25 -Declares a test group similarly to [`method: Test.describe#1`]. Tests in this group are marked as "fixme" and will not be executed. +Declares a test group similarly to [`method: Test.describe`]. Tests in this group are marked as "fixme" and will not be executed. + +* `test.describe.fixme(title, callback)` +* `test.describe.fixme(callback)` **Usage** ```js -test.describe.fixme('broken tests', () => { +test.describe.fixme('broken tests that should be fixed', () => { test('example', async ({ page }) => { // This test will not run }); }); ``` +You can also omit the title. + +```js +test.describe.fixme(() => { + // ... +}); +``` + ### param: Test.describe.fixme.title * since: v1.25 -- `title` <[string]> +- `title` ?<[string]> Group title. @@ -506,6 +448,9 @@ 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. +* `test.describe.only(title, callback)` +* `test.describe.only(callback)` + **Usage** ```js @@ -519,9 +464,18 @@ test('not in the focused group', async ({ page }) => { }); ``` +You can also omit the title. + +```js +test.describe.only(() => { + // ... +}); +``` + + ### param: Test.describe.only.title * since: v1.10 -- `title` <[string]> +- `title` ?<[string]> Group title. @@ -539,6 +493,9 @@ A callback that is run immediately when calling [`method: Test.describe.only`]. 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. +* `test.describe.parallel(title, callback)` +* `test.describe.parallel(callback)` + **Usage** ```js @@ -550,9 +507,17 @@ test.describe.parallel('group', () => { Note that parallel tests are executed in separate processes and cannot share any state or global variables. Each of the parallel tests executes all relevant hooks. +You can also omit the title. + +```js +test.describe.parallel(() => { + // ... +}); +``` + ### param: Test.describe.parallel.title * since: v1.10 -- `title` <[string]> +- `title` ?<[string]> Group title. @@ -570,6 +535,9 @@ A callback that is run immediately when calling [`method: Test.describe.parallel 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. +* `test.describe.parallel.only(title, callback)` +* `test.describe.parallel.only(callback)` + **Usage** ```js @@ -579,9 +547,17 @@ test.describe.parallel.only('group', () => { }); ``` +You can also omit the title. + +```js +test.describe.parallel.only(() => { + // ... +}); +``` + ### param: Test.describe.parallel.only.title * since: v1.10 -- `title` <[string]> +- `title` ?<[string]> Group title. @@ -603,6 +579,9 @@ Declares a group of tests that should always be run serially. If one of the test Using serial is not recommended. It is usually better to make your tests isolated, so they can be run independently. ::: +* `test.describe.serial(title, callback)` +* `test.describe.serial(title)` + **Usage** ```js @@ -612,9 +591,17 @@ test.describe.serial('group', () => { }); ``` +You can also omit the title. + +```js +test.describe.serial(() => { + // ... +}); +``` + ### param: Test.describe.serial.title * since: v1.10 -- `title` <[string]> +- `title` ?<[string]> Group title. @@ -636,6 +623,9 @@ 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. ::: +* `test.describe.serial.only(title, callback)` +* `test.describe.serial.only(title)` + **Usage** ```js @@ -647,6 +637,14 @@ test.describe.serial.only('group', () => { }); ``` +You can also omit the title. + +```js +test.describe.serial.only(() => { + // ... +}); +``` + ### param: Test.describe.serial.only.title * since: v1.10 - `title` <[string]> @@ -665,7 +663,10 @@ A callback that is run immediately when calling [`method: Test.describe.serial.o ## method: Test.describe.skip * since: v1.10 -Declares a skipped test group, similarly to [`method: Test.describe#1`]. Tests in the skipped group are never run. +Declares a skipped test group, similarly to [`method: Test.describe`]. Tests in the skipped group are never run. + +* `test.describe.skip(title, callback)` +* `test.describe.skip(title)` **Usage** @@ -677,6 +678,14 @@ test.describe.skip('skipped group', () => { }); ``` +You can also omit the title. + +```js +test.describe.skip(() => { + // ... +}); +``` + ### param: Test.describe.skip.title * since: v1.10 - `title` <[string]> @@ -822,14 +831,20 @@ An object containing fixtures and/or options. Learn more about [fixtures format] +## method: Test.fail +* since: v1.10 -## method: Test.fail#4 -* since: v1.42 +Marks a test as "should fail". Playwright 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. -Declares a test that "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. +* `test.fail(title, body)` +* `test.fail()` +* `test.fail(condition, description)` +* `test.fail(callback, description)` **Usage** +You can declare a test as failing, so that Playwright ensures it actually fails. + ```js import { test, expect } from '@playwright/test'; @@ -838,41 +853,7 @@ test.fail('not yet ready', async ({ page }) => { }); ``` -### param: Test.fail#4.title -* since: v1.42 -- `title` <[string]> - -Test title. - -### param: Test.fail#4.testFunction -* since: v1.42 -- `testFunction` <[function]\([Fixtures], [TestInfo]\)> - -Test function that takes one or two arguments: an object with fixtures and optional [TestInfo]. - - -## method: Test.fail#1 -* since: v1.10 - -Unconditionally 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 -import { test, expect } from '@playwright/test'; - -test('not yet ready', async ({ page }) => { - test.fail(); - // ... -}); -``` - -## method: Test.fail#2 -* since: v1.10 - -Conditionally mark a test as "should fail" with an optional description. - -**Usage** +If your test fails in some configurations, but not all, you can mark the test as failing inside the test body based on some condition. We recommend passing a `description` argument in this case. ```js import { test, expect } from '@playwright/test'; @@ -883,30 +864,12 @@ test('fail in WebKit', async ({ page, browserName }) => { }); ``` -### param: Test.fail#2.condition -* since: v1.10 -- `condition` <[boolean]> - -Test is marked as "should fail" when the condition is `true`. - -### param: Test.fail#2.description -* since: v1.10 -- `description` ?<[string]> - -Optional description that will be reflected in a test report. - - -## method: Test.fail#3 -* since: v1.10 - -Conditionally mark all tests in a file or [`method: Test.describe#1`] group as "should fail". - -**Usage** +You can mark all tests in a file or [`method: Test.describe`] group as "should fail" based on some condition with a single `test.fail(callback, description)` call. ```js import { test, expect } from '@playwright/test'; -test.fail(({ browserName }) => browserName === 'webkit'); +test.fail(({ browserName }) => browserName === 'webkit', 'not implemented yet'); test('fail in WebKit 1', async ({ page }) => { // ... @@ -916,105 +879,133 @@ test('fail in WebKit 2', async ({ page }) => { }); ``` -### param: Test.fail#3.condition +You can also call `test.fail()` without arguments inside the test body to always mark the test as failed. We recommend declaring a failing test with `test.fail(title, body)` instead. + +```js +import { test, expect } from '@playwright/test'; + +test('less readable', async ({ page }) => { + test.fail(); + // ... +}); +``` + +### param: Test.fail.title +* since: v1.42 +- `title` ?<[string]> + +Test title. + +### param: Test.fail.body +* since: v1.42 +- `body` ?<[function]\([Fixtures], [TestInfo]\)> + +Test body that takes one or two arguments: an object with fixtures and optional [TestInfo]. + +### param: Test.fail.condition * since: v1.10 -- `callback` <[function]\([Fixtures]\):[boolean]> +- `condition` ?<[boolean]> + +Test is marked as "should fail" when the condition is `true`. + +### param: Test.fail.callback +* since: v1.10 +- `callback` ?<[function]\([Fixtures]\):[boolean]> A function that returns whether to mark as "should fail", based on test fixtures. Test or tests are marked as "should fail" when the return value is `true`. -### param: Test.fail#3.description +### param: Test.fail.description * since: v1.10 - `description` ?<[string]> Optional description that will be reflected in a test report. -## method: Test.fixme#1 + +## method: Test.fixme * since: v1.10 -Declares a test to be fixed, similarly to [`method: Test.(call)`]. This test will not be run. +Mark a test as "fixme", with the intention to fix it. Playwright will not run the test past the `test.fixme()` call. + +* `test.fixme(title, body)` +* `test.fixme()` +* `test.fixme(condition, description)` +* `test.fixme(callback, description)` **Usage** +You can declare a test as to be fixed, and Playwright will not run it. ```js import { test, expect } from '@playwright/test'; -test.fixme('test to be fixed', async ({ page }) => { +test.fixme('to be fixed', async ({ page }) => { // ... }); ``` -### param: Test.fixme#1.title -* since: v1.10 -- `title` <[string]> - -Test title. - -### param: Test.fixme#1.testFunction -* since: v1.10 -- `testFunction` <[function]\([Fixtures], [TestInfo]\)> - -Test function that takes one or two arguments: an object with fixtures and optional [TestInfo]. - - - -## method: Test.fixme#2 -* since: v1.10 - -Mark a test as "fixme", with the intention to fix it. Test is immediately aborted when you call [`method: Test.fixme#2`]. - -**Usage** +If your test should be fixed in some configurations, but not all, you can mark the test as "fixme" inside the test body based on some condition. We recommend passing a `description` argument in this case. Playwright will run the test, but abort it immediately after the `test.fixme` call. ```js import { test, expect } from '@playwright/test'; -test('test to be fixed', async ({ page }) => { +test('to be fixed in Safari', async ({ page, browserName }) => { + test.fixme(browserName === 'webkit', 'This feature breaks in Safari for some reason'); + // ... +}); +``` + +You can mark all tests in a file or [`method: Test.describe`] group as "fixme" based on some condition with a single `test.fixme(callback, description)` call. + +```js +import { test, expect } from '@playwright/test'; + +test.fixme(({ browserName }) => browserName === 'webkit', 'Should figure out the issue'); + +test('to be fixed in Safari 1', async ({ page }) => { + // ... +}); +test('to be fixed in Safari 2', async ({ page }) => { + // ... +}); +``` + +You can also call `test.fixme()` without arguments inside the test body to always mark the test as failed. We recommend using `test.fixme(title, body)` instead. + +```js +import { test, expect } from '@playwright/test'; + +test('less readable', async ({ page }) => { test.fixme(); // ... }); ``` -Mark all tests in a file or [`method: Test.describe#1`] group as "fixme". - -```js -import { test, expect } from '@playwright/test'; - -test.fixme(); - -test('test to be fixed 1', async ({ page }) => { - // ... -}); -test('test to be fixed 2', async ({ page }) => { - // ... -}); -``` - - -## method: Test.fixme#3 +### param: Test.fixme.title * since: v1.10 +- `title` ?<[string]> -Conditionally mark a test as "fixme" with an optional description. +Test title. -**Usage** - -```js -import { test, expect } from '@playwright/test'; - -test('broken in WebKit', async ({ page, browserName }) => { - test.fixme(browserName === 'webkit', 'This feature is not implemented on Mac yet'); - // ... -}); -``` - - -### param: Test.fixme#3.condition +### param: Test.fixme.body * since: v1.10 -- `condition` <[boolean]> +- `body` ?<[function]\([Fixtures], [TestInfo]\)> -Test is marked as "fixme" when the condition is `true`. +Test body that takes one or two arguments: an object with fixtures and optional [TestInfo]. -### param: Test.fixme#3.description +### param: Test.fixme.condition +* since: v1.10 +- `condition` ?<[boolean]> + +Test is marked as "should fail" when the condition is `true`. + +### param: Test.fixme.callback +* since: v1.10 +- `callback` ?<[function]\([Fixtures]\):[boolean]> + +A function that returns whether to mark as "should fail", based on test fixtures. Test or tests are marked as "should fail" when the return value is `true`. + +### param: Test.fixme.description * since: v1.10 - `description` ?<[string]> @@ -1022,41 +1013,6 @@ Optional description that will be reflected in a test report. - -## method: Test.fixme#4 -* since: v1.10 - -Conditionally mark all tests in a file or [`method: Test.describe#1`] group as "fixme". - -**Usage** - -```js -import { test, expect } from '@playwright/test'; - -test.fixme(({ browserName }) => browserName === 'webkit'); - -test('broken in WebKit 1', async ({ page }) => { - // ... -}); -test('broken in WebKit 2', async ({ page }) => { - // ... -}); -``` - - -### param: Test.fixme#4.condition -* since: v1.10 -- `callback` <[function]\([Fixtures]\):[boolean]> - -A function that returns whether to mark as "fixme", based on test fixtures. Test or tests are marked as "fixme" when the return value is `true`. - -### param: Test.fixme#4.description -* since: v1.10 -- `description` ?<[string]> - -Optional description that will be reflected in a test report. - - ## method: Test.info * since: v1.10 - returns: <[TestInfo]> @@ -1095,11 +1051,11 @@ test.only('focus this test', async ({ page }) => { Test title. -### param: Test.only.testFunction +### param: Test.only.body * since: v1.10 -- `testFunction` <[function]\([Fixtures], [TestInfo]\)> +- `body` <[function]\([Fixtures], [TestInfo]\)> -Test function that takes one or two arguments: an object with fixtures and optional [TestInfo]. +Test body that takes one or two arguments: an object with fixtures and optional [TestInfo]. ## method: Test.setTimeout @@ -1138,7 +1094,7 @@ Timeout for the currently running test is available through [`property: TestInfo }); ``` -* Changing timeout for all tests in a [`method: Test.describe#1`] group. +* Changing timeout for all tests in a [`method: Test.describe`] group. ```js test.describe('group', () => { @@ -1159,137 +1115,92 @@ Timeout in milliseconds. -## method: Test.skip#1 +## method: Test.skip * since: v1.10 -Declares a skipped test, similarly to [`method: Test.(call)`]. Skipped test is never run. +Skip a test. Playwright will not run the test past the `test.skip()` call. + +Skipped tests are not supposed to be ever run. If you intent to fix the test, use [`method: Test.fixme`] instead. + +* `test.skip(title, body)` +* `test.skip()` +* `test.skip(condition, description)` +* `test.skip(callback, description)` **Usage** +You can declare a skipped test, and Playwright will not run it. + ```js import { test, expect } from '@playwright/test'; -test.skip('broken test', async ({ page }) => { +test.skip('never run', async ({ page }) => { // ... }); ``` -### param: Test.skip#1.title -* since: v1.10 -- `title` <[string]> - -Test title. - -### param: Test.skip#1.testFunction -* since: v1.10 -- `testFunction` <[function]\([Fixtures], [TestInfo]\)> - -Test function that takes one or two arguments: an object with fixtures and optional [TestInfo]. - - - -## method: Test.skip#2 -* since: v1.10 - -Unconditionally skip a test. Test is immediately aborted when you call [`method: Test.skip#2`]. - -**Usage** +If your test should be skipped in some configurations, but not all, you can skip the test inside the test body based on some condition. We recommend passing a `description` argument in this case. Playwright will run the test, but abort it immediately after the `test.skip` call. ```js import { test, expect } from '@playwright/test'; -test('skipped test', async ({ page }) => { +test('Safari-only test', async ({ page, browserName }) => { + test.skip(browserName !== 'webkit', 'This feature is Safari-only'); + // ... +}); +``` + +You can skip all tests in a file or [`method: Test.describe`] group based on some condition with a single `test.skip(callback, description)` call. + +```js +import { test, expect } from '@playwright/test'; + +test.skip(({ browserName }) => browserName !== 'webkit', 'Safari-only'); + +test('Safari-only test 1', async ({ page }) => { + // ... +}); +test('Safari-only test 2', async ({ page }) => { + // ... +}); +``` + +You can also call `test.skip()` without arguments inside the test body to always mark the test as failed. We recommend using `test.skip(title, body)` instead. + +```js +import { test, expect } from '@playwright/test'; + +test('less readable', async ({ page }) => { test.skip(); // ... }); ``` -Unconditionally skip all tests in a file or [`method: Test.describe#1`] group: - -```js -import { test, expect } from '@playwright/test'; - -test.skip(); - -test('skipped test 1', async ({ page }) => { - // ... -}); -test('skipped test 2', async ({ page }) => { - // ... -}); -``` - - -## method: Test.skip#3 +### param: Test.skip.title * since: v1.10 +- `title` ?<[string]> -Conditionally skip a test with an optional description. +Test title. -**Usage** - -```js -import { test, expect } from '@playwright/test'; - -test('skip in WebKit', async ({ page, browserName }) => { - test.skip(browserName === 'webkit', 'This feature is not implemented for Mac'); - // ... -}); -``` - -Skip from [`method: Test.beforeEach#1`] hook: - -```js -import { test, expect } from '@playwright/test'; - -test.beforeEach(async ({ page }) => { - test.skip(process.env.APP_VERSION === 'v1', 'There are no settings in v1'); - await page.goto('/settings'); -}); -``` - -### param: Test.skip#3.condition +### param: Test.skip.body * since: v1.10 -- `condition` <[boolean]> +- `body` ?<[function]\([Fixtures], [TestInfo]\)> -A skip condition. Test is skipped when the condition is `true`. +Test body that takes one or two arguments: an object with fixtures and optional [TestInfo]. -### param: Test.skip#3.description +### param: Test.skip.condition * since: v1.10 -- `description` ?<[void]|[string]> +- `condition` ?<[boolean]> -Optional description that will be reflected in a test report. +Test is marked as "should fail" when the condition is `true`. - - - -## method: Test.skip#4 +### param: Test.skip.callback * since: v1.10 +- `callback` ?<[function]\([Fixtures]\):[boolean]> -Conditionally skips all tests in a file or [`method: Test.describe#1`] group. +A function that returns whether to mark as "should fail", based on test fixtures. Test or tests are marked as "should fail" when the return value is `true`. -**Usage** - -```js -import { test, expect } from '@playwright/test'; - -test.skip(({ browserName }) => browserName === 'webkit'); - -test('skip in WebKit 1', async ({ page }) => { - // ... -}); -test('skip in WebKit 2', async ({ page }) => { - // ... -}); -``` - - -### param: Test.skip#4.condition -* since: v1.10 -- `callback` <[function]\([Fixtures]\):[boolean]> - -A function that returns whether to skip, based on test fixtures. Test or tests are skipped when the return value is `true`. - -### param: Test.skip#4.description +### param: Test.skip.description * since: v1.10 - `description` ?<[string]> @@ -1297,17 +1208,23 @@ Optional description that will be reflected in a test report. -## method: Test.slow#1 + + +## method: Test.slow * since: v1.10 -Unconditionally marks a test as "slow". Slow test will be given triple the default timeout. +Marks a test as "slow". Slow test will be given triple the default timeout. -**Details** +Note that [`method: Test.slow`] cannot be used in a `beforeAll` or `afterAll` hook. Use [`method: Test.setTimeout`] instead. -[`method: Test.slow#1`] cannot be used in a `beforeAll` or `afterAll` hook. Use [`method: Test.setTimeout`] instead. +* `test.slow()` +* `test.slow(condition, description)` +* `test.slow(callback, description)` **Usage** +You can mark a test as slow by calling `test.slow()` inside the test body. + ```js import { test, expect } from '@playwright/test'; @@ -1317,68 +1234,52 @@ test('slow test', async ({ page }) => { }); ``` -## 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** +If your test is slow in some configurations, but not all, you can mark it as slow based on a condition. We recommend passing a `description` argument in this case. ```js import { test, expect } from '@playwright/test'; -test('slow in WebKit', async ({ page, browserName }) => { - test.slow(browserName === 'webkit', 'This feature is slow on Mac'); +test('slow in Safari', async ({ page, browserName }) => { + test.slow(browserName === 'webkit', 'This feature is slow in Safari'); // ... }); ``` -### param: Test.slow#2.condition +You can mark all tests in a file or [`method: Test.describe`] group as "slow" based on some condition by passing a callback. + +```js +import { test, expect } from '@playwright/test'; + +test.slow(({ browserName }) => browserName === 'webkit', 'all tests are slow in Safari'); + +test('slow in Safari 1', async ({ page }) => { + // ... +}); +test('fail in Safari 2', async ({ page }) => { + // ... +}); +``` + +### param: Test.slow.condition * since: v1.10 -- `condition` <[boolean]> +- `condition` ?<[boolean]> Test is marked as "slow" when the condition is `true`. -### param: Test.slow#2.description +### param: Test.slow.callback * since: v1.10 -- `description` ?<[string]> - -Optional description that will be reflected in a test report. - - -## method: Test.slow#3 -* since: v1.10 - -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 -import { test, expect } from '@playwright/test'; - -test.slow(({ browserName }) => browserName === 'webkit'); - -test('slow in WebKit 1', async ({ page }) => { - // ... -}); -test('fail in WebKit 2', async ({ page }) => { - // ... -}); -``` - -### param: Test.slow#3.condition -* since: v1.10 -- `callback` <[function]\([Fixtures]\):[boolean]> +- `callback` ?<[function]\([Fixtures]\):[boolean]> A function that returns whether to mark as "slow", based on test fixtures. Test or tests are marked as "slow" when the return value is `true`. -### param: Test.slow#3.description +### param: Test.slow.description * since: v1.10 - `description` ?<[string]> Optional description that will be reflected in a test report. + ## async method: Test.step * since: v1.10 - returns: <[any]> @@ -1555,7 +1456,7 @@ Whether to box the step in the report. Defaults to `false`. When the step is box ## 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. +Specifies options or fixtures to use in a single test file or a [`method: Test.describe`] group. Most useful to set an option, for example set `locale` to configure `context` fixture. **Usage** diff --git a/docs/src/test-api/class-testinfo.md b/docs/src/test-api/class-testinfo.md index 3dca7942e4..d766920b06 100644 --- a/docs/src/test-api/class-testinfo.md +++ b/docs/src/test-api/class-testinfo.md @@ -2,7 +2,7 @@ * since: v1.10 * langs: js -`TestInfo` contains information about currently running test. It is available to test functions, [`method: Test.beforeEach#1`], [`method: Test.afterEach#1`], [`method: Test.beforeAll#1`] and [`method: Test.afterAll#1`] hooks, and test-scoped fixtures. `TestInfo` provides utilities to control test execution: attach files, update test timeout, determine which test is currently running and whether it was retried, etc. +`TestInfo` contains information about currently running test. It is available to test functions, [`method: Test.beforeEach`], [`method: Test.afterEach`], [`method: Test.beforeAll`] and [`method: Test.afterAll`] hooks, and test-scoped fixtures. `TestInfo` provides utilities to control test execution: attach files, update test timeout, determine which test is currently running and whether it was retried, etc. ```js import { test, expect } from '@playwright/test'; @@ -20,7 +20,7 @@ test('basic test', async ({ page }, testInfo) => { - `type` <[string]> Annotation type, for example `'skip'` or `'fail'`. - `description` ?<[string]> Optional description. -The list of annotations applicable to the current test. Includes annotations from the test, annotations from all [`method: Test.describe#1`] groups the test belongs to and file-level annotations for the test file. +The list of annotations applicable to the current test. Includes annotations from the test, annotations from all [`method: Test.describe`] groups the test belongs to and file-level annotations for the test file. Learn more about [test annotations](../test-annotations.md). @@ -115,7 +115,7 @@ Processed configuration from the [configuration file](../test-configuration.md). * since: v1.10 - type: <[int]> -The number of milliseconds the test took to finish. Always zero before the test finishes, either successfully or not. Can be used in [`method: Test.afterEach#1`] hook. +The number of milliseconds the test took to finish. Always zero before the test finishes, either successfully or not. Can be used in [`method: Test.afterEach`] hook. ## property: TestInfo.error @@ -137,8 +137,8 @@ Errors thrown during test execution, if any. - type: <[TestStatus]<"passed"|"failed"|"timedOut"|"skipped"|"interrupted">> Expected status for the currently running test. This is usually `'passed'`, except for a few cases: -* `'skipped'` for skipped tests, e.g. with [`method: Test.skip#2`]; -* `'failed'` for tests marked as failed with [`method: Test.fail#1`]. +* `'skipped'` for skipped tests, e.g. with [`method: Test.skip`]; +* `'failed'` for tests marked as failed with [`method: Test.fail`]. Expected status is usually compared with the actual [`property: TestInfo.status`]: @@ -154,12 +154,12 @@ test.afterEach(async ({}, testInfo) => { ## method: TestInfo.fail#1 * since: v1.10 -Marks the currently running 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. This is similar to [`method: Test.fail#1`]. +Marks the currently running 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. This is similar to [`method: Test.fail`]. ## method: TestInfo.fail#2 * since: v1.10 -Conditionally mark the currently running test as "should fail" with an optional description. This is similar to [`method: Test.fail#2`]. +Conditionally mark the currently running test as "should fail" with an optional description. This is similar to [`method: Test.fail`]. ### param: TestInfo.fail#2.condition * since: v1.10 @@ -184,12 +184,12 @@ Absolute path to a file where the currently running test is declared. ## method: TestInfo.fixme#1 * since: v1.10 -Mark a test as "fixme", with the intention to fix it. Test is immediately aborted. This is similar to [`method: Test.fixme#2`]. +Mark a test as "fixme", with the intention to fix it. Test is immediately aborted. This is similar to [`method: Test.fixme`]. ## method: TestInfo.fixme#2 * since: v1.10 -Conditionally mark the currently running test as "fixme" with an optional description. This is similar to [`method: Test.fixme#3`]. +Conditionally mark the currently running test as "fixme" with an optional description. This is similar to [`method: Test.fixme`]. ### param: TestInfo.fixme#2.condition * since: v1.10 @@ -330,12 +330,12 @@ Timeout in milliseconds. ## method: TestInfo.skip#1 * since: v1.10 -Unconditionally skip the currently running test. Test is immediately aborted. This is similar to [`method: Test.skip#2`]. +Unconditionally skip the currently running test. Test is immediately aborted. This is similar to [`method: Test.skip`]. ## method: TestInfo.skip#2 * since: v1.10 -Conditionally skips the currently running test with an optional description. This is similar to [`method: Test.skip#3`]. +Conditionally skips the currently running test with an optional description. This is similar to [`method: Test.skip`]. ### param: TestInfo.skip#2.condition * since: v1.10 @@ -353,12 +353,12 @@ Optional description that will be reflected in a test report. ## method: TestInfo.slow#1 * since: v1.10 -Marks the currently running test as "slow", giving it triple the default timeout. This is similar to [`method: Test.slow#1`]. +Marks the currently running test as "slow", giving it triple the default timeout. This is similar to [`method: Test.slow`]. ## method: TestInfo.slow#2 * since: v1.10 -Conditionally mark the currently running test as "slow" with an optional description, giving it triple the default timeout. This is similar to [`method: Test.slow#2`]. +Conditionally mark the currently running test as "slow" with an optional description, giving it triple the default timeout. This is similar to [`method: Test.slow`]. ### param: TestInfo.slow#2.condition * since: v1.10 @@ -403,7 +403,7 @@ Suffix used to differentiate snapshots between multiple test configurations. For * since: v1.10 - type: ?<[TestStatus]<"passed"|"failed"|"timedOut"|"skipped"|"interrupted">> -Actual status for the currently running test. Available after the test has finished in [`method: Test.afterEach#1`] hook and fixtures. +Actual status for the currently running test. Available after the test has finished in [`method: Test.afterEach`] hook and fixtures. Status is usually compared with the [`property: TestInfo.expectedStatus`]: diff --git a/docs/src/test-reporter-api/class-suite.md b/docs/src/test-reporter-api/class-suite.md index 6c94c9e823..0c0c75691f 100644 --- a/docs/src/test-reporter-api/class-suite.md +++ b/docs/src/test-reporter-api/class-suite.md @@ -9,7 +9,7 @@ * File suite #1 * [TestCase] #1 * [TestCase] #2 - * Suite corresponding to a [`method: Test.describe#1`] group + * Suite corresponding to a [`method: Test.describe`] group * [TestCase] #1 in a group * [TestCase] #2 in a group * < more test cases ... > @@ -54,7 +54,7 @@ Child suites. See [Suite] for the hierarchy of suites. * since: v1.10 - type: <[Array]<[TestCase]>> -Test cases in the suite. Note that only test cases defined directly in this suite are in the list. Any test cases defined in nested [`method: Test.describe#1`] groups are listed +Test cases in the suite. Note that only test cases defined directly in this suite are in the list. Any test cases defined in nested [`method: Test.describe`] groups are listed in the child [`property: Suite.suites`]. ## property: Suite.title @@ -65,7 +65,7 @@ Suite title. * Empty for root suite. * Project name for project suite. * File path for file suite. -* Title passed to [`method: Test.describe#1`] for a group suite. +* Title passed to [`method: Test.describe`] for a group suite. ## method: Suite.titlePath * since: v1.10 diff --git a/docs/src/test-reporter-api/class-testcase.md b/docs/src/test-reporter-api/class-testcase.md index de795d2028..df721ff404 100644 --- a/docs/src/test-reporter-api/class-testcase.md +++ b/docs/src/test-reporter-api/class-testcase.md @@ -10,7 +10,7 @@ - `type` <[string]> Annotation type, for example `'skip'` or `'fail'`. - `description` ?<[string]> Optional description. -The list of annotations applicable to the current test. Includes annotations from the test, annotations from all [`method: Test.describe#1`] groups the test belongs to and file-level annotations for the test file. +The list of annotations applicable to the current test. Includes annotations from the test, annotations from all [`method: Test.describe`] groups the test belongs to and file-level annotations for the test file. Annotations are available during test execution through [`property: TestInfo.annotations`]. @@ -21,8 +21,8 @@ Learn more about [test annotations](../test-annotations.md). - type: <[TestStatus]<"passed"|"failed"|"timedOut"|"skipped"|"interrupted">> Expected test status. -* Tests marked as [`method: Test.skip#1`] or [`method: Test.fixme#1`] are expected to be `'skipped'`. -* Tests marked as [`method: Test.fail#1`] are expected to be `'failed'`. +* Tests marked as [`method: Test.skip`] or [`method: Test.fixme`] are expected to be `'skipped'`. +* Tests marked as [`method: Test.fail`] are expected to be `'failed'`. * Other tests are expected to be `'passed'`. See also [`property: TestResult.status`] for the actual status. @@ -83,7 +83,7 @@ Learn more about [test retries](../test-retries.md#retries). * since: v1.10 - type: <[float]> -The timeout given to the test. Affected by [`property: TestConfig.timeout`], [`property: TestProject.timeout`], [`method: Test.setTimeout`], [`method: Test.slow#1`] and [`method: TestInfo.setTimeout`]. +The timeout given to the test. Affected by [`property: TestConfig.timeout`], [`property: TestProject.timeout`], [`method: Test.setTimeout`], [`method: Test.slow`] and [`method: TestInfo.setTimeout`]. ## property: TestCase.title * since: v1.10 diff --git a/docs/src/test-retries-js.md b/docs/src/test-retries-js.md index 0deca7544c..b53b426880 100644 --- a/docs/src/test-retries-js.md +++ b/docs/src/test-retries-js.md @@ -169,7 +169,7 @@ It is usually better to make your tests isolated, so they can be efficiently run ## Reuse single page between tests -Playwright Test creates an isolated [Page] object for each test. However, if you'd like to reuse a single [Page] object between multiple tests, you can create your own in [`method: Test.beforeAll#1`] and close it in [`method: Test.afterAll#1`]. +Playwright Test creates an isolated [Page] object for each test. However, if you'd like to reuse a single [Page] object between multiple tests, you can create your own in [`method: Test.beforeAll`] and close it in [`method: Test.afterAll`]. ```js tab=js-js title="example.spec.js" // @ts-check diff --git a/docs/src/test-timeouts-js.md b/docs/src/test-timeouts-js.md index 61d148f8fb..02f00f0b26 100644 --- a/docs/src/test-timeouts-js.md +++ b/docs/src/test-timeouts-js.md @@ -54,7 +54,7 @@ test('very slow test', async ({ page }) => { }); ``` -API reference: [`method: Test.setTimeout`] and [`method: Test.slow#1`]. +API reference: [`method: Test.setTimeout`] and [`method: Test.slow`]. ### Change timeout from a `beforeEach` hook diff --git a/packages/playwright/types/test.d.ts b/packages/playwright/types/test.d.ts index a557514fcb..46bc239cb9 100644 --- a/packages/playwright/types/test.d.ts +++ b/packages/playwright/types/test.d.ts @@ -707,8 +707,9 @@ interface TestConfig { /** * Whether to exit with an error if any tests or groups are marked as - * [test.only(title, testFunction)](https://playwright.dev/docs/api/class-test#test-only) or - * [test.describe.only(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-only). Useful on CI. + * [test.only(title, body)](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** * @@ -1463,8 +1464,9 @@ export type Metadata = { [key: string]: any }; export interface FullConfig { /** * Whether to exit with an error if any tests or groups are marked as - * [test.only(title, testFunction)](https://playwright.dev/docs/api/class-test#test-only) or - * [test.describe.only(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-only). Useful on CI. + * [test.only(title, body)](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** * @@ -1916,12 +1918,12 @@ export interface WorkerInfo { /** * `TestInfo` contains information about currently running test. It is available to test functions, - * [test.beforeEach(hookFunction)](https://playwright.dev/docs/api/class-test#test-before-each-1), - * [test.afterEach(hookFunction)](https://playwright.dev/docs/api/class-test#test-after-each-1), - * [test.beforeAll(hookFunction)](https://playwright.dev/docs/api/class-test#test-before-all-1) and - * [test.afterAll(hookFunction)](https://playwright.dev/docs/api/class-test#test-after-all-1) hooks, and test-scoped - * fixtures. `TestInfo` provides utilities to control test execution: attach files, update test timeout, determine - * which test is currently running and whether it was retried, etc. + * [test.beforeEach([title, hookFunction])](https://playwright.dev/docs/api/class-test#test-before-each), + * [test.afterEach([title, hookFunction])](https://playwright.dev/docs/api/class-test#test-after-each), + * [test.beforeAll([title, hookFunction])](https://playwright.dev/docs/api/class-test#test-before-all) and + * [test.afterAll([title, hookFunction])](https://playwright.dev/docs/api/class-test#test-after-all) hooks, and + * test-scoped fixtures. `TestInfo` provides utilities to control test execution: attach files, update test timeout, + * determine which test is currently running and whether it was retried, etc. * * ```js * import { test, expect } from '@playwright/test'; @@ -1998,13 +2000,14 @@ export interface TestInfo { /** * Marks the currently running 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. This is similar to [test.fail()](https://playwright.dev/docs/api/class-test#test-fail-1). + * fixed. This is similar to + * [test.fail([title, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fail). */ fail(): void; /** * Conditionally mark the currently running test as "should fail" with an optional description. This is similar to - * [test.fail(condition[, description])](https://playwright.dev/docs/api/class-test#test-fail-2). + * [test.fail([title, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fail). * @param condition Test is marked as "should fail" when the condition is `true`. * @param description Optional description that will be reflected in a test report. */ @@ -2012,13 +2015,13 @@ export interface TestInfo { /** * Mark a test as "fixme", with the intention to fix it. Test is immediately aborted. This is similar to - * [test.fixme()](https://playwright.dev/docs/api/class-test#test-fixme-2). + * [test.fixme([title, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fixme). */ fixme(): void; /** * Conditionally mark the currently running test as "fixme" with an optional description. This is similar to - * [test.fixme(condition[, description])](https://playwright.dev/docs/api/class-test#test-fixme-3). + * [test.fixme([title, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fixme). * @param condition Test is marked as "fixme" when the condition is `true`. * @param description Optional description that will be reflected in a test report. */ @@ -2070,13 +2073,13 @@ export interface TestInfo { /** * Unconditionally skip the currently running test. Test is immediately aborted. This is similar to - * [test.skip()](https://playwright.dev/docs/api/class-test#test-skip-2). + * [test.skip([title, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-skip). */ skip(): void; /** * Conditionally skips the currently running test with an optional description. This is similar to - * [test.skip(condition[, description])](https://playwright.dev/docs/api/class-test#test-skip-3). + * [test.skip([title, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-skip). * @param condition A skip condition. Test is skipped when the condition is `true`. * @param description Optional description that will be reflected in a test report. */ @@ -2084,14 +2087,14 @@ export interface TestInfo { /** * Marks the currently running test as "slow", giving it triple the default timeout. This is similar to - * [test.slow()](https://playwright.dev/docs/api/class-test#test-slow-1). + * [test.slow([condition, callback, description])](https://playwright.dev/docs/api/class-test#test-slow). */ slow(): void; /** * Conditionally mark the currently running test as "slow" with an optional description, giving it triple the default * timeout. This is similar to - * [test.slow(condition[, description])](https://playwright.dev/docs/api/class-test#test-slow-2). + * [test.slow([condition, callback, description])](https://playwright.dev/docs/api/class-test#test-slow). * @param condition Test is marked as "slow" when the condition is `true`. * @param description Optional description that will be reflected in a test report. */ @@ -2112,7 +2115,7 @@ export interface TestInfo { /** * The list of annotations applicable to the current test. Includes annotations from the test, annotations from all - * [test.describe(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-1) groups the test + * [test.describe([title, callback])](https://playwright.dev/docs/api/class-test#test-describe) groups the test * belongs to and file-level annotations for the test file. * * Learn more about [test annotations](https://playwright.dev/docs/test-annotations). @@ -2166,8 +2169,8 @@ export interface TestInfo { /** * The number of milliseconds the test took to finish. Always zero before the test finishes, either successfully or - * not. Can be used in [test.afterEach(hookFunction)](https://playwright.dev/docs/api/class-test#test-after-each-1) - * hook. + * not. Can be used in + * [test.afterEach([title, hookFunction])](https://playwright.dev/docs/api/class-test#test-after-each) hook. */ duration: number; @@ -2184,9 +2187,10 @@ export interface TestInfo { /** * Expected status for the currently running test. This is usually `'passed'`, except for a few cases: - * - `'skipped'` for skipped tests, e.g. with [test.skip()](https://playwright.dev/docs/api/class-test#test-skip-2); + * - `'skipped'` for skipped tests, e.g. with + * [test.skip([title, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-skip); * - `'failed'` for tests marked as failed with - * [test.fail()](https://playwright.dev/docs/api/class-test#test-fail-1). + * [test.fail([title, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fail). * * Expected status is usually compared with the actual * [testInfo.status](https://playwright.dev/docs/api/class-testinfo#test-info-status): @@ -2290,7 +2294,8 @@ export interface TestInfo { /** * Actual status for the currently running test. Available after the test has finished in - * [test.afterEach(hookFunction)](https://playwright.dev/docs/api/class-test#test-after-each-1) hook and fixtures. + * [test.afterEach([title, hookFunction])](https://playwright.dev/docs/api/class-test#test-after-each) hook and + * fixtures. * * Status is usually compared with the * [testInfo.expectedStatus](https://playwright.dev/docs/api/class-testinfo#test-info-expected-status): @@ -2353,9 +2358,14 @@ export interface TestInfo { interface SuiteFunction { /** * Declares a group of tests. + * - `test.describe(title, callback)` + * - `test.describe(callback)` * * **Usage** * + * You can declare a group of tests with a title. The title will be visible in the test report as a part of each + * test's title. + * * ```js * test.describe('two tests', () => { * test('one', async ({ page }) => { @@ -2368,17 +2378,8 @@ interface SuiteFunction { * }); * ``` * - * @param title Group title. - * @param callback A callback that is run immediately when calling - * [test.describe(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-1). Any tests added in - * this callback will belong to the group. - */ - (title: string, callback: () => void): void; - /** - * 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** + * Without a title, this method 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). * * ```js * test.describe(() => { @@ -2394,9 +2395,55 @@ interface SuiteFunction { * }); * ``` * + * @param title Group title. * @param callback A callback that is run immediately when calling - * [test.describe(callback)](https://playwright.dev/docs/api/class-test#test-describe-2). Any tests added in this - * callback will belong to the group. + * [test.describe([title, callback])](https://playwright.dev/docs/api/class-test#test-describe). Any tests declared in + * this callback will belong to the group. + */ + (title: string, callback: () => void): void; + /** + * Declares a group of tests. + * - `test.describe(title, callback)` + * - `test.describe(callback)` + * + * **Usage** + * + * You can declare a group of tests with a title. The title will be visible in the test report as a part of each + * test's title. + * + * ```js + * test.describe('two tests', () => { + * test('one', async ({ page }) => { + * // ... + * }); + * + * test('two', async ({ page }) => { + * // ... + * }); + * }); + * ``` + * + * Without a title, this method 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). + * + * ```js + * test.describe(() => { + * test.use({ colorScheme: 'dark' }); + * + * test('one', async ({ page }) => { + * // ... + * }); + * + * test('two', async ({ page }) => { + * // ... + * }); + * }); + * ``` + * + * @param title Group title. + * @param callback A callback that is run immediately when calling + * [test.describe([title, callback])](https://playwright.dev/docs/api/class-test#test-describe). Any tests declared in + * this callback will belong to the group. */ (callback: () => void): void; } @@ -2432,14 +2479,19 @@ export interface TestType; /** * Declares a group of tests. + * - `test.describe(title, callback)` + * - `test.describe(callback)` * * **Usage** * + * You can declare a group of tests with a title. The title will be visible in the test report as a part of each + * test's title. + * * ```js * test.describe('two tests', () => { * test('one', async ({ page }) => { @@ -2452,15 +2504,34 @@ export interface TestType { + * test.use({ colorScheme: 'dark' }); + * + * test('one', async ({ page }) => { + * // ... + * }); + * + * test('two', async ({ page }) => { + * // ... + * }); + * }); + * ``` + * * @param title Group title. * @param callback A callback that is run immediately when calling - * [test.describe(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-1). Any tests added in + * [test.describe([title, callback])](https://playwright.dev/docs/api/class-test#test-describe). Any tests declared in * this callback will belong to the group. */ describe: SuiteFunction & { /** * Declares a focused group of tests. If there are some focused tests or suites, all of them will be run but nothing * else. + * - `test.describe.only(title, callback)` + * - `test.describe.only(callback)` * * **Usage** * @@ -2475,16 +2546,26 @@ export interface TestType { + * // ... + * }); + * ``` + * * @param title Group title. * @param callback A callback that is run immediately when calling - * [test.describe.only(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-only). Any tests + * [test.describe.only([title, callback])](https://playwright.dev/docs/api/class-test#test-describe-only). Any tests * added in this callback will belong to the group. */ only: SuiteFunction; /** * Declares a skipped test group, similarly to - * [test.describe(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-1). Tests in the skipped + * [test.describe([title, callback])](https://playwright.dev/docs/api/class-test#test-describe). Tests in the skipped * group are never run. + * - `test.describe.skip(title, callback)` + * - `test.describe.skip(title)` * * **Usage** * @@ -2496,6 +2577,14 @@ export interface TestType { + * // ... + * }); + * ``` + * * @param title Group title. * @param callback A callback that is run immediately when calling * [test.describe.skip(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-skip). Any tests @@ -2504,22 +2593,32 @@ export interface TestType { + * test.describe.fixme('broken tests that should be fixed', () => { * test('example', async ({ page }) => { * // This test will not run * }); * }); * ``` * + * You can also omit the title. + * + * ```js + * test.describe.fixme(() => { + * // ... + * }); + * ``` + * * @param title Group title. * @param callback A callback that is run immediately when calling - * [test.describe.fixme(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-fixme). Any tests + * [test.describe.fixme([title, callback])](https://playwright.dev/docs/api/class-test#test-describe-fixme). Any tests * added in this callback will belong to the group, and will not be run. */ fixme: SuiteFunction; @@ -2532,6 +2631,8 @@ export interface TestType { + * // ... + * }); + * ``` + * * @param title Group title. * @param callback A callback that is run immediately when calling - * [test.describe.serial(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-serial). Any tests - * added in this callback will belong to the group. + * [test.describe.serial([title, callback])](https://playwright.dev/docs/api/class-test#test-describe-serial). Any + * tests added in this callback will belong to the group. */ serial: SuiteFunction & { /** @@ -2558,6 +2667,8 @@ export interface TestType { + * // ... + * }); + * ``` + * * @param title Group title. * @param callback A callback that is run immediately when calling * [test.describe.serial.only(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-serial-only). @@ -2583,8 +2702,10 @@ export interface TestType { + * // ... + * }); + * ``` + * * @param title Group title. * @param callback A callback that is run immediately when calling - * [test.describe.parallel(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-parallel). Any + * [test.describe.parallel([title, callback])](https://playwright.dev/docs/api/class-test#test-describe-parallel). Any * tests added in this callback will belong to the group. */ parallel: SuiteFunction & { @@ -2608,8 +2738,10 @@ export interface TestType { + * // ... + * }); + * ``` + * * @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). + * [test.describe.parallel.only([title, callback])](https://playwright.dev/docs/api/class-test#test-describe-parallel-only). * Any tests added in this callback will belong to the group. */ only: SuiteFunction; @@ -2687,226 +2827,599 @@ export interface TestType void; }; /** - * Declares a skipped test, similarly to - * [test.(call)(title, testFunction)](https://playwright.dev/docs/api/class-test#test-call). Skipped test is never - * run. + * Skip a test. Playwright will not run the test past the `test.skip()` call. + * + * Skipped tests are not supposed to be ever run. If you intent to fix the test, use + * [test.fixme([title, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fixme) + * instead. + * - `test.skip(title, body)` + * - `test.skip()` + * - `test.skip(condition, description)` + * - `test.skip(callback, description)` * * **Usage** * + * You can declare a skipped test, and Playwright will not run it. + * * ```js * import { test, expect } from '@playwright/test'; * - * test.skip('broken test', async ({ page }) => { + * test.skip('never run', async ({ page }) => { * // ... * }); * ``` * - * @param title Test title. - * @param testFunction Test function that takes one or two arguments: an object with fixtures and optional {@link TestInfo}. - */ - skip(title: string, testFunction: (args: TestArgs & WorkerArgs, testInfo: TestInfo) => Promise | void): void; - /** - * Unconditionally skip a test. Test is immediately aborted when you call - * [test.skip()](https://playwright.dev/docs/api/class-test#test-skip-2). - * - * **Usage** + * If your test should be skipped in some configurations, but not all, you can skip the test inside the test body + * based on some condition. We recommend passing a `description` argument in this case. Playwright will run the test, + * but abort it immediately after the `test.skip` call. * * ```js * import { test, expect } from '@playwright/test'; * - * test('skipped test', async ({ page }) => { + * test('Safari-only test', async ({ page, browserName }) => { + * test.skip(browserName !== 'webkit', 'This feature is Safari-only'); + * // ... + * }); + * ``` + * + * You can skip all tests in a file or + * [test.describe([title, callback])](https://playwright.dev/docs/api/class-test#test-describe) group based on some + * condition with a single `test.skip(callback, description)` call. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test.skip(({ browserName }) => browserName !== 'webkit', 'Safari-only'); + * + * test('Safari-only test 1', async ({ page }) => { + * // ... + * }); + * test('Safari-only test 2', async ({ page }) => { + * // ... + * }); + * ``` + * + * You can also call `test.skip()` without arguments inside the test body to always mark the test as failed. We + * recommend using `test.skip(title, body)` instead. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test('less readable', async ({ page }) => { * test.skip(); * // ... * }); * ``` * - * Unconditionally skip all tests in a file or - * [test.describe(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-1) group: - * - * ```js - * import { test, expect } from '@playwright/test'; - * - * test.skip(); - * - * test('skipped test 1', async ({ page }) => { - * // ... - * }); - * test('skipped test 2', async ({ page }) => { - * // ... - * }); - * ``` - * - */ - skip(): void; - /** - * Conditionally skip a test with an optional description. - * - * **Usage** - * - * ```js - * import { test, expect } from '@playwright/test'; - * - * test('skip in WebKit', async ({ page, browserName }) => { - * test.skip(browserName === 'webkit', 'This feature is not implemented for Mac'); - * // ... - * }); - * ``` - * - * Skip from [test.beforeEach(hookFunction)](https://playwright.dev/docs/api/class-test#test-before-each-1) hook: - * - * ```js - * import { test, expect } from '@playwright/test'; - * - * test.beforeEach(async ({ page }) => { - * test.skip(process.env.APP_VERSION === 'v1', 'There are no settings in v1'); - * await page.goto('/settings'); - * }); - * ``` - * - * @param condition A skip condition. Test is skipped when the condition is `true`. + * @param title Test title. + * @param body Test body that takes one or two arguments: an object with fixtures and optional {@link TestInfo}. + * @param condition Test is marked as "should fail" when the condition is `true`. + * @param callback A function that returns whether to mark as "should fail", based on test fixtures. Test or tests are marked as + * "should fail" when the return value is `true`. * @param description Optional description that will be reflected in a test report. */ - skip(condition: boolean, description?: string): void; + skip(title: string, testFunction: (args: TestArgs & WorkerArgs, testInfo: TestInfo) => Promise | void): void; /** - * Conditionally skips all tests in a file or - * [test.describe(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-1) group. + * Skip a test. Playwright will not run the test past the `test.skip()` call. + * + * Skipped tests are not supposed to be ever run. If you intent to fix the test, use + * [test.fixme([title, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fixme) + * instead. + * - `test.skip(title, body)` + * - `test.skip()` + * - `test.skip(condition, description)` + * - `test.skip(callback, description)` * * **Usage** * + * You can declare a skipped test, and Playwright will not run it. + * * ```js * import { test, expect } from '@playwright/test'; * - * test.skip(({ browserName }) => browserName === 'webkit'); - * - * test('skip in WebKit 1', async ({ page }) => { - * // ... - * }); - * test('skip in WebKit 2', async ({ page }) => { + * test.skip('never run', async ({ page }) => { * // ... * }); * ``` * - * @param callback A function that returns whether to skip, based on test fixtures. Test or tests are skipped when the return value is - * `true`. - * @param description Optional description that will be reflected in a test report. - */ - skip(callback: (args: TestArgs & WorkerArgs) => boolean, description?: string): void; - /** - * Declares a test to be fixed, similarly to - * [test.(call)(title, testFunction)](https://playwright.dev/docs/api/class-test#test-call). This test will not be - * run. - * - * **Usage** + * If your test should be skipped in some configurations, but not all, you can skip the test inside the test body + * based on some condition. We recommend passing a `description` argument in this case. Playwright will run the test, + * but abort it immediately after the `test.skip` call. * * ```js * import { test, expect } from '@playwright/test'; * - * test.fixme('test to be fixed', async ({ page }) => { + * test('Safari-only test', async ({ page, browserName }) => { + * test.skip(browserName !== 'webkit', 'This feature is Safari-only'); + * // ... + * }); + * ``` + * + * You can skip all tests in a file or + * [test.describe([title, callback])](https://playwright.dev/docs/api/class-test#test-describe) group based on some + * condition with a single `test.skip(callback, description)` call. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test.skip(({ browserName }) => browserName !== 'webkit', 'Safari-only'); + * + * test('Safari-only test 1', async ({ page }) => { + * // ... + * }); + * test('Safari-only test 2', async ({ page }) => { + * // ... + * }); + * ``` + * + * You can also call `test.skip()` without arguments inside the test body to always mark the test as failed. We + * recommend using `test.skip(title, body)` instead. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test('less readable', async ({ page }) => { + * test.skip(); * // ... * }); * ``` * * @param title Test title. - * @param testFunction Test function that takes one or two arguments: an object with fixtures and optional {@link TestInfo}. + * @param body Test body that takes one or two arguments: an object with fixtures and optional {@link TestInfo}. + * @param condition Test is marked as "should fail" when the condition is `true`. + * @param callback A function that returns whether to mark as "should fail", based on test fixtures. Test or tests are marked as + * "should fail" when the return value is `true`. + * @param description Optional description that will be reflected in a test report. */ - fixme(title: string, testFunction: (args: TestArgs & WorkerArgs, testInfo: TestInfo) => Promise | void): void; + skip(): void; /** - * Mark a test as "fixme", with the intention to fix it. Test is immediately aborted when you call - * [test.fixme()](https://playwright.dev/docs/api/class-test#test-fixme-2). + * Skip a test. Playwright will not run the test past the `test.skip()` call. + * + * Skipped tests are not supposed to be ever run. If you intent to fix the test, use + * [test.fixme([title, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fixme) + * instead. + * - `test.skip(title, body)` + * - `test.skip()` + * - `test.skip(condition, description)` + * - `test.skip(callback, description)` * * **Usage** * + * You can declare a skipped test, and Playwright will not run it. + * * ```js * import { test, expect } from '@playwright/test'; * - * test('test to be fixed', async ({ page }) => { + * test.skip('never run', async ({ page }) => { + * // ... + * }); + * ``` + * + * If your test should be skipped in some configurations, but not all, you can skip the test inside the test body + * based on some condition. We recommend passing a `description` argument in this case. Playwright will run the test, + * but abort it immediately after the `test.skip` call. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test('Safari-only test', async ({ page, browserName }) => { + * test.skip(browserName !== 'webkit', 'This feature is Safari-only'); + * // ... + * }); + * ``` + * + * You can skip all tests in a file or + * [test.describe([title, callback])](https://playwright.dev/docs/api/class-test#test-describe) group based on some + * condition with a single `test.skip(callback, description)` call. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test.skip(({ browserName }) => browserName !== 'webkit', 'Safari-only'); + * + * test('Safari-only test 1', async ({ page }) => { + * // ... + * }); + * test('Safari-only test 2', async ({ page }) => { + * // ... + * }); + * ``` + * + * You can also call `test.skip()` without arguments inside the test body to always mark the test as failed. We + * recommend using `test.skip(title, body)` instead. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test('less readable', async ({ page }) => { + * test.skip(); + * // ... + * }); + * ``` + * + * @param title Test title. + * @param body Test body that takes one or two arguments: an object with fixtures and optional {@link TestInfo}. + * @param condition Test is marked as "should fail" when the condition is `true`. + * @param callback A function that returns whether to mark as "should fail", based on test fixtures. Test or tests are marked as + * "should fail" when the return value is `true`. + * @param description Optional description that will be reflected in a test report. + */ + skip(condition: boolean, description?: string): void; + /** + * Skip a test. Playwright will not run the test past the `test.skip()` call. + * + * Skipped tests are not supposed to be ever run. If you intent to fix the test, use + * [test.fixme([title, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fixme) + * instead. + * - `test.skip(title, body)` + * - `test.skip()` + * - `test.skip(condition, description)` + * - `test.skip(callback, description)` + * + * **Usage** + * + * You can declare a skipped test, and Playwright will not run it. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test.skip('never run', async ({ page }) => { + * // ... + * }); + * ``` + * + * If your test should be skipped in some configurations, but not all, you can skip the test inside the test body + * based on some condition. We recommend passing a `description` argument in this case. Playwright will run the test, + * but abort it immediately after the `test.skip` call. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test('Safari-only test', async ({ page, browserName }) => { + * test.skip(browserName !== 'webkit', 'This feature is Safari-only'); + * // ... + * }); + * ``` + * + * You can skip all tests in a file or + * [test.describe([title, callback])](https://playwright.dev/docs/api/class-test#test-describe) group based on some + * condition with a single `test.skip(callback, description)` call. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test.skip(({ browserName }) => browserName !== 'webkit', 'Safari-only'); + * + * test('Safari-only test 1', async ({ page }) => { + * // ... + * }); + * test('Safari-only test 2', async ({ page }) => { + * // ... + * }); + * ``` + * + * You can also call `test.skip()` without arguments inside the test body to always mark the test as failed. We + * recommend using `test.skip(title, body)` instead. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test('less readable', async ({ page }) => { + * test.skip(); + * // ... + * }); + * ``` + * + * @param title Test title. + * @param body Test body that takes one or two arguments: an object with fixtures and optional {@link TestInfo}. + * @param condition Test is marked as "should fail" when the condition is `true`. + * @param callback A function that returns whether to mark as "should fail", based on test fixtures. Test or tests are marked as + * "should fail" when the return value is `true`. + * @param description Optional description that will be reflected in a test report. + */ + skip(callback: (args: TestArgs & WorkerArgs) => boolean, description?: string): void; + /** + * Mark a test as "fixme", with the intention to fix it. Playwright will not run the test past the `test.fixme()` + * call. + * - `test.fixme(title, body)` + * - `test.fixme()` + * - `test.fixme(condition, description)` + * - `test.fixme(callback, description)` + * + * **Usage** + * + * You can declare a test as to be fixed, and Playwright will not run it. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test.fixme('to be fixed', async ({ page }) => { + * // ... + * }); + * ``` + * + * If your test should be fixed in some configurations, but not all, you can mark the test as "fixme" inside the test + * body based on some condition. We recommend passing a `description` argument in this case. Playwright will run the + * test, but abort it immediately after the `test.fixme` call. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test('to be fixed in Safari', async ({ page, browserName }) => { + * test.fixme(browserName === 'webkit', 'This feature breaks in Safari for some reason'); + * // ... + * }); + * ``` + * + * You can mark all tests in a file or + * [test.describe([title, callback])](https://playwright.dev/docs/api/class-test#test-describe) group as "fixme" based + * on some condition with a single `test.fixme(callback, description)` call. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test.fixme(({ browserName }) => browserName === 'webkit', 'Should figure out the issue'); + * + * test('to be fixed in Safari 1', async ({ page }) => { + * // ... + * }); + * test('to be fixed in Safari 2', async ({ page }) => { + * // ... + * }); + * ``` + * + * You can also call `test.fixme()` without arguments inside the test body to always mark the test as failed. We + * recommend using `test.fixme(title, body)` instead. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test('less readable', async ({ page }) => { * test.fixme(); * // ... * }); * ``` * - * Mark all tests in a file or - * [test.describe(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-1) group as "fixme". - * - * ```js - * import { test, expect } from '@playwright/test'; - * - * test.fixme(); - * - * test('test to be fixed 1', async ({ page }) => { - * // ... - * }); - * test('test to be fixed 2', async ({ page }) => { - * // ... - * }); - * ``` - * + * @param title Test title. + * @param body Test body that takes one or two arguments: an object with fixtures and optional {@link TestInfo}. + * @param condition Test is marked as "should fail" when the condition is `true`. + * @param callback A function that returns whether to mark as "should fail", based on test fixtures. Test or tests are marked as + * "should fail" when the return value is `true`. + * @param description Optional description that will be reflected in a test report. */ - fixme(): void; + fixme(title: string, testFunction: (args: TestArgs & WorkerArgs, testInfo: TestInfo) => Promise | void): void; /** - * Conditionally mark a test as "fixme" with an optional description. + * Mark a test as "fixme", with the intention to fix it. Playwright will not run the test past the `test.fixme()` + * call. + * - `test.fixme(title, body)` + * - `test.fixme()` + * - `test.fixme(condition, description)` + * - `test.fixme(callback, description)` * * **Usage** * + * You can declare a test as to be fixed, and Playwright will not run it. + * * ```js * import { test, expect } from '@playwright/test'; * - * test('broken in WebKit', async ({ page, browserName }) => { - * test.fixme(browserName === 'webkit', 'This feature is not implemented on Mac yet'); + * test.fixme('to be fixed', async ({ page }) => { * // ... * }); * ``` * - * @param condition Test is marked as "fixme" when the condition is `true`. + * If your test should be fixed in some configurations, but not all, you can mark the test as "fixme" inside the test + * body based on some condition. We recommend passing a `description` argument in this case. Playwright will run the + * test, but abort it immediately after the `test.fixme` call. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test('to be fixed in Safari', async ({ page, browserName }) => { + * test.fixme(browserName === 'webkit', 'This feature breaks in Safari for some reason'); + * // ... + * }); + * ``` + * + * You can mark all tests in a file or + * [test.describe([title, callback])](https://playwright.dev/docs/api/class-test#test-describe) group as "fixme" based + * on some condition with a single `test.fixme(callback, description)` call. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test.fixme(({ browserName }) => browserName === 'webkit', 'Should figure out the issue'); + * + * test('to be fixed in Safari 1', async ({ page }) => { + * // ... + * }); + * test('to be fixed in Safari 2', async ({ page }) => { + * // ... + * }); + * ``` + * + * You can also call `test.fixme()` without arguments inside the test body to always mark the test as failed. We + * recommend using `test.fixme(title, body)` instead. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test('less readable', async ({ page }) => { + * test.fixme(); + * // ... + * }); + * ``` + * + * @param title Test title. + * @param body Test body that takes one or two arguments: an object with fixtures and optional {@link TestInfo}. + * @param condition Test is marked as "should fail" when the condition is `true`. + * @param callback A function that returns whether to mark as "should fail", based on test fixtures. Test or tests are marked as + * "should fail" when the return value is `true`. + * @param description Optional description that will be reflected in a test report. + */ + fixme(): void; + /** + * Mark a test as "fixme", with the intention to fix it. Playwright will not run the test past the `test.fixme()` + * call. + * - `test.fixme(title, body)` + * - `test.fixme()` + * - `test.fixme(condition, description)` + * - `test.fixme(callback, description)` + * + * **Usage** + * + * You can declare a test as to be fixed, and Playwright will not run it. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test.fixme('to be fixed', async ({ page }) => { + * // ... + * }); + * ``` + * + * If your test should be fixed in some configurations, but not all, you can mark the test as "fixme" inside the test + * body based on some condition. We recommend passing a `description` argument in this case. Playwright will run the + * test, but abort it immediately after the `test.fixme` call. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test('to be fixed in Safari', async ({ page, browserName }) => { + * test.fixme(browserName === 'webkit', 'This feature breaks in Safari for some reason'); + * // ... + * }); + * ``` + * + * You can mark all tests in a file or + * [test.describe([title, callback])](https://playwright.dev/docs/api/class-test#test-describe) group as "fixme" based + * on some condition with a single `test.fixme(callback, description)` call. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test.fixme(({ browserName }) => browserName === 'webkit', 'Should figure out the issue'); + * + * test('to be fixed in Safari 1', async ({ page }) => { + * // ... + * }); + * test('to be fixed in Safari 2', async ({ page }) => { + * // ... + * }); + * ``` + * + * You can also call `test.fixme()` without arguments inside the test body to always mark the test as failed. We + * recommend using `test.fixme(title, body)` instead. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test('less readable', async ({ page }) => { + * test.fixme(); + * // ... + * }); + * ``` + * + * @param title Test title. + * @param body Test body that takes one or two arguments: an object with fixtures and optional {@link TestInfo}. + * @param condition Test is marked as "should fail" when the condition is `true`. + * @param callback A function that returns whether to mark as "should fail", based on test fixtures. Test or tests are marked as + * "should fail" when the return value is `true`. * @param description Optional description that will be reflected in a test report. */ fixme(condition: boolean, description?: string): void; /** - * Conditionally mark all tests in a file or - * [test.describe(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-1) group as "fixme". + * Mark a test as "fixme", with the intention to fix it. Playwright will not run the test past the `test.fixme()` + * call. + * - `test.fixme(title, body)` + * - `test.fixme()` + * - `test.fixme(condition, description)` + * - `test.fixme(callback, description)` * * **Usage** * + * You can declare a test as to be fixed, and Playwright will not run it. + * * ```js * import { test, expect } from '@playwright/test'; * - * test.fixme(({ browserName }) => browserName === 'webkit'); - * - * test('broken in WebKit 1', async ({ page }) => { - * // ... - * }); - * test('broken in WebKit 2', async ({ page }) => { + * test.fixme('to be fixed', async ({ page }) => { * // ... * }); * ``` * - * @param callback A function that returns whether to mark as "fixme", based on test fixtures. Test or tests are marked as "fixme" - * when the return value is `true`. + * If your test should be fixed in some configurations, but not all, you can mark the test as "fixme" inside the test + * body based on some condition. We recommend passing a `description` argument in this case. Playwright will run the + * test, but abort it immediately after the `test.fixme` call. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test('to be fixed in Safari', async ({ page, browserName }) => { + * test.fixme(browserName === 'webkit', 'This feature breaks in Safari for some reason'); + * // ... + * }); + * ``` + * + * You can mark all tests in a file or + * [test.describe([title, callback])](https://playwright.dev/docs/api/class-test#test-describe) group as "fixme" based + * on some condition with a single `test.fixme(callback, description)` call. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test.fixme(({ browserName }) => browserName === 'webkit', 'Should figure out the issue'); + * + * test('to be fixed in Safari 1', async ({ page }) => { + * // ... + * }); + * test('to be fixed in Safari 2', async ({ page }) => { + * // ... + * }); + * ``` + * + * You can also call `test.fixme()` without arguments inside the test body to always mark the test as failed. We + * recommend using `test.fixme(title, body)` instead. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test('less readable', async ({ page }) => { + * test.fixme(); + * // ... + * }); + * ``` + * + * @param title Test title. + * @param body Test body that takes one or two arguments: an object with fixtures and optional {@link TestInfo}. + * @param condition Test is marked as "should fail" when the condition is `true`. + * @param callback A function that returns whether to mark as "should fail", based on test fixtures. Test or tests are marked as + * "should fail" when the return value is `true`. * @param description Optional description that will be reflected in a test report. */ fixme(callback: (args: TestArgs & WorkerArgs) => boolean, description?: string): void; /** - * Unconditionally 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. + * Marks a test as "should fail". Playwright 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. + * - `test.fail(title, body)` + * - `test.fail()` + * - `test.fail(condition, description)` + * - `test.fail(callback, description)` * * **Usage** * + * You can declare a test as failing, so that Playwright ensures it actually fails. + * * ```js * import { test, expect } from '@playwright/test'; * - * test('not yet ready', async ({ page }) => { - * test.fail(); + * test.fail('not yet ready', async ({ page }) => { * // ... * }); * ``` * - */ - fail(): void; - /** - * Conditionally mark a test as "should fail" with an optional description. - * - * **Usage** + * If your test fails in some configurations, but not all, you can mark the test as failing inside the test body based + * on some condition. We recommend passing a `description` argument in this case. * * ```js * import { test, expect } from '@playwright/test'; @@ -2917,21 +3430,14 @@ export interface TestType browserName === 'webkit'); + * test.fail(({ browserName }) => browserName === 'webkit', 'not implemented yet'); * * test('fail in WebKit 1', async ({ page }) => { * // ... @@ -2941,17 +3447,38 @@ export interface TestType { + * test.fail(); + * // ... + * }); + * ``` + * + * @param title Test title. + * @param body Test body that takes one or two arguments: an object with fixtures and optional {@link TestInfo}. + * @param condition Test is marked as "should fail" when the condition is `true`. * @param callback A function that returns whether to mark as "should fail", based on test fixtures. Test or tests are marked as * "should fail" when the return value is `true`. * @param description Optional description that will be reflected in a test report. */ - fail(callback: (args: TestArgs & WorkerArgs) => boolean, description?: string): void; + fail(title: string, testFunction: (args: TestArgs & WorkerArgs, testInfo: TestInfo) => Promise | void): void; /** - * Declares a test that "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. + * Marks a test as "should fail". Playwright 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. + * - `test.fail(title, body)` + * - `test.fail()` + * - `test.fail(condition, description)` + * - `test.fail(callback, description)` * * **Usage** * + * You can declare a test as failing, so that Playwright ensures it actually fails. + * * ```js * import { test, expect } from '@playwright/test'; * @@ -2960,20 +3487,207 @@ export interface TestType { + * test.fail(browserName === 'webkit', 'This feature is not implemented for Mac yet'); + * // ... + * }); + * ``` + * + * You can mark all tests in a file or + * [test.describe([title, callback])](https://playwright.dev/docs/api/class-test#test-describe) group as "should fail" + * based on some condition with a single `test.fail(callback, description)` call. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test.fail(({ browserName }) => browserName === 'webkit', 'not implemented yet'); + * + * test('fail in WebKit 1', async ({ page }) => { + * // ... + * }); + * test('fail in WebKit 2', async ({ page }) => { + * // ... + * }); + * ``` + * + * You can also call `test.fail()` without arguments inside the test body to always mark the test as failed. We + * recommend declaring a failing test with `test.fail(title, body)` instead. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test('less readable', async ({ page }) => { + * test.fail(); + * // ... + * }); + * ``` + * * @param title Test title. - * @param testFunction Test function that takes one or two arguments: an object with fixtures and optional {@link TestInfo}. + * @param body Test body that takes one or two arguments: an object with fixtures and optional {@link TestInfo}. + * @param condition Test is marked as "should fail" when the condition is `true`. + * @param callback A function that returns whether to mark as "should fail", based on test fixtures. Test or tests are marked as + * "should fail" when the return value is `true`. + * @param description Optional description that will be reflected in a test report. */ - fail(title: string, testFunction: (args: TestArgs & WorkerArgs, testInfo: TestInfo) => Promise | void): void; + fail(condition: boolean, description?: string): void; /** - * Unconditionally marks a test as "slow". Slow test will be given triple the default timeout. - * - * **Details** - * - * [test.slow()](https://playwright.dev/docs/api/class-test#test-slow-1) cannot be used in a `beforeAll` or `afterAll` - * hook. Use [test.setTimeout(timeout)](https://playwright.dev/docs/api/class-test#test-set-timeout) instead. + * Marks a test as "should fail". Playwright 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. + * - `test.fail(title, body)` + * - `test.fail()` + * - `test.fail(condition, description)` + * - `test.fail(callback, description)` * * **Usage** * + * You can declare a test as failing, so that Playwright ensures it actually fails. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test.fail('not yet ready', async ({ page }) => { + * // ... + * }); + * ``` + * + * If your test fails in some configurations, but not all, you can mark the test as failing inside the test body based + * on some condition. We recommend passing a `description` argument in this case. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test('fail in WebKit', async ({ page, browserName }) => { + * test.fail(browserName === 'webkit', 'This feature is not implemented for Mac yet'); + * // ... + * }); + * ``` + * + * You can mark all tests in a file or + * [test.describe([title, callback])](https://playwright.dev/docs/api/class-test#test-describe) group as "should fail" + * based on some condition with a single `test.fail(callback, description)` call. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test.fail(({ browserName }) => browserName === 'webkit', 'not implemented yet'); + * + * test('fail in WebKit 1', async ({ page }) => { + * // ... + * }); + * test('fail in WebKit 2', async ({ page }) => { + * // ... + * }); + * ``` + * + * You can also call `test.fail()` without arguments inside the test body to always mark the test as failed. We + * recommend declaring a failing test with `test.fail(title, body)` instead. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test('less readable', async ({ page }) => { + * test.fail(); + * // ... + * }); + * ``` + * + * @param title Test title. + * @param body Test body that takes one or two arguments: an object with fixtures and optional {@link TestInfo}. + * @param condition Test is marked as "should fail" when the condition is `true`. + * @param callback A function that returns whether to mark as "should fail", based on test fixtures. Test or tests are marked as + * "should fail" when the return value is `true`. + * @param description Optional description that will be reflected in a test report. + */ + fail(callback: (args: TestArgs & WorkerArgs) => boolean, description?: string): void; + /** + * Marks a test as "should fail". Playwright 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. + * - `test.fail(title, body)` + * - `test.fail()` + * - `test.fail(condition, description)` + * - `test.fail(callback, description)` + * + * **Usage** + * + * You can declare a test as failing, so that Playwright ensures it actually fails. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test.fail('not yet ready', async ({ page }) => { + * // ... + * }); + * ``` + * + * If your test fails in some configurations, but not all, you can mark the test as failing inside the test body based + * on some condition. We recommend passing a `description` argument in this case. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test('fail in WebKit', async ({ page, browserName }) => { + * test.fail(browserName === 'webkit', 'This feature is not implemented for Mac yet'); + * // ... + * }); + * ``` + * + * You can mark all tests in a file or + * [test.describe([title, callback])](https://playwright.dev/docs/api/class-test#test-describe) group as "should fail" + * based on some condition with a single `test.fail(callback, description)` call. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test.fail(({ browserName }) => browserName === 'webkit', 'not implemented yet'); + * + * test('fail in WebKit 1', async ({ page }) => { + * // ... + * }); + * test('fail in WebKit 2', async ({ page }) => { + * // ... + * }); + * ``` + * + * You can also call `test.fail()` without arguments inside the test body to always mark the test as failed. We + * recommend declaring a failing test with `test.fail(title, body)` instead. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test('less readable', async ({ page }) => { + * test.fail(); + * // ... + * }); + * ``` + * + * @param title Test title. + * @param body Test body that takes one or two arguments: an object with fixtures and optional {@link TestInfo}. + * @param condition Test is marked as "should fail" when the condition is `true`. + * @param callback A function that returns whether to mark as "should fail", based on test fixtures. Test or tests are marked as + * "should fail" when the return value is `true`. + * @param description Optional description that will be reflected in a test report. + */ + fail(): void; + /** + * Marks a test as "slow". Slow test will be given triple the default timeout. + * + * Note that [test.slow([condition, callback, description])](https://playwright.dev/docs/api/class-test#test-slow) + * cannot be used in a `beforeAll` or `afterAll` hook. Use + * [test.setTimeout(timeout)](https://playwright.dev/docs/api/class-test#test-set-timeout) instead. + * - `test.slow()` + * - `test.slow(condition, description)` + * - `test.slow(callback, description)` + * + * **Usage** + * + * You can mark a test as slow by calling `test.slow()` inside the test body. + * * ```js * import { test, expect } from '@playwright/test'; * @@ -2983,47 +3697,152 @@ export interface TestType { - * test.slow(browserName === 'webkit', 'This feature is slow on Mac'); + * test('slow in Safari', async ({ page, browserName }) => { + * test.slow(browserName === 'webkit', 'This feature is slow in Safari'); + * // ... + * }); + * ``` + * + * You can mark all tests in a file or + * [test.describe([title, callback])](https://playwright.dev/docs/api/class-test#test-describe) group as "slow" based + * on some condition by passing a callback. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test.slow(({ browserName }) => browserName === 'webkit', 'all tests are slow in Safari'); + * + * test('slow in Safari 1', async ({ page }) => { + * // ... + * }); + * test('fail in Safari 2', async ({ page }) => { * // ... * }); * ``` * * @param condition Test is marked as "slow" when the condition is `true`. + * @param callback A function that returns whether to mark as "slow", based on test fixtures. Test or tests are marked as "slow" when + * the return value is `true`. * @param description Optional description that will be reflected in a test report. */ - slow(condition: boolean, description?: string): void; + slow(): void; /** - * Conditionally mark all tests in a file or - * [test.describe(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-1) group as "slow". Slow - * tests will be given triple the default timeout. + * Marks a test as "slow". Slow test will be given triple the default timeout. + * + * Note that [test.slow([condition, callback, description])](https://playwright.dev/docs/api/class-test#test-slow) + * cannot be used in a `beforeAll` or `afterAll` hook. Use + * [test.setTimeout(timeout)](https://playwright.dev/docs/api/class-test#test-set-timeout) instead. + * - `test.slow()` + * - `test.slow(condition, description)` + * - `test.slow(callback, description)` * * **Usage** * + * You can mark a test as slow by calling `test.slow()` inside the test body. + * * ```js * import { test, expect } from '@playwright/test'; * - * test.slow(({ browserName }) => browserName === 'webkit'); - * - * test('slow in WebKit 1', async ({ page }) => { - * // ... - * }); - * test('fail in WebKit 2', async ({ page }) => { + * test('slow test', async ({ page }) => { + * test.slow(); * // ... * }); * ``` * + * If your test is slow in some configurations, but not all, you can mark it as slow based on a condition. We + * recommend passing a `description` argument in this case. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test('slow in Safari', async ({ page, browserName }) => { + * test.slow(browserName === 'webkit', 'This feature is slow in Safari'); + * // ... + * }); + * ``` + * + * You can mark all tests in a file or + * [test.describe([title, callback])](https://playwright.dev/docs/api/class-test#test-describe) group as "slow" based + * on some condition by passing a callback. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test.slow(({ browserName }) => browserName === 'webkit', 'all tests are slow in Safari'); + * + * test('slow in Safari 1', async ({ page }) => { + * // ... + * }); + * test('fail in Safari 2', async ({ page }) => { + * // ... + * }); + * ``` + * + * @param condition Test is marked as "slow" when the condition is `true`. + * @param callback A function that returns whether to mark as "slow", based on test fixtures. Test or tests are marked as "slow" when + * the return value is `true`. + * @param description Optional description that will be reflected in a test report. + */ + slow(condition: boolean, description?: string): void; + /** + * Marks a test as "slow". Slow test will be given triple the default timeout. + * + * Note that [test.slow([condition, callback, description])](https://playwright.dev/docs/api/class-test#test-slow) + * cannot be used in a `beforeAll` or `afterAll` hook. Use + * [test.setTimeout(timeout)](https://playwright.dev/docs/api/class-test#test-set-timeout) instead. + * - `test.slow()` + * - `test.slow(condition, description)` + * - `test.slow(callback, description)` + * + * **Usage** + * + * You can mark a test as slow by calling `test.slow()` inside the test body. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test('slow test', async ({ page }) => { + * test.slow(); + * // ... + * }); + * ``` + * + * If your test is slow in some configurations, but not all, you can mark it as slow based on a condition. We + * recommend passing a `description` argument in this case. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test('slow in Safari', async ({ page, browserName }) => { + * test.slow(browserName === 'webkit', 'This feature is slow in Safari'); + * // ... + * }); + * ``` + * + * You can mark all tests in a file or + * [test.describe([title, callback])](https://playwright.dev/docs/api/class-test#test-describe) group as "slow" based + * on some condition by passing a callback. + * + * ```js + * import { test, expect } from '@playwright/test'; + * + * test.slow(({ browserName }) => browserName === 'webkit', 'all tests are slow in Safari'); + * + * test('slow in Safari 1', async ({ page }) => { + * // ... + * }); + * test('fail in Safari 2', async ({ page }) => { + * // ... + * }); + * ``` + * + * @param condition Test is marked as "slow" when the condition is `true`. * @param callback A function that returns whether to mark as "slow", based on test fixtures. Test or tests are marked as "slow" when * the return value is `true`. * @param description Optional description that will be reflected in a test report. @@ -3066,7 +3885,7 @@ export interface TestType { @@ -3085,20 +3904,23 @@ export interface TestType { - * console.log(`Running ${testInfo.title}`); + * test.beforeEach(async ({ page }) => { + * console.log(`Running ${test.info().title}`); * await page.goto('https://my.start.url/'); * }); * @@ -3116,15 +3938,40 @@ export interface TestType { + * console.log(`Running ${test.info().title}`); + * await page.goto('https://my.start.url/'); + * }); + * ``` + * + * @param title Hook title. * @param hookFunction Hook function that takes one or two arguments: an object with fixtures and optional {@link TestInfo}. */ beforeEach(inner: (args: TestArgs & WorkerArgs, testInfo: TestInfo) => Promise | any): void; /** - * Declares a `beforeEach` hook with a title that is executed before each test. + * 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 + * [test.describe([title, callback])](https://playwright.dev/docs/api/class-test#test-describe) group, runs before + * each test in the group. + * + * You can access all the same {@link Fixtures} as the test body itself, and also the {@link TestInfo} object that + * gives a lot of useful information. For example, you can navigate the page before starting the test. + * + * You can use [test.afterEach([title, hookFunction])](https://playwright.dev/docs/api/class-test#test-after-each) to + * teardown any resources set up in `beforeEach`. + * - `test.beforeEach(hookFunction)` + * - `test.beforeEach(title, hookFunction)` * * **Details** * - * See [test.beforeEach(hookFunction)](https://playwright.dev/docs/api/class-test#test-before-each-1). + * When multiple `beforeEach` hooks are added, they will run in the order of their registration. + * + * Playwright will continue running all applicable hooks even if some of them have failed. * * **Usage** * @@ -3132,8 +3979,8 @@ export interface TestType { - * console.log(`Running ${testInfo.title}`); + * test.beforeEach(async ({ page }) => { + * console.log(`Running ${test.info().title}`); * await page.goto('https://my.start.url/'); * }); * @@ -3142,6 +3989,16 @@ export interface TestType { + * console.log(`Running ${test.info().title}`); + * await page.goto('https://my.start.url/'); + * }); + * ``` + * * @param title Hook title. * @param hookFunction Hook function that takes one or two arguments: an object with fixtures and optional {@link TestInfo}. */ @@ -3149,14 +4006,18 @@ export interface TestType { - * console.log(`Finished ${testInfo.title} with status ${testInfo.status}`); + * test.afterEach(async ({ page }) => { + * console.log(`Finished ${test.info().title} with status ${test.info().status}`); * - * if (testInfo.status !== testInfo.expectedStatus) + * if (test.info().status !== test.info().expectedStatus) * console.log(`Did not run as expected, ended up at ${page.url()}`); * }); * @@ -3178,15 +4039,37 @@ export interface TestType { + * if (test.info().status !== test.info().expectedStatus) + * console.log(`Did not run as expected, ended up at ${page.url()}`); + * }); + * ``` + * + * @param title Hook title. * @param hookFunction Hook function that takes one or two arguments: an object with fixtures and optional {@link TestInfo}. */ afterEach(inner: (args: TestArgs & WorkerArgs, testInfo: TestInfo) => Promise | any): void; /** - * Declares an `afterEach` hook with a title that is executed after each test. + * 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 + * [test.describe([title, callback])](https://playwright.dev/docs/api/class-test#test-describe) group, runs after each + * test in the group. + * + * You can access all the same {@link Fixtures} as the test body itself, and also the {@link TestInfo} object that + * gives a lot of useful information. For example, you can check whether the test succeeded or failed. + * - `test.afterEach(hookFunction)` + * - `test.afterEach(title, hookFunction)` * * **Details** * - * See [test.afterEach(hookFunction)](https://playwright.dev/docs/api/class-test#test-after-each-1). + * When multiple `afterEach` hooks are added, they will run in the order of their registration. + * + * Playwright will continue running all applicable hooks even if some of them have failed. * * **Usage** * @@ -3194,10 +4077,10 @@ export interface TestType { - * console.log(`Finished ${testInfo.title} with status ${testInfo.status}`); + * test.afterEach(async ({ page }) => { + * console.log(`Finished ${test.info().title} with status ${test.info().status}`); * - * if (testInfo.status !== testInfo.expectedStatus) + * if (test.info().status !== test.info().expectedStatus) * console.log(`Did not run as expected, ended up at ${page.url()}`); * }); * @@ -3206,6 +4089,16 @@ export interface TestType { + * if (test.info().status !== test.info().expectedStatus) + * console.log(`Did not run as expected, ended up at ${page.url()}`); + * }); + * ``` + * * @param title Hook title. * @param hookFunction Hook function that takes one or two arguments: an object with fixtures and optional {@link TestInfo}. */ @@ -3213,20 +4106,24 @@ export interface TestType { + * console.log('Before tests'); + * }); + * ``` + * + * @param title Hook title. * @param hookFunction Hook function that takes one or two arguments: an object with worker fixtures and optional {@link TestInfo}. */ beforeAll(inner: (args: TestArgs & WorkerArgs, testInfo: TestInfo) => Promise | any): void; /** - * Declares a `beforeAll` hook with a title that is executed once per worker process before all tests. + * 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 + * [test.describe([title, callback])](https://playwright.dev/docs/api/class-test#test-describe) group, runs before all + * tests in the group. + * + * You can use [test.afterAll([title, hookFunction])](https://playwright.dev/docs/api/class-test#test-after-all) to + * teardown any resources set up in `beforeAll`. + * - `test.beforeAll(hookFunction)` + * - `test.beforeAll(title, hookFunction)` * * **Details** * - * See [test.beforeAll(hookFunction)](https://playwright.dev/docs/api/class-test#test-before-all-1). + * When 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). + * + * Playwright will continue running all applicable hooks even if some of them have failed. * * **Usage** * @@ -3262,15 +4183,28 @@ export interface TestType { + * test.beforeAll(async () => { * console.log('Before tests'); * }); * + * test.afterAll(async () => { + * console.log('After tests'); + * }); + * * test('my test', async ({ page }) => { * // ... * }); * ``` * + * Alternatively, you can declare a hook **with a title**. + * + * ```js + * // example.spec.ts + * test.beforeAll('Setup', async () => { + * console.log('Before tests'); + * }); + * ``` + * * @param title Hook title. * @param hookFunction Hook function that takes one or two arguments: an object with worker fixtures and optional {@link TestInfo}. */ @@ -3278,16 +4212,20 @@ export interface TestType { + * console.log('Done with tests'); + * // ... + * }); + * ``` + * + * @param title Hook title. * @param hookFunction Hook function that takes one or two arguments: an object with worker fixtures and optional {@link TestInfo}. */ afterAll(inner: (args: TestArgs & WorkerArgs, testInfo: TestInfo) => Promise | any): void; /** - * Declares an `afterAll` hook with a title that is executed once per worker after all tests. + * 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 + * [test.describe([title, callback])](https://playwright.dev/docs/api/class-test#test-describe) group, runs after all + * tests in the group. * * **Details** * - * See [test.afterAll(hookFunction)](https://playwright.dev/docs/api/class-test#test-after-all-1). + * When 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). + * + * Playwright will continue running all applicable hooks even if some of them have failed. + * - `test.afterAll(hookFunction)` + * - `test.afterAll(title, hookFunction)` * * **Usage** * * ```js + * test.afterAll(async () => { + * console.log('Done with tests'); + * // ... + * }); + * ``` + * + * Alternatively, you can declare a hook **with a title**. + * + * ```js * test.afterAll('Teardown', async () => { * console.log('Done with tests'); * // ... @@ -3323,7 +4291,7 @@ export interface TestType 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 + * [test.describe([title, callback])](https://playwright.dev/docs/api/class-test#test-describe) group. Most useful to * set an option, for example set `locale` to configure `context` fixture. * * **Usage** diff --git a/packages/playwright/types/testReporter.d.ts b/packages/playwright/types/testReporter.d.ts index d38f07be54..19735e972b 100644 --- a/packages/playwright/types/testReporter.d.ts +++ b/packages/playwright/types/testReporter.d.ts @@ -26,7 +26,7 @@ export type { FullConfig, TestStatus } from './test'; * - {@link TestCase} #1 * - {@link TestCase} #2 * - Suite corresponding to a - * [test.describe(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-1) group + * [test.describe([title, callback])](https://playwright.dev/docs/api/class-test#test-describe) group * - {@link TestCase} #1 in a group * - {@link TestCase} #2 in a group * - < more test cases ... > @@ -71,7 +71,7 @@ export interface Suite { /** * Test cases in the suite. Note that only test cases defined directly in this suite are in the list. Any test cases - * defined in nested [test.describe(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-1) + * defined in nested [test.describe([title, callback])](https://playwright.dev/docs/api/class-test#test-describe) * groups are listed in the child [suite.suites](https://playwright.dev/docs/api/class-suite#suite-suites). */ tests: Array; @@ -81,27 +81,29 @@ export interface Suite { * - Empty for root suite. * - Project name for project suite. * - File path for file suite. - * - Title passed to [test.describe(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-1) + * - Title passed to [test.describe([title, callback])](https://playwright.dev/docs/api/class-test#test-describe) * for a group suite. */ title: string; } /** - * `TestCase` corresponds to every - * [test.(call)(title, testFunction)](https://playwright.dev/docs/api/class-test#test-call) call in a test file. When - * a single [test.(call)(title, testFunction)](https://playwright.dev/docs/api/class-test#test-call) is running in - * multiple projects or repeated multiple times, it will have multiple `TestCase` objects in corresponding projects' - * suites. + * `TestCase` corresponds to every [test.(call)(title, body)](https://playwright.dev/docs/api/class-test#test-call) + * call in a test file. When a single [test.(call)(title, body)](https://playwright.dev/docs/api/class-test#test-call) + * is running in multiple projects or repeated multiple times, it will have multiple `TestCase` objects in + * corresponding projects' suites. */ export interface TestCase { /** * Expected test status. - * - Tests marked as [test.skip(title, testFunction)](https://playwright.dev/docs/api/class-test#test-skip-1) or - * [test.fixme(title, testFunction)](https://playwright.dev/docs/api/class-test#test-fixme-1) are expected to be - * `'skipped'`. - * - Tests marked as [test.fail()](https://playwright.dev/docs/api/class-test#test-fail-1) are expected to be - * `'failed'`. + * - Tests marked as + * [test.skip([title, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-skip) + * or + * [test.fixme([title, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fixme) + * are expected to be `'skipped'`. + * - Tests marked as + * [test.fail([title, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fail) + * are expected to be `'failed'`. * - Other tests are expected to be `'passed'`. * * See also [testResult.status](https://playwright.dev/docs/api/class-testresult#test-result-status) for the actual @@ -128,7 +130,7 @@ export interface TestCase { /** * The list of annotations applicable to the current test. Includes annotations from the test, annotations from all - * [test.describe(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-1) groups the test + * [test.describe([title, callback])](https://playwright.dev/docs/api/class-test#test-describe) groups the test * belongs to and file-level annotations for the test file. * * Annotations are available during test execution through @@ -187,14 +189,13 @@ export interface TestCase { * [testConfig.timeout](https://playwright.dev/docs/api/class-testconfig#test-config-timeout), * [testProject.timeout](https://playwright.dev/docs/api/class-testproject#test-project-timeout), * [test.setTimeout(timeout)](https://playwright.dev/docs/api/class-test#test-set-timeout), - * [test.slow()](https://playwright.dev/docs/api/class-test#test-slow-1) and + * [test.slow([condition, callback, description])](https://playwright.dev/docs/api/class-test#test-slow) and * [testInfo.setTimeout(timeout)](https://playwright.dev/docs/api/class-testinfo#test-info-set-timeout). */ timeout: number; /** - * Test title as passed to the - * [test.(call)(title, testFunction)](https://playwright.dev/docs/api/class-test#test-call) call. + * Test title as passed to the [test.(call)(title, body)](https://playwright.dev/docs/api/class-test#test-call) call. */ title: string; } diff --git a/utils/generate_types/index.js b/utils/generate_types/index.js index 4631046402..d41750e822 100644 --- a/utils/generate_types/index.js +++ b/utils/generate_types/index.js @@ -98,7 +98,7 @@ class TypesGenerator { }, (className, methodName, overloadIndex) => { if (className === 'SuiteFunction' && methodName === '__call') { const cls = this.documentation.classes.get('Test'); - const method = cls.membersArray.find(m => m.alias === 'describe' && m.overloadIndex === overloadIndex); + const method = cls.membersArray.find(m => m.alias === 'describe'); return this.memberJSDOC(method, ' ').trimLeft(); } diff --git a/utils/generate_types/overrides-test.d.ts b/utils/generate_types/overrides-test.d.ts index 464cd7f8b2..6ef214bc54 100644 --- a/utils/generate_types/overrides-test.d.ts +++ b/utils/generate_types/overrides-test.d.ts @@ -142,10 +142,10 @@ export interface TestType boolean, description?: string): void; - fail(): void; + fail(title: string, testFunction: (args: TestArgs & WorkerArgs, testInfo: TestInfo) => Promise | void): void; fail(condition: boolean, description?: string): void; fail(callback: (args: TestArgs & WorkerArgs) => boolean, description?: string): void; - fail(title: string, testFunction: (args: TestArgs & WorkerArgs, testInfo: TestInfo) => Promise | void): void; + fail(): void; slow(): void; slow(condition: boolean, description?: string): void; slow(callback: (args: TestArgs & WorkerArgs) => boolean, description?: string): void;