Playwright 是 Microsoft 开发的自动化测试框架，相比 Puppeteer 支持多浏览器（Chrome/Firefox/Safari），并提供了更完善的调试体验。
2024-2026 更新：Playwright v1.61+ 支持更强大的 Trace Viewer 和 VSCode 扩展：UI Mode / Trace Viewer 可在浏览器标签页中打开（
--ui-port 0，v1.35+ 起支持）、新增on-all-retries等 Trace 录制模式。
# 方式一：命令行
npx playwright test --debug
# 方式二：只调试某个测试
npx playwright test example.spec.ts --debug
# 方式三：在代码中使用
await page.pause();Playwright Inspector 是一个独立的调试窗口，提供以下功能：
// example.spec.ts
import { test, expect } from '@playwright/test';
test('login flow', async ({ page }) => {
await page.goto('https://example.com/login');
// 在此处暂停，打开 Inspector
await page.pause();
await page.fill('#username', 'admin');
await page.fill('#password', 'password');
await page.click('#login-button');
await expect(page).toHaveURL(/dashboard/);
});Trace Viewer 是 Playwright 最强大的调试工具，可以录制测试的每一步，此后回放查看。相比 Puppeteer 只能通过截图和 console 日志调试，Playwright 的 Trace Viewer 提供了完整的回放能力。
# 方式一：命令行录制
npx playwright test --trace on
# 方式二：配置文件
# playwright.config.ts// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
trace: 'on-first-retry', // 仅在重试时录制（推荐）
// trace: 'on', // 始终录制
// trace: 'off', // 不录制
// trace: 'retain-on-failure', // 失败时保留
// trace: 'on-all-retries', // 每次重试都录制（v1.49+）
// trace: 'retain-on-first-failure', // 首次失败时保留（v1.49+）
// trace: 'retain-on-failure-and-retries', // 失败及重试时保留（v1.49+）
},
});# 查看录制的 Trace
npx playwright show-trace trace.zip
# 在浏览器标签页中打开（不占用终端）
npx playwright show-trace --port 0 trace.zip
# 或在 CI 中上传 Trace
npx playwright show-trace https://trace.server/trace.zip2024-2026 新增：
show-trace --port 0会在浏览器标签页中打开 Trace Viewer，并自动选择一个可用端口；同理，UI Mode 也支持npx playwright test --ui-port 0在标签页中打开（v1.35+），在 Docker / Codespaces 等容器环境中还可通过--ui-host=0.0.0.0暴露访问地址。
Trace 文件包含以下数据：
| 数据 | 说明 |
|---|---|
| Actions | 每个 Playwright 操作（click、fill、navigate 等） |
| Snapshots | 每步操作后的 DOM 快照 |
| Network | 所有网络请求和响应 |
| Console | 所有 console 输出 |
| Screenshots | 每步操作后的截图 |
| Metadata | 浏览器版本、视口大小、测试名称等 |
Playwright Codegen 可以录制浏览器操作并生成测试代码：
# 启动录制
npx playwright codegen https://example.com
# 指定浏览器
npx playwright codegen --browser=firefox https://example.com
# 指定设备和视口
npx playwright codegen --device="iPhone 14 Pro" https://example.comimport { test, expect } from '@playwright/test';
test('test', async ({ page }) => {
await page.goto('https://example.com/');
await page.getByRole('link', { name: 'Login' }).click();
await page.getByLabel('Username').fill('admin');
await page.getByLabel('Password').fill('password');
await page.getByRole('button', { name: 'Sign in' }).click();
await expect(page.getByText('Welcome')).toBeVisible();
});Playwright 提供了 VSCode 扩展，可以在 IDE 内直接运行和调试测试：
ms-playwright.playwright| 功能 | 说明 |
|---|---|
| 运行测试 | 点击 ▶ 运行单个测试 |
| 调试测试 | 设置断点，逐步执行 |
| 查看 Trace | 测试失败后自动打开 Trace Viewer |
| 录制测试 | 点击录制按钮，打开 Codegen |
| 选择器查看 | 悬停在代码上查看对应元素 |
| 方面 | Puppeteer | Playwright |
|---|---|---|
| 调试模式 | 无内置 | --debug / page.pause() |
| 回放分析 | 无 | Trace Viewer |
| 录制生成代码 | 第三方工具 | 内置 Codegen |
| VSCode 集成 | 手动配置 | 官方扩展 |
| 自动等待 | 需手动 waitForSelector | 自动等待 |
| 多浏览器 | Chrome / Firefox（v23 起官方支持） | Chrome / Firefox / Safari |
--trace on-first-retry// playwright.config.ts
export default defineConfig({
use: {
trace: 'on-first-retry', // 仅重试时录制，节省资源
},
});page.pause()test('complex flow', async ({ page }) => {
await page.goto('/');
// 复杂操作前暂停调试
await page.pause();
await page.click('#complex-button');
});2024-2026 补充：视频录制与 Trace 支持同一套触发模式（
on/off/retain-on-failure/on-all-retries等），可在use.video中配置，配合 Trace 实现完整的失败回放。
test.afterEach(async ({ page }, testInfo) => {
if (testInfo.status !== testInfo.expectedStatus) {
await page.screenshot({
path: `test-results/${testInfo.title}-failure.png`,
});
}
});# GitHub Actions
- name: Run Playwright tests
run: npx playwright test --trace on
- name: Upload Trace on failure
if: failure()
uses: actions/upload-artifact@v4
with:
name: playwright-traces
path: test-results/