注释

介绍

🌐 Introduction

Playwright 支持测试报告中显示的标签和注释。

🌐 Playwright supports tags and annotations that are displayed in the test report.

你可以随时添加自己的标签和注释，但 Playwright 附带了一些内置标签和注释：

🌐 You can add your own tags and annotations at any moment, but Playwright comes with a few built-in ones:

test.skip() 将测试标记为不相关。Playwright 不会运行这样的测试。当测试在某些配置下不适用时，请使用此注解。
test.fail() 将测试标记为失败。Playwright 会运行此测试，并确保它确实失败。如果测试没有失败，Playwright 会发出警告。
test.fixme() 将测试标记为失败。Playwright 不会运行此测试，这与 fail 注解不同。当运行测试速度很慢或出现崩溃时使用 fixme。
test.slow() 将测试标记为慢，并将测试超时时间增加三倍。

注释可以添加到单个测试或一组测试中。

🌐 Annotations can be added to a single test or a group of tests.

内置注解可以是有条件的，在这种情况下，它们在条件为真时适用，并且可能依赖于测试夹具。同一个测试上可能有多个注解，可能处于不同的配置中。

🌐 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.

集中测试

🌐 Focus a test

你可以专注于某些测试。当有专注测试时，只有这些测试会运行。

🌐 You can focus some tests. When there are focused tests, only these tests run.

test.only('focus this test', async ({ page }) => {
  // Run only focused tests in the entire project.
});

跳过测试

🌐 Skip a test

将测试标记为已跳过。

🌐 Mark a test as skipped.

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.

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.

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

test.describe('two tests', () => {
  test('one', async ({ page }) => {
    // ...
  });

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

标签测试

🌐 Tag tests

有时你可能想将测试标记为 @fast 或 @slow，然后在测试报告中按标签进行筛选。或者你可能只想运行具有某个特定标签的测试。

🌐 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.

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

test('test login page', {
  tag: '@fast',
}, async ({ page }) => {
  // ...
});

test('test full report @slow', async ({ page }) => {
  // ...
});

你还可以标记组中的所有测试或提供多个标签：

🌐 You can also tag all tests in a group or provide multiple tags:

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 }) => {
    // ...
  });
});

你现在可以使用 --grep 命令行选项运行具有特定标签的测试。

🌐 You can now run tests that have a particular tag with --grep command line option.

Bash
PowerShell
Batch

npx playwright test --grep @fast

npx playwright test --grep "@fast"

npx playwright test --grep @fast

或者，如果你想要相反的结果，你可以跳过带有特定标签的测试：

🌐 Or if you want the opposite, you can skip the tests with a certain tag:

Bash
PowerShell
Batch

npx playwright test --grep-invert @fast

npx playwright test --grep-invert "@fast"

npx playwright test --grep-invert @fast

运行包含任一标签的测试（逻辑 OR 运算符）：

🌐 To run tests containing either tag (logical OR operator):

Bash
PowerShell
Batch

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

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

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

或者使用正则前瞻运行包含两个标签的测试（逻辑 AND 运算符）:

🌐 Or run tests containing both tags (logical AND operator) using regex lookaheads:

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

你还可以通过 testConfig.grep 和 testProject.grep 在配置文件中筛选测试。

🌐 You can also filter tests in the configuration file via testConfig.grep and testProject.grep.

注释测试

🌐 Annotate tests

如果你想用比标签更有实质性的内容来注释你的测试，可以在声明测试时进行。注释有一个 type 和一个 description 来提供更多上下文，并可以在报告 API 中使用。Playwright 内置的 HTML 报告器会显示所有注释，除了那些 type 以 _ 符号开头的注释。

🌐 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.

例如，要使用问题 url 注释测试：

🌐 For example, to annotate a test with an issue url:

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

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

你还可以注释一组中的所有测试或提供多个注释：

🌐 You can also annotate all tests in a group or provide multiple annotations:

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 }) => {
    // ...
  });
});

有条件地跳过一组测试

🌐 Conditionally skip a group of tests

例如，你可以通过传递回调仅在 Chromium 中运行一组测试。

🌐 For example, you can run a group of tests just in Chromium by passing a callback.

example.spec.ts

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.
  });
});

在 `beforeEach` 钩子中使用 fixme

🌐 Use fixme in beforeEach hook

为了避免运行 beforeEach 钩子，你可以在钩子本身中添加注解。

🌐 To avoid running beforeEach hooks, you can put annotations in the hook itself.

example.spec.ts

test.beforeEach(async ({ page, isMobile }) => {
  test.fixme(isMobile, 'Settings page does not work in mobile yet');

  await page.goto('http://localhost:3000/settings');
});

test('user profile', async ({ page }) => {
  await page.getByText('My Profile').click();
  // ...
});

运行时注释

🌐 Runtime annotations

在测试运行时，你可以向test.info().annotations添加注释。

🌐 While the test is already running, you can add annotations to test.info().annotations.

example.spec.ts

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

  // ...
});

介绍​

集中测试​

跳过测试​

有条件地跳过测试​

群组测试​

标签测试​

注释测试​

有条件地跳过一组测试​

在 beforeEach 钩子中使用 fixme​

运行时注释​

介绍