What does test.describe do in Playwright?

test.describe groups related tests under one title, and that title becomes part of every test name in the report. Hooks such as beforeEach declared inside the group run only for its tests, and a group can be nested, focused with .only, skipped with .skip or set up with .configure.

This answer is one piece of Chapter 16: The Test Runner.

Test Structure & Lifecycle
playwright.config.ts Complete Reference
Test Organization at Scale
Tags, Grep, and the Suite You Actually Run
What Runs Where, and What Serial Costs
Practice and interview questions: Assertions & Test Runner

Use test.describe() when several tests share a feature and some setup. The example groups two catalog tests under Catalog, nests a Search group inside it, and leaves one test outside.

The title becomes part of each test name. The run lists Catalog › Search › has a search box, so a failure in the report says which feature broke.

Hooks are scoped to the group. The beforeEach that opens the catalog runs for both tests inside Catalog, including the nested one. The test outside the group does its own goto.

Run one group from the terminal. The group title is part of the test title, so -g matches it: npx playwright test -g Catalog ran the two grouped tests and left the third alone. -g looks in every file, though. -g Search also picked up second test: search form exists from another spec file in the same folder, so add the file name when the pattern is short.

The modifiers:

test.describe.only() declares a focused group, and only it runs. Remove it before committing.
test.describe.skip() declares a skipped group. Its tests are reported as skipped.
test.describe.configure({ mode: 'parallel' }) configures the enclosing group, for example to run its tests in parallel. test.describe.serial exists, but the docs mark it as discouraged: tests that are isolated can run independently.

describe-suite.spec.js(https://practice.learnplayforge.com)

import { test, expect } from '@playwright/test';

test.describe('Catalog', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('/catalog.html?mock=static&seed=42&autologin=1');
  });

  test('shows the product grid', async ({ page }) => {
    await expect(page.getByTestId('product-grid')).toBeVisible();
  });

  test.describe('Search', () => {
    test('has a search box', async ({ page }) => {
      await expect(page.getByTestId('catalog-query')).toBeVisible();
    });
  });
});

test('header renders outside the group', async ({ page }) => {
  await page.goto('/catalog.html?mock=static&seed=42&autologin=1');
  await expect(page.getByTestId('site-header')).toBeVisible();
});

Output

$ npx playwright test describe-suite.spec.js
  ok 1 [chromium] › describe-suite.spec.js:8:3 › Catalog › shows the product grid (1.3s)
  ok 2 [chromium] › describe-suite.spec.js:13:5 › Catalog › Search › has a search box (281ms)
  ok 3 [chromium] › describe-suite.spec.js:19:1 › header renders outside the group (311ms)
  3 passed (3.1s)

$ npx playwright test -g Catalog
  ok 1 [chromium] › describe-suite.spec.js:8:3 › Catalog › shows the product grid (1.2s)
  ok 2 [chromium] › describe-suite.spec.js:13:5 › Catalog › Search › has a search box (287ms)
  2 passed (2.6s)

Test yourself

If you declare a test.beforeEach() hook inside a test.describe('Checkout', ...) block, which tests will run that hook?

Practised in the full course: the drill Config at the wrong scope.

See the chapter

AI can write the test now. The job is knowing whether it checks anything. That's what the course teaches, one chapter at a time.

163 lessons · 226 drills · start free

What does test.describe do in Playwright?

Related questions