2021-05-27 20:30:03 -07:00
---
id: test-annotations
title: "Annotations"
---
2023-10-06 15:08:51 +02:00
## Introduction
feat(test runner): tags/annotations (#29248)
API changes:
- `test(title, details, body)` where details contain `tag` and
`annotation`.
- similar `details` property added to `test.skip`, `test.fail`,
`test.fixme`, `test.only`, `test.describe` and other `test.describe.*`
variations.
- `TestProject.tagFilter`/`TestConfig.tagFilter` that supports logical
tag expressions with `(`, `)`, `and`, `or` and `not`.
- `--tag` CLI option to filter by tags.
- New annotations are available in `TestInfo.annotations` and
`TestCase.annotations`.
- New tags are available in `TestCase.tags`.
Reporter changes:
- `json` reporter includes new tags in addition to old `@smoke`-style
tags. **Breaking**: tags are now listed with the leading `@` symbol.
- `html` reporter filters by old and new tags with the same `@smoke`
token.
Fixes #29229, fixes #23180.
2024-02-07 16:31:25 -08:00
Playwright supports tags and annotations that are displayed in the test report.
You can add your own tags and annotations at any moment, but Playwright comes with a few built-in ones:
- [`method: Test.skip` ] marks the test as irrelevant. Playwright 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 will run this test and ensure it does indeed fail. If the test does not fail, Playwright will complain.
- [`method: Test.fixme` ] marks the test as failing. Playwright will not run this test, as opposed to the `fail` annotation. Use `fixme` when running the test is slow or crashes.
2024-02-05 19:03:04 -08:00
- [`method: Test.slow` ] marks the test as slow and triples the test timeout.
2021-06-18 17:56:59 -07:00
2024-02-15 11:37:16 -08:00
Annotations can be added to a single test or a group of tests.
feat(test runner): tags/annotations (#29248)
API changes:
- `test(title, details, body)` where details contain `tag` and
`annotation`.
- similar `details` property added to `test.skip`, `test.fail`,
`test.fixme`, `test.only`, `test.describe` and other `test.describe.*`
variations.
- `TestProject.tagFilter`/`TestConfig.tagFilter` that supports logical
tag expressions with `(`, `)`, `and`, `or` and `not`.
- `--tag` CLI option to filter by tags.
- New annotations are available in `TestInfo.annotations` and
`TestCase.annotations`.
- New tags are available in `TestCase.tags`.
Reporter changes:
- `json` reporter includes new tags in addition to old `@smoke`-style
tags. **Breaking**: tags are now listed with the leading `@` symbol.
- `html` reporter filters by old and new tags with the same `@smoke`
token.
Fixes #29229, fixes #23180.
2024-02-07 16:31:25 -08:00
Built-in annotations can be conditional, in which case they apply when the condition is truthy, and may depend on test fixtures. There could be multiple annotations on the same test, possibly in different configurations.
2021-07-09 16:13:33 -07:00
2021-06-18 17:56:59 -07:00
## Focus a test
You can focus some tests. When there are focused tests, only these tests run.
2021-05-27 20:30:03 -07:00
2023-03-16 21:16:18 +01:00
```js
2021-06-18 17:56:59 -07:00
test.only('focus this test', async ({ page }) => {
// Run only focused tests in the entire project.
2021-05-29 08:58:17 -07:00
});
2021-06-18 17:56:59 -07:00
```
## Skip a test
2021-05-29 08:58:17 -07:00
2021-07-29 14:33:37 -07:00
Mark a test as skipped.
2023-03-16 21:16:18 +01:00
```js
2021-07-29 14:33:37 -07:00
test.skip('skip this test', async ({ page }) => {
// This test is not run
});
```
## Conditionally skip a test
You can skip certain test based on the condition.
2021-06-18 17:56:59 -07:00
2023-03-16 21:16:18 +01:00
```js
2021-06-18 17:56:59 -07:00
test('skip this test', async ({ page, browserName }) => {
test.skip(browserName === 'firefox', 'Still working on it');
});
```
## Group tests
You can group tests to give them a logical name or to scope before/after hooks to the group.
2021-05-27 20:30:03 -07:00
2023-03-16 21:16:18 +01:00
```js
2021-06-18 17:56:59 -07:00
import { test, expect } from '@playwright/test ';
2021-05-27 20:30:03 -07:00
2021-06-18 17:56:59 -07:00
test.describe('two tests', () => {
test('one', async ({ page }) => {
// ...
});
test('two', async ({ page }) => {
// ...
});
2021-05-27 20:30:03 -07:00
});
```
2021-06-18 17:56:59 -07:00
## Tag tests
2024-02-15 11:37:16 -08:00
Sometimes you want to tag your tests as `@fast` or `@slow` , and then filter by tag in the test report. Or you might want to only run tests that have a certain tag.
To tag a test, either provide an additional details object when declaring a test, or add `@` -token to the test title. Note that tags must start with `@` symbol.
2021-06-18 17:56:59 -07:00
2023-03-16 21:16:18 +01:00
```js
2021-06-18 17:56:59 -07:00
import { test, expect } from '@playwright/test ';
feat(test runner): tags/annotations (#29248)
API changes:
- `test(title, details, body)` where details contain `tag` and
`annotation`.
- similar `details` property added to `test.skip`, `test.fail`,
`test.fixme`, `test.only`, `test.describe` and other `test.describe.*`
variations.
- `TestProject.tagFilter`/`TestConfig.tagFilter` that supports logical
tag expressions with `(`, `)`, `and`, `or` and `not`.
- `--tag` CLI option to filter by tags.
- New annotations are available in `TestInfo.annotations` and
`TestCase.annotations`.
- New tags are available in `TestCase.tags`.
Reporter changes:
- `json` reporter includes new tags in addition to old `@smoke`-style
tags. **Breaking**: tags are now listed with the leading `@` symbol.
- `html` reporter filters by old and new tags with the same `@smoke`
token.
Fixes #29229, fixes #23180.
2024-02-07 16:31:25 -08:00
test('test login page', {
tag: '@fast ',
}, async ({ page }) => {
2021-06-18 17:56:59 -07:00
// ...
});
2024-02-15 11:37:16 -08:00
test('test full report @slow ', async ({ page }) => {
2021-06-18 17:56:59 -07:00
// ...
});
```
feat(test runner): tags/annotations (#29248)
API changes:
- `test(title, details, body)` where details contain `tag` and
`annotation`.
- similar `details` property added to `test.skip`, `test.fail`,
`test.fixme`, `test.only`, `test.describe` and other `test.describe.*`
variations.
- `TestProject.tagFilter`/`TestConfig.tagFilter` that supports logical
tag expressions with `(`, `)`, `and`, `or` and `not`.
- `--tag` CLI option to filter by tags.
- New annotations are available in `TestInfo.annotations` and
`TestCase.annotations`.
- New tags are available in `TestCase.tags`.
Reporter changes:
- `json` reporter includes new tags in addition to old `@smoke`-style
tags. **Breaking**: tags are now listed with the leading `@` symbol.
- `html` reporter filters by old and new tags with the same `@smoke`
token.
Fixes #29229, fixes #23180.
2024-02-07 16:31:25 -08:00
You can also tag all tests in a group or provide multiple tags:
```js
import { test, expect } from '@playwright/test ';
test.describe('group', {
tag: '@report ',
}, () => {
test('test report header', async ({ page }) => {
// ...
});
test('test full report', {
tag: ['@slow ', '@vrt '],
}, async ({ page }) => {
// ...
});
});
```
2024-02-15 11:37:16 -08:00
You can now run tests that have a particular tag with [`--grep` ](./test-cli.md#reference ) command line option.
2021-06-18 17:56:59 -07:00
2023-12-20 09:56:37 -08:00
```bash tab=bash-bash
2024-02-15 11:37:16 -08:00
npx playwright test --grep @fast
2021-06-18 17:56:59 -07:00
```
2023-12-20 09:56:37 -08:00
```powershell tab=bash-powershell
2024-02-15 11:37:16 -08:00
npx playwright test --grep "@fast "
2023-12-20 09:56:37 -08:00
```
2021-06-18 17:56:59 -07:00
2023-12-20 09:56:37 -08:00
```batch tab=bash-batch
2024-02-15 11:37:16 -08:00
npx playwright test --grep @fast
2021-06-18 17:56:59 -07:00
```
2021-07-09 16:13:33 -07:00
2023-12-20 09:56:37 -08:00
Or if you want the opposite, you can skip the tests with a certain tag:
2023-05-09 14:52:48 -07:00
2023-12-20 09:56:37 -08:00
```bash tab=bash-bash
2024-02-15 11:37:16 -08:00
npx playwright test --grep-invert @fast
2023-05-09 14:52:48 -07:00
```
2023-12-20 09:56:37 -08:00
```powershell tab=bash-powershell
2024-02-15 11:37:16 -08:00
npx playwright test --grep-invert "@fast "
2023-12-20 09:56:37 -08:00
```
```batch tab=bash-batch
2024-02-15 11:37:16 -08:00
npx playwright test --grep-invert @fast
2023-12-20 09:56:37 -08:00
```
2023-07-22 00:30:40 +02:00
2024-02-15 11:37:16 -08:00
To run tests containing either tag (logical `OR` operator):
2023-07-24 20:10:39 +02:00
2023-12-20 09:56:37 -08:00
```bash tab=bash-bash
2024-02-15 11:37:16 -08:00
npx playwright test --grep "@fast |@slow "
2023-12-20 09:56:37 -08:00
```
2023-07-22 00:30:40 +02:00
2023-12-20 09:56:37 -08:00
```powershell tab=bash-powershell
2024-02-15 11:37:16 -08:00
npx playwright test --grep --% "@fast ^|@slow "
2023-12-20 09:56:37 -08:00
```
2023-07-24 20:10:39 +02:00
2023-12-20 09:56:37 -08:00
```batch tab=bash-batch
2024-02-15 11:37:16 -08:00
npx playwright test --grep "@fast ^|@slow "
feat(test runner): tags/annotations (#29248)
API changes:
- `test(title, details, body)` where details contain `tag` and
`annotation`.
- similar `details` property added to `test.skip`, `test.fail`,
`test.fixme`, `test.only`, `test.describe` and other `test.describe.*`
variations.
- `TestProject.tagFilter`/`TestConfig.tagFilter` that supports logical
tag expressions with `(`, `)`, `and`, `or` and `not`.
- `--tag` CLI option to filter by tags.
- New annotations are available in `TestInfo.annotations` and
`TestCase.annotations`.
- New tags are available in `TestCase.tags`.
Reporter changes:
- `json` reporter includes new tags in addition to old `@smoke`-style
tags. **Breaking**: tags are now listed with the leading `@` symbol.
- `html` reporter filters by old and new tags with the same `@smoke`
token.
Fixes #29229, fixes #23180.
2024-02-07 16:31:25 -08:00
```
2024-02-15 11:37:16 -08:00
Or run tests containing both tags (logical `AND` operator) using regex lookaheads:
```bash
npx playwright test --grep "(?=.*@fast )(?=.*@slow )"
```
You can also filter tests in the configuration file via [`property: TestConfig.grep` ] and [`property: TestProject.grep` ].
feat(test runner): tags/annotations (#29248)
API changes:
- `test(title, details, body)` where details contain `tag` and
`annotation`.
- similar `details` property added to `test.skip`, `test.fail`,
`test.fixme`, `test.only`, `test.describe` and other `test.describe.*`
variations.
- `TestProject.tagFilter`/`TestConfig.tagFilter` that supports logical
tag expressions with `(`, `)`, `and`, `or` and `not`.
- `--tag` CLI option to filter by tags.
- New annotations are available in `TestInfo.annotations` and
`TestCase.annotations`.
- New tags are available in `TestCase.tags`.
Reporter changes:
- `json` reporter includes new tags in addition to old `@smoke`-style
tags. **Breaking**: tags are now listed with the leading `@` symbol.
- `html` reporter filters by old and new tags with the same `@smoke`
token.
Fixes #29229, fixes #23180.
2024-02-07 16:31:25 -08:00
## Annotate tests
2024-07-03 03:46:24 +04:00
If you would like to annotate your tests with something more substantial than a tag, you can do that when declaring a test. Annotations have a `type` and a `description` for more context and available in reporter API. Playwright's built-in HTML reporter shows all annotations, except those where `type` starts with `_` symbol.
feat(test runner): tags/annotations (#29248)
API changes:
- `test(title, details, body)` where details contain `tag` and
`annotation`.
- similar `details` property added to `test.skip`, `test.fail`,
`test.fixme`, `test.only`, `test.describe` and other `test.describe.*`
variations.
- `TestProject.tagFilter`/`TestConfig.tagFilter` that supports logical
tag expressions with `(`, `)`, `and`, `or` and `not`.
- `--tag` CLI option to filter by tags.
- New annotations are available in `TestInfo.annotations` and
`TestCase.annotations`.
- New tags are available in `TestCase.tags`.
Reporter changes:
- `json` reporter includes new tags in addition to old `@smoke`-style
tags. **Breaking**: tags are now listed with the leading `@` symbol.
- `html` reporter filters by old and new tags with the same `@smoke`
token.
Fixes #29229, fixes #23180.
2024-02-07 16:31:25 -08:00
For example, to annotate a test with an issue url:
```js
import { test, expect } from '@playwright/test ';
test('test login page', {
annotation: {
type: 'issue',
description: 'https://github.com/microsoft/playwright/issues/23180',
},
}, async ({ page }) => {
// ...
});
2023-12-20 09:56:37 -08:00
```
2023-07-22 00:30:40 +02:00
feat(test runner): tags/annotations (#29248)
API changes:
- `test(title, details, body)` where details contain `tag` and
`annotation`.
- similar `details` property added to `test.skip`, `test.fail`,
`test.fixme`, `test.only`, `test.describe` and other `test.describe.*`
variations.
- `TestProject.tagFilter`/`TestConfig.tagFilter` that supports logical
tag expressions with `(`, `)`, `and`, `or` and `not`.
- `--tag` CLI option to filter by tags.
- New annotations are available in `TestInfo.annotations` and
`TestCase.annotations`.
- New tags are available in `TestCase.tags`.
Reporter changes:
- `json` reporter includes new tags in addition to old `@smoke`-style
tags. **Breaking**: tags are now listed with the leading `@` symbol.
- `html` reporter filters by old and new tags with the same `@smoke`
token.
Fixes #29229, fixes #23180.
2024-02-07 16:31:25 -08:00
You can also annotate all tests in a group or provide multiple annotations:
2023-05-09 14:52:48 -07:00
feat(test runner): tags/annotations (#29248)
API changes:
- `test(title, details, body)` where details contain `tag` and
`annotation`.
- similar `details` property added to `test.skip`, `test.fail`,
`test.fixme`, `test.only`, `test.describe` and other `test.describe.*`
variations.
- `TestProject.tagFilter`/`TestConfig.tagFilter` that supports logical
tag expressions with `(`, `)`, `and`, `or` and `not`.
- `--tag` CLI option to filter by tags.
- New annotations are available in `TestInfo.annotations` and
`TestCase.annotations`.
- New tags are available in `TestCase.tags`.
Reporter changes:
- `json` reporter includes new tags in addition to old `@smoke`-style
tags. **Breaking**: tags are now listed with the leading `@` symbol.
- `html` reporter filters by old and new tags with the same `@smoke`
token.
Fixes #29229, fixes #23180.
2024-02-07 16:31:25 -08:00
```js
import { test, expect } from '@playwright/test ';
test.describe('report tests', {
annotation: { type: 'category', description: 'report' },
}, () => {
test('test report header', async ({ page }) => {
// ...
});
test('test full report', {
annotation: [
{ type: 'issue', description: 'https://github.com/microsoft/playwright/issues/23180' },
{ type: 'performance', description: 'very slow test!' },
],
}, async ({ page }) => {
// ...
});
});
2023-05-09 14:52:48 -07:00
```
2021-07-09 16:13:33 -07:00
## Conditionally skip a group of tests
For example, you can run a group of tests just in Chromium by passing a callback.
2023-05-10 23:30:51 +02:00
```js title="example.spec.ts"
2021-07-09 16:13:33 -07:00
test.describe('chromium only', () => {
test.skip(({ browserName }) => browserName !== 'chromium', 'Chromium only!');
test.beforeAll(async () => {
// This hook is only run in Chromium.
});
test('test 1', async ({ page }) => {
// This test is only run in Chromium.
});
test('test 2', async ({ page }) => {
// This test is only run in Chromium.
});
});
```
## Use fixme in `beforeEach` hook
To avoid running `beforeEach` hooks, you can put annotations in the hook itself.
2023-05-10 23:30:51 +02:00
```js title="example.spec.ts"
2021-07-09 16:13:33 -07:00
2022-04-21 14:58:40 -04:00
test.beforeEach(async ({ page, isMobile }) => {
2021-07-09 16:13:33 -07:00
test.fixme(isMobile, 'Settings page does not work in mobile yet');
await page.goto('http://localhost:3000/settings');
});
test('user profile', async ({ page }) => {
2022-10-03 17:02:46 -07:00
await page.getByText('My Profile').click();
2021-07-09 16:13:33 -07:00
// ...
});
```
2022-03-11 19:09:23 +01:00
2024-02-15 11:37:16 -08:00
## Runtime annotations
2022-03-11 19:09:23 +01:00
2024-02-15 11:37:16 -08:00
While the test is already running, you can add annotations to [`test.info().annotations` ](./api/class-testinfo#test-info-annotations ).
2022-03-11 19:09:23 +01:00
2023-05-10 23:30:51 +02:00
```js title="example.spec.ts"
2022-03-11 19:09:23 +01:00
feat(test runner): tags/annotations (#29248)
API changes:
- `test(title, details, body)` where details contain `tag` and
`annotation`.
- similar `details` property added to `test.skip`, `test.fail`,
`test.fixme`, `test.only`, `test.describe` and other `test.describe.*`
variations.
- `TestProject.tagFilter`/`TestConfig.tagFilter` that supports logical
tag expressions with `(`, `)`, `and`, `or` and `not`.
- `--tag` CLI option to filter by tags.
- New annotations are available in `TestInfo.annotations` and
`TestCase.annotations`.
- New tags are available in `TestCase.tags`.
Reporter changes:
- `json` reporter includes new tags in addition to old `@smoke`-style
tags. **Breaking**: tags are now listed with the leading `@` symbol.
- `html` reporter filters by old and new tags with the same `@smoke`
token.
Fixes #29229, fixes #23180.
2024-02-07 16:31:25 -08:00
test('example test', async ({ page, browser }) => {
2023-08-02 11:23:47 +02:00
test.info().annotations.push({
feat(test runner): tags/annotations (#29248)
API changes:
- `test(title, details, body)` where details contain `tag` and
`annotation`.
- similar `details` property added to `test.skip`, `test.fail`,
`test.fixme`, `test.only`, `test.describe` and other `test.describe.*`
variations.
- `TestProject.tagFilter`/`TestConfig.tagFilter` that supports logical
tag expressions with `(`, `)`, `and`, `or` and `not`.
- `--tag` CLI option to filter by tags.
- New annotations are available in `TestInfo.annotations` and
`TestCase.annotations`.
- New tags are available in `TestCase.tags`.
Reporter changes:
- `json` reporter includes new tags in addition to old `@smoke`-style
tags. **Breaking**: tags are now listed with the leading `@` symbol.
- `html` reporter filters by old and new tags with the same `@smoke`
token.
Fixes #29229, fixes #23180.
2024-02-07 16:31:25 -08:00
type: 'browser version',
description: browser.version(),
2023-08-02 11:23:47 +02:00
});
2024-02-15 11:37:16 -08:00
2022-03-11 19:09:23 +01:00
// ...
});
```