注解

介绍

Playwright 支持标签和注解，并将它们显示在测试报告中。

你可以随时添加自定义标签和注解，但 Playwright 也提供了一些内置的注解：

test.skip()：标记测试为无关，Playwright 不会运行该测试。当测试在某些配置下不适用时使用此注解。
test.fail()：标记测试为失败，Playwright 会运行该测试并确保它确实失败。如果测试没有失败，Playwright 会提示错误。
test.fixme()：标记测试为失败，Playwright 不会运行此测试（与 fail 注解不同）。当测试运行缓慢或崩溃时使用 fixme 注解。
test.slow()：标记测试为慢，三倍增加测试的超时时间。

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

内置注解可以是条件性的，当条件为真时应用，它们可能依赖于测试的设置。一个测试上可以有多个注解，可能在不同的配置中。

关注测试

你可以关注某些测试。当存在关注测试时，只有这些测试会被运行。

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

跳过测试

标记测试为跳过。

test.skip('skip this test', async ({ page }) => {
  // 该测试不会运行
});

条件跳过测试

你可以根据条件跳过某些测试。

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

分组测试

你可以将测试分组，给它们一个逻辑名称，或者将 before/after 钩子限定于该组内。

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

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

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

标记测试

有时你希望给测试加上 @fast 或 @slow 标签，然后在测试报告中通过标签进行过滤。或者你可能只想运行具有特定标签的测试。

要标记测试，可以在声明测试时提供附加的详细信息对象，或者在测试标题中添加 @ 符号的标签。请注意，标签必须以 @ 符号开头。

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

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

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

你也可以为整个测试组打标签或提供多个标签：

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 命令行选项来运行具有特定标签的测试。

Bash
PowerShell
Batch

npx playwright test --grep @fast

npx playwright test --grep "@fast"

npx playwright test --grep @fast

或者，如果你希望相反地跳过具有某个标签的测试：

Bash
PowerShell
Batch

npx playwright test --grep-invert @fast

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

npx playwright test --grep-invert @fast

要运行包含任意标签的测试（逻辑 OR 操作符）：

Bash
PowerShell
Batch

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

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

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

或者使用正则表达式前瞻运行同时包含两个标签的测试（逻辑 AND 操作符）：

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

你也可以通过【testConfig.grep】和【testProject.grep】在配置文件中过滤测试。

注解测试

如果你希望在测试中添加比标签更具说明性的注解，可以在声明测试时做到这一点。注解有 type 和 description，以便提供更多上下文，并可以通过 reporter API 获取。Playwright 内置的 HTML 报告器会显示所有注解，除了那些 type 以 _ 符号开头的注解。

例如，要在测试中添加问题的 URL 注解：

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

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

你还可以为整个测试组加注解或提供多个注解：

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

条件跳过一组测试

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

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

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

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

运行时注解

在测试运行过程中，你也可以通过【test.info().annotations】添加注解。

example.spec.ts

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

  // ...
});