43. 测试分组、标签与跳过条件执行

测试一多，就得会「分类」和「挑着跑」。Playwright 给了分组、标签、注解三套工具，让你在几百条测试里精准定位想要的那几条。

用 describe 分组

test.describe 把相关测试拢到一起，可以给它们一个逻辑名字，也能圈定一组专属的钩子：

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

test.describe('报表相关', () => {
  test('表头正确', async ({ page }) => { /* ... */ });
  test('导出按钮可见', async ({ page }) => { /* ... */ });
});

用 @tag 打标签

标签（tag）以 @ 开头，可以贴在单条测试，也可以贴在整组：

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

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

test('完整报表 @slow', async ({ page }) => { /* ... */ });

test.describe('报表组', { tag: '@report' }, () => {
  test('报表头', async ({ page }) => { /* ... */ });
  test('完整报表', { tag: ['@slow', '@vrt'] }, async ({ page }) => { /* ... */ });
});

按标签筛着跑

只跑带某标签的测试：

npx playwright test --grep @fast

反过来，跳过某标签：

npx playwright test --grep-invert @fast

多个标签用正则组合，比如「或」关系：

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

「且」关系（既要又要）用正则前瞻：

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

跳过：test.skip

test.skip 标记的测试不会被执行，适合「当前环境不适用」的场景：

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

test('火狐不支持，跳过', async ({ page, browserName }) => {
  test.skip(browserName === 'firefox', '火狐尚未支持');
  // 下面的代码在火狐上不会执行
});

整组跳过也行，用回调判断：

test.describe('仅 chromium', () => {
  test.skip(({ browserName }) => browserName !== 'chromium', '只跑 chromium');
  test('测试 1', async ({ page }) => { /* ... */ });
});

待修：test.fixme

fixme 和 skip 类似，但语义不同：skip 表示「本就不该跑」，fixme 表示「应该跑但还没修好，先放着」。

test('已知缺陷，待修复', async ({ page }) => {
  test.fixme(true, '这个功能还没实现');
});

它还能放在 beforeEach 里，连钩子一起跳过：

test.beforeEach(async ({ page, isMobile }) => {
  test.fixme(isMobile, '移动端设置页暂不支持');
  await page.goto('http://localhost:3000/settings');
});

聚焦：test.only

调试时只想跑某几条，用 test.only。一旦存在 focused 测试，其余全部不跑：

test.only('只跑这一条', async ({ page }) => { /* ... */ });

标记慢测试：test.slow

有些测试就是慢，用 test.slow 把超时放大三倍，避免误判失败：

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

test('耗时导出', async ({ page }) => {
  test.slow();   // 本条测试的超时变成原来的三倍
  // ...
});

更丰富的注解

除了标签，还能加 annotation（注解），带 type 和 description，在报告里展示：

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

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

测到一半也能动态加注解：

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

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

怎么排兵布阵

我的习惯：长期标签化（@smoke、@slow、@regression），临时用 only 调试、用完即删，skip/fixme 当作可读的「待办标记」写进代码。报告一开，哪些快、哪些慢、哪些挂着没修，一目了然。

小结

分组、标签、注解三件套：describe 给测试归堆，@tag 配合 --grep 筛着跑，skip/fixme/only/slow 管条件执行。skip 是「不该跑」，fixme 是「还没修好」，only 调试完记得删，slow 给慢测试放宽超时。标签长期维护，注解补上下文，这套组合用熟了管理几百条测试不费劲。