Skip to main content

注释

介绍​

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

  • test.fail() 将测试标记为失败。Playwright 将运行此测试并确保它确实失败。如果测试没有失败，Playwright 就会抗诉。

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

  • test.fixme() 将测试标记为失败。与 fail 注释相反，Playwright 不会运行此测试。当运行测试缓慢或崩溃时使用 fixme。

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

  • test.slow() 将测试标记为慢速并将测试超时增加三倍。

    ¥test.slow() marks the test as slow and triples the test timeout.

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

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

要标记测试，请在声明测试时提供额外的详细信息对象，或将 @-token 添加到测试标题。请注意，标签必须以 @ 符号开头。

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

npx playwright test --grep @fast

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

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

npx playwright test --grep-invert @fast

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

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

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(),
  });

  // ...
});