跳到主要内容

测试注解

简介​

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

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

  • test.skip() 将测试标记为无关项。Playwright 不会运行此类测试。当测试在某些配置中不适用时使用此注解。
  • test.fail() 将测试标记为预期失败。Playwright 会运行此测试并确保它确实失败。如果测试没有失败，Playwright 会报错。
  • test.fixme() 将测试标记为需要修复。与 fail 注解不同，Playwright 不会运行此测试。当测试运行缓慢或会导致崩溃时使用 fixme。
  • test.slow() 将测试标记为慢速测试，并将测试超时时间延长三倍。

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

内置注解可以是条件性的，当条件为真时应用，并且可能依赖于测试夹具。同一个测试可以有多个注解，可能在不同的配置下应用。

聚焦测试​

您可以聚焦某些测试。当存在聚焦测试时，只会运行这些测试。

test.only('聚焦此测试', async ({ page }) => {
  // 在整个项目中只运行被聚焦的测试
});

跳过测试​

将测试标记为跳过。

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

条件性跳过测试​

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

test('跳过此测试', async ({ page, browserName }) => {
  test.skip(browserName === 'firefox', '仍在处理中');
});

分组测试​

你可以将测试分组，为它们赋予逻辑名称或在组内限定 before/after 钩子的作用范围。

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

test.describe('两个测试', () => {
  test('第一个', async ({ page }) => {
    // ...
  });

  test('第二个', async ({ page }) => {
    // ...
  });
});

测试标签​

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

要给测试添加标签，可以在声明测试时提供额外的 details 对象，或者在测试标题中添加 @ 标记。请注意，标签必须以 @ 符号开头。

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

test('测试登录页面', {
  tag: '@fast',
}, async ({ page }) => {
  // ...
});

test('测试完整报告 @slow', async ({ page }) => {
  // ...
});

您也可以为整个测试组添加标签或提供多个标签：

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

test.describe('测试组', {
  tag: '@report',
}, () => {
  test('测试报告头部', async ({ page }) => {
    // ...
  });

  test('测试完整报告', {
    tag: ['@slow', '@vrt'],
  }, async ({ page }) => {
    // ...
  });
});

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

npx playwright test --grep @fast

或者如果您想要相反的效果，可以跳过具有特定标签的测试：

npx playwright test --grep-invert @fast

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

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

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

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

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

为测试添加注解​

如果您想为测试添加比标签更丰富的注解，可以在声明测试时进行操作。注解包含 type（类型）和 description（描述）以提供更多上下文，并且可通过报告器 API 获取。Playwright 内置的 HTML 报告器会显示所有注解，除非注解的 type 以 _ 符号开头。

例如，为测试添加问题链接的注解：

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

test('测试登录页面', {
  annotation: {
    type: 'issue',
    description: 'https://github.com/microsoft/playwright/issues/23180',
  },
}, async ({ page }) => {
  // ...
});

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

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

test.describe('报告测试', {
  annotation: { type: 'category', description: 'report' },
}, () => {
  test('测试报告头部', async ({ page }) => {
    // ...
  });

  test('测试完整报告', {
    annotation: [
      { type: 'issue', description: 'https://github.com/microsoft/playwright/issues/23180' },
      { type: 'performance', description: '非常慢的测试！' },
    ],
  }, async ({ page }) => {
    // ...
  });
});

有条件地跳过一组测试​

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

example.spec.ts

test.describe('仅限 Chromium', () => {
  test.skip(({ browserName }) => browserName !== 'chromium', '仅限 Chromium！');

  test.beforeAll(async () => {
    // 这个钩子仅在 Chromium 中运行
  });

  test('测试 1', async ({ page }) => {
    // 这个测试仅在 Chromium 中运行
  });

  test('测试 2', async ({ page }) => {
    // 这个测试仅在 Chromium 中运行
  });
});

在 beforeEach 钩子中使用 fixme​

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

example.spec.ts

test.beforeEach(async ({ page, isMobile }) => {
  test.fixme(isMobile, '设置页面在移动端尚未支持');

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

test('用户资料', async ({ page }) => {
  await page.getByText('我的资料').click();
  // ...
});

运行时注解​

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

example.spec.ts

test('示例测试', async ({ page, browser }) => {
  test.info().annotations.push({
    type: '浏览器版本',
    description: browser.version(),
  });

  // ...
});