5. 测试运行器 Playwright Test 概览

装好之后，你实际在用什么

第 2 章我们跑过 npm init playwright@latest。那个命令装上的核心包叫 @playwright/test。

它和另一个包 playwright 是两回事，很多人会搞混。

• playwright 是裸库（Library），只管驱动浏览器。
• @playwright/test 是测试运行器（Test Runner），在裸库之上又包了一整套测试能力。

日常写端到端（E2E）测试，用的就是 @playwright/test。本教程后面所有例子都基于它。

Playwright Test 的三件套

理解这三块，就理解了 Playwright Test 的骨架。

第一块：test 函数

test() 是写用例的入口。第一个参数是用例名，第二个是测试函数。

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

test('首页能打开', async ({ page }) => {
  await page.goto('/'); // 这里的 '/' 依赖配置里的 baseURL，见第 6 章
  await expect(page).toHaveTitle(/Playwright/);
});

注意测试函数里那个 { page }。它不是你手动创建的，而是运行器按需注入的。这种「用的时候才给你准备好」的机制，叫 Fixture（夹具）。

第二块：expect 断言

expect() 是 Playwright 的断言（Assertion，即判断结果是否符合预期）写法。它和裸库最大的不同，是它带自动重试。

// Playwright Test 的写法（推荐）
await expect(page.getByText('欢迎')).toBeVisible();

它会在默认 5 秒内反复检查。元素晚一两秒出现也等得到，不会一上来就报错。这就是 Web 优先断言（Web-First Assertions） 的核心优势。

第三块：配置文件

playwright.config.ts 管全局设置。超时、用哪几个浏览器、基础地址、失败录屏，都在这里写一次，全项目共用。

这块下一章会专门拆开讲。

对比裸库：差别到底在哪

下面两段做同一件事：打开页面、确认标题含 “Example”。

裸库写法：

import { chromium } from 'playwright';
import assert from 'node:assert';

(async () => {
  const browser = await chromium.launch();
  const context = await browser.newContext();
  const page = await context.newPage();
  await page.goto('https://example.com/');
  assert((await page.title()) === 'Example Domain'); // 一次性判断，不重试
  await context.close();
  await browser.close();
})();

Test 写法：

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

test('标题正确', async ({ page }) => {
  await page.goto('https://example.com/');
  await expect(page).toHaveTitle(/Example/);
});

差别一目了然：

• 裸库要自己 launch、newContext、newPage、close，四步都得手写。
• Test 模式里 page 直接由夹具给好，用完自动回收。
• 裸库用 Node 的 assert，不重试；Test 用 expect，自动等待。
• 裸库用 node 脚本.js 跑；Test 用 npx playwright test 跑，自带发现用例、并发、报告。

Test 还顺手给了什么

运行器不只是「能跑」。它额外附带这些能力，都是裸库没有的：

• 配置矩阵与项目：一份用例，同时跑在 Chromium、Firefox、WebKit 上。
• 并发：多用例同时跑，省时间。
• 重试：CI 上失败自动再跑一次。
• 报告：HTML 报告、JUnit 报告开箱即用。
• 追踪：失败自动留痕，配合 Trace Viewer 回看。

这些后面都会分别讲到。这一章你只要记住：写端到端测试，认准 @playwright/test，认准 test + expect + 配置这三件套。

小结

Playwright Test = 裸库 + 运行器。test 组织用例，expect 做可重试断言，配置文件管全局。

比起裸库，你不用再手动开关浏览器，也不用手写等待，并发、重试、报告都是现成的。

下一章，我们把配置文件这个「总开关」拆开看。