Playwright 如何用注解标记不适用于当前环境的测试并条件跳过？

Playwright 如何用注解标记不适用于当前环境的测试并条件跳过？

【免费下载链接】playwrightPlaywright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.项目地址: https://gitcode.com/GitHub_Trending/pl/playwright

一个测试套件的用例往往要在 Chromium、WebKit、Firefox 多个浏览器（或不同设备形态）下各跑一遍。其中有些用例只在特定环境才成立：功能只在 WebKit 实现了、移动端布局还没有设置页、某浏览器下用例会直接崩溃。硬编码的if让测试变脏，直接删掉用例又损失了在其他环境下的覆盖。Playwright Test 内置的注解（annotations）解决的就是这个问题：test.skip标记测试"不适用于当前配置"，Playwright 不运行它；条件形式则让跳过只在条件为 truthy 时生效，且条件可以依赖测试 fixtures（如browserName），跳过原因会显示在测试报告中。

本文的前提是一个已经能跑npx playwright test的 Playwright Test 项目，目标是：让不适用于当前环境的测试不执行、在报告中保留跳过原因，并且不污染其他环境的运行结果。

先分清 skip、fixme 和 fail 的用途

三者都是 Playwright 内置注解，也都支持条件形式（条件为 truthy 时生效，可依赖 fixtures，同一个测试可同时挂多个注解），但适用场景不同（见 Annotations）：

• test.skip：标记测试为"不适用于当前配置"，Playwright 不运行该测试。适用于"这个测试在此环境下本就不该跑"。
• test.fixme：标记测试为待修复，与skip相对，Playwright 不运行它；文档建议当"运行该测试很慢或会崩溃"时使用fixme。
• test.fail：标记测试"应当失败"。Playwright 会运行该测试并确保它确实失败；如果测试没失败，Playwright 会报错。适用于承认某功能暂时坏了、先记录下来。

Test.skip的 API 参考还明确了一点边界：Skipped tests are not supposed to be ever run. If you intend to fix the test, useTest.fixmeinstead（见 Test API）。也就是说：环境本身不支持就用skip，测试还有修复计划就用fixme。

无条件跳过：test.skip(title, body)

某个测试在任何环境下都不该跑时，直接在声明处使用：

test.skip('skip this test', async ({ page }) => { // This test is not run });

Playwright 不会运行test.skip()调用之后的任何测试代码。

条件跳过单个测试：test.skip(condition, description)

主路径就是这一条：在测试体内，根据 fixture 判断当前环境是否适用，不适用就调用test.skip(condition, description)：

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

工作方式：条件为true时测试被标记为 skipped，Playwright 会在test.skip调用处立即中止该测试，不执行后续步骤；条件为false时测试正常跑完。第二个参数是跳过原因，会反映到测试报告中。文档建议在条件形式下始终传description。

条件里可用的就是测试 fixtures，除browserName外还有isMobile等。比如某个功能只在 WebKit 可用：

test('Safari-only test', async ({ page, browserName }) => { test.skip(browserName !== 'webkit', 'This feature is Safari-only'); // ... });

条件跳过整组或整个文件的测试：test.skip(callback, description)

同一文件里所有测试都不适用某环境时，不必逐个标注，在文件顶部（或test.describe组内）调用一次test.skip(callback, description)即可。callback 接收 fixtures，返回true时整个作用域被标记为 skipped：

import { test, expect } from '@playwright/test'; test.skip(({ browserName }) => browserName !== 'webkit', 'Safari-only'); test('Safari-only test 1', async ({ page }) => { // ... }); test('Safari-only test 2', async ({ page }) => { // ... });

写在test.describe组内时，组内所有测试和钩子都只在条件不成立的环境中运行：

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

fixme和fail也有完全对应的条件形式：test.fixme(callback, description)、test.fail(callback, description)，参数语义相同。

想让钩子也跳过：把 fixme 放进 beforeEach

条件注解放在beforeEach钩子内部，可以避免钩子本身在不适用环境中执行（见 Annotations）：

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

当isMobile为true时，测试在test.fixme处即被中止，page.goto不会执行（示例中的 URL 为文档示例值）。

运行时追加自定义注解（可选分支）

内置注解之外，测试运行中还可以往test.info().annotations里追加type和description，用于记录环境信息供报告展示：

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

注意：内置 HTML 报告会显示所有注解，但type以_开头的除外。自定义注解只用于补充上下文，不承担跳过逻辑。

运行并验证跳过是否生效

验证方式直接来自 Running and debugging tests：

npx playwright test

测试默认在 headless 模式下按playwright.config中配置的所有浏览器运行，结果输出到终端。确认跳过生效有两个检查点：

1. 被跳过的测试在对应浏览器项目中不执行（test.skip之后的代码不会运行），且标记为 skipped 而非 failed。
2. 用--project单独跑某个浏览器项目，确认条件只在目标环境触发：

npx playwright test --project firefox

跳过原因在 HTML 报告中可见。HTML 报告支持按浏览器、passed / failed / skipped / flaky 测试过滤；有失败时报告默认自动打开，否则手动打开：

npx playwright show-report

限制与边界

• skip的语义是"该测试不应再被运行"。如果跳过是因为环境暂时不支持、但测试本身计划修复，应改用test.fixme，文档给出了明确区分。
• test.fail与skip/fixme行为相反：它要求测试"确实失败"，测试通过反而报错，不要用它来表示"此环境不适用"。
• 条件形式下 Playwright 会"运行到注解调用处再中止"，所以test.skip之前的代码仍会执行；需要连前置操作一起省掉时，把条件注解放进beforeEach或改用test.skip(callback, description)作用在组级别。
• 同一测试可以挂多个注解（可能来自不同配置），互相独立生效。

完整参数与签名参见 Test.skip、Test.fixme 的 API 文档，注解与标签的整体机制参见 Annotations。

【免费下载链接】playwrightPlaywright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.项目地址: https://gitcode.com/GitHub_Trending/pl/playwright