Playwright Annotations

What Are Annotations in Playwright?

Annotations are markers that you can attach to your tests to provide additional context, control test execution, or categorize tests. Playwright comes with several built-in annotations, and you can also create custom ones to suit your needs.

Built-in Annotations

Playwright provides a set of built-in annotations that can be used to control the behavior of your tests:

1. test.skip(): Marks the test as irrelevant. Playwright will skip running this test. Use this when the test is not applicable under certain configurations.

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

test.skip('skip this test', async ({ page }) => {
  // This test will be skipped
});

1. test.fail(): Marks the test as expected to fail. Playwright will run the test and expect it to fail. If the test does not fail, Playwright will report it as an issue.

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

test.fail('this test is expected to fail', async ({ page }) => {
  // This test is expected to fail
});

1. test.fixme(): Marks the test as failing but will not run it. Use this for tests that are slow or have issues that prevent them from running.

`import { test } from '@playwright/test';

test.fixme('this test is not yet ready', async ({ page }) => {
// This test will not run
});`

1. test.slow(): Marks the test as slow, which increases the timeout duration for this test by three times.

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

test.slow('this test is slow', async ({ page }) => {
  // This test has an extended timeout
});

Focus and Skip Tests

You can focus on specific tests or skip them based on the following conditions:

Focus a Test: Run only the focused tests in the entire test suite.

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

test.only('focus this test', async ({ page }) => {
  // This test will be the only one executed
});

Conditionally Skip a Test: Skip a test based on a condition.

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

test('conditionally skip this test', async ({ page, browserName }) => {
  test.skip(browserName === 'firefox', 'Still working on Firefox support');
});

Grouping Tests

Grouping tests allow you to organize them logically and apply hooks at the group level.

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

test.describe('Group of tests', () => {
  test('test one', async ({ page }) => {
    // Test implementation
  });

  test('test two', async ({ page }) => {
    // Test implementation
  });
});

Tagging Tests

Tags help you categorize tests and run specific subsets based on these tags. Tags start with the @ symbol.

• Tag a Single Test:

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

test('test login page', {
  tags: ['@fast'],
}, async ({ page }) => {
  // Test implementation
});

• Tag a Group of Tests:

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

test.describe('Group with tags', {
  tags: ['@report'],
}, () => {
  test('test report header', async ({ page }) => {
    // Test implementation
  });

  test('test full report', {
    tags: ['@slow', '@vrt'],
  }, async ({ page }) => {
    // Test implementation
  });
});

Run Tests by Tag

1. Use the --grep option to run tests with specific tags:

npx playwright test --grep @fast

1. Skip tests with a specific tag using --grep-invert:

npx playwright test --grep-invert @fast

1. Run tests containing either tag (logical OR):

npx playwright test --grep "@fast|@slow"

1. Run tests containing both tags (logical AND) using regex lookaheads:

npx playwright test --grep "(?=.*@fast)(?=.*@slow)"

Annotating Tests

Annotations provide more detailed context beyond tags. You can add annotations with a type and description.

• Annotate a Single Test:

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

test('test login page', {
  annotations: [
    { type: 'issue', description: 'https://github.com/microsoft/playwright/issues/23180' },
  ],
}, async ({ page }) => {
  // Test implementation
});

• Annotate a Group of Tests:

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

test.describe('Annotated tests group', {
  annotations: [{ type: 'category', description: 'report' }],
}, () => {
  test('test report header', async ({ page }) => {
    // Test implementation
  });

  test('test full report', {
    annotations: [
      { type: 'issue', description: 'https://github.com/microsoft/playwright/issues/23180' },
      { type: 'performance', description: 'very slow test!' },
    ],
  }, async ({ page }) => {
    // Test implementation
  });
});

Conditional Hooks

Use hooks like beforeEach conditionally to skip setup code based on conditions.

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

test.beforeEach(async ({ page, isMobile }) => {
  test.fixme(isMobile, 'Settings page does not work in mobile yet');
  await page.goto('http://localhost:3000/settings');
});

Runtime Annotations

You can also add annotations while the test is running:

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

test('example test', async ({ page, browser }) => {
  test.info().annotations.push({
    type: 'browser version',
    description: browser.version(),
  });

  // Test implementation
});

Summary

Annotations in Playwright offer a flexible way to manage and categorize your tests, control their execution, and enhance reporting. By leveraging built-in annotations, tags, and custom annotations, you can tailor your testing strategy to fit your specific needs, improve test organization, and make debugging easier