Playwright Groups and Tags
Playwright Groups and Tags
Groups and tags help you organize tests and choose which tests to run.
A group puts related tests together under one name.
A tag is a label like @smoke that you can filter on when you run the tests.
Groups with test.describe
test.describe() creates a group.
A group can contain other groups, and each group can have its own hooks:
Example
tests/describe.spec.js
// @ts-check
import { test, expect } from '@playwright/test';
test.describe('todo list', () => {
test.beforeEach(async ({ page }) => {
await page.goto('https://www.w3schools.com/playwright/practice/todo.html');
});
test('starts empty', async ({ page }) => {
await expect(page.getByTestId('todo-count')).toHaveText('0 items left');
});
test.describe('with one todo', () => {
test.beforeEach(async ({ page }) => {
await page.getByPlaceholder('What needs to be done?').fill('Buy milk');
await page.getByRole('button', { name: 'Add' }).click();
});
test('shows the todo', async ({ page }) => {
await expect(page.getByRole('listitem')).toContainText('Buy milk');
});
test('can complete it', async ({ page }) => {
await page.getByRole('checkbox', { name: 'Complete Buy milk' }).check();
await expect(page.getByTestId('todo-count')).toHaveText('0 items left');
});
});
});
Example
npx playwright test tests/describe.spec.js --reporter=list
Output:
Running 3 tests using 3 workers
ok 2 [chromium] › tests/describe.spec.js:9:3 › todo list › starts empty (218ms)
ok 1 [chromium] › tests/describe.spec.js:19:5 › todo list › with one todo › shows the todo (998ms)
ok 3 [chromium] › tests/describe.spec.js:23:5 › todo list › with one todo › can complete it (991ms)
3 passed (2.5s)
The group names become part of the test name: todo list › with one todo › shows the todo.
The tests in the inner group run both beforeEach hooks: first the outer one, which opens the page, then the inner one, which adds a todo.
Tags
Add tags to a test with the tag option.
A tag starts with @, and one test can have several tags:
Example
tests/tags.spec.js
// @ts-check
import { test, expect } from '@playwright/test';
test('log in', { tag: '@smoke' }, async ({ page }) => {
await page.goto('https://www.w3schools.com/playwright/practice/login.html');
await page.getByLabel('Username').fill('student');
await page.getByLabel('Password').fill('w3schools');
await page.getByRole('button', { name: 'Log in' }).click();
await expect(page.getByTestId('welcome')).toBeVisible();
});
test('shop shows products', { tag: ['@smoke', '@shop'] }, async ({ page }) => {
await page.goto('https://www.w3schools.com/playwright/practice/shop.html');
await expect(page.getByTestId('product')).toHaveCount(5);
});
test('search finds one product', { tag: '@shop' }, async ({ page }) => {
await page.goto('https://www.w3schools.com/playwright/practice/shop.html');
await page.getByLabel('Search products').fill('Webcam');
await expect(page.getByTestId('product')).toHaveCount(1);
});
Use --grep to run only the tests that have a tag:
Example
npx playwright test --grep @smoke --reporter=list
Output:
Running 2 tests using 2 workers
ok 2 [chromium] › tests/tags.spec.js:12:1 › shop shows products @smoke @shop (188ms)
ok 1 [chromium] › tests/tags.spec.js:4:1 › log in @smoke (1.8s)
2 passed (3.6s)
Use --grep-invert to run all tests except the ones with a tag:
Example
npx playwright test tests/tags.spec.js --grep-invert @smoke --reporter=list
Output:
Running 1 test using 1 worker
ok 1 [chromium] › tests/tags.spec.js:17:1 › search finds one product @shop (215ms)
1 passed (1.5s)
--grep takes a regular expression (a text pattern).
To run the tests that have one tag or the other, use --grep "@smoke|@shop".
A whole group can have tags too: test.describe('shop', { tag: '@shop' }, () => { ... }).
Annotations
An annotation adds a note to a test, for example a link to a bug report.
It has a type and a description, and shows up in the HTML report:
Example
test('buy a webcam', {
annotation: { type: 'issue', description: 'https://example.com/issues/12' },
}, async ({ page }) => {
// ...
});
The reason you give to test.skip(), test.fixme() and test.fail() is also saved as an annotation.
You will learn about them in the Skip and Only chapter.
Steps with test.step
test.step() splits a long test into named steps.
The steps show up in the HTML report, in the Trace Viewer, and in the list reporter if you turn on printSteps:
Example
playwright.config.js
reporter: [['list', { printSteps: true }]],
Example
tests/steps.spec.js
// @ts-check
import { test, expect } from '@playwright/test';
test('buy a webcam', {
annotation: { type: 'issue', description: 'https://example.com/issues/12' },
}, async ({ page }) => {
await test.step('open the shop', async () => {
await page.goto('https://www.w3schools.com/playwright/practice/shop.html');
await expect(page.getByTestId('product')).toHaveCount(5);
});
await test.step('search for the webcam', async () => {
await page.getByLabel('Search products').fill('Webcam');
await expect(page.getByTestId('product')).toHaveCount(1);
});
await test.step('add it to the cart', async () => {
await page.getByRole('button', { name: 'Add to cart' }).click();
await expect(page.getByTestId('cart-total')).toHaveText('$39.90');
});
});
Output:
Running 1 test using 1 worker
1.1 [chromium] › tests/steps.spec.js:4:1 › buy a webcam › open the shop (71ms)
1.2 [chromium] › tests/steps.spec.js:4:1 › buy a webcam › search for the webcam (31ms)
1.3 [chromium] › tests/steps.spec.js:4:1 › buy a webcam › add it to the cart (848ms)
ok 1 [chromium] › tests/steps.spec.js:4:1 › buy a webcam (1.1s)
1 passed (2.2s)
Each step is printed with its name and how long it took.
When a test fails inside a step, the error tells you which step failed.