🎭 Playwright

文档 | API 参考

Playwright 是一个用于 Web 自动化和测试的框架。它通过单一 API 驱动 Chromium、Firefox 和 WebKit——用于你的测试、脚本,以及作为 AI 代理的工具。

快速开始

选择适合你工作流程的路径:

Playwright Test

Playwright Test 是一个功能完整的测试运行器,专为端到端测试而构建。它能在 Chromium、Firefox 和 WebKit 上运行测试,并提供完整的浏览器隔离、自动等待和 Web 优先断言。

安装

npm init playwright@latest

或手动添加:

npm i -D @playwright/test
npx playwright install

编写测试

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

test('has title', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await expect(page).toHaveTitle(/Playwright/);
});

test('get started link', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await page.getByRole('link', { name: 'Get started' }).click();
  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

运行测试

npx playwright test

测试会在所有已配置的浏览器上并行运行,默认使用无头模式。每个测试都会获得全新的浏览器上下文——近乎零开销的完全隔离。

主要功能

自动等待与 Web 优先断言。 没有人为的超时。Playwright 会等待元素变为可操作,断言会自动重试,直到条件满足。

定位器。 使用富有弹性的定位器查找元素,这些定位器反映了用户查看页面的方式:

page.getByRole('button', { name: 'Submit' })
page.getByLabel('Email')
page.getByPlaceholder('Search...')
page.getByTestId('login-form')

测试隔离。 每个测试都在自己的浏览器上下文中运行——相当于一个全新的浏览器配置文件。保存一次身份验证状态,并在多个测试中复用:

// Save state after login
await page.context().storageState({ path: 'auth.json' });

// Reuse in other tests
test.use({ storageState: 'auth.json' });

追踪。 在失败时捕获执行轨迹、截图和视频。在 Trace Viewer 中检查每一个操作、DOM 快照、网络请求和控制台消息:

// playwright.config.ts
export default defineConfig({
  use: {
    trace: 'on-first-retry',
  },
});

npx playwright show-trace trace.zip

并行性。 默认情况下,测试会在所有已配置的浏览器上并行运行。

完整测试文档

Playwright CLI

Playwright CLI 是一个面向编码代理的浏览器自动化命令行界面。它比 MCP 更节省 token——命令可以避免将大型工具模式和可访问性树加载到模型上下文中。

安装

npm install -g @playwright/cli@latest

可选安装技能,以获得更丰富的代理集成:

playwright-cli install --skills

用法

将你的编码代理指向一个任务:

Test the "add todo" flow on https://demo.playwright.dev/todomvc using playwright-cli.
Take screenshots for all successful and failing scenarios.

或直接运行命令:

playwright-cli open https://demo.playwright.dev/todomvc/ --headed
playwright-cli type "Buy groceries"
playwright-cli press Enter
playwright-cli screenshot

会话监控

使用 playwright-cli show 打开一个可视化仪表盘,实时屏幕预览所有正在运行的浏览器会话。点击任意会话即可放大并进行远程控制。

playwright-cli show

完整 CLI 文档 | GitHub

Playwright MCP

Playwright MCP server 通过 Model Context Protocol 为 AI 代理提供完整的浏览器控制能力。代理使用结构化的可访问性快照与页面交互——无需视觉模型或截图。

设置

添加到你的 MCP 客户端(VS Code、Cursor、Claude Desktop、Windsurf 等):

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

VS Code 一键安装:

对于 Claude Code:

claude mcp add playwright npx @playwright/mcp@latest

工作原理

让 AI 助手与任意网页交互:

Navigate to https://demo.playwright.dev/todomvc and add a few todo items.

代理将页面视为结构化的可访问性树:

- heading "todos" [level=1]
- textbox "What needs to be done?" [ref=e5]
- listitem:
  - checkbox "Toggle Todo" [ref=e10]
  - text: "Buy groceries"

它使用像 e5、e10 这样的元素引用来点击、输入和交互——确定性高,且不存在视觉歧义。工具涵盖导航、表单填写、截图、网络模拟、存储管理等。

完整 MCP 文档 | GitHub

Playwright Library

将 playwright 作为库用于浏览器自动化脚本——网页抓取、PDF 生成、截图捕获,以及任何需要以编程方式控制浏览器但又不需要测试运行器的工作流程。

安装

npm i playwright

示例

截图:

import { chromium } from 'playwright';

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://playwright.dev/');
await page.screenshot({ path: 'screenshot.png' });
await browser.close();

生成 PDF:

import { chromium } from 'playwright';

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://playwright.dev/');
await page.pdf({ path: 'page.pdf', format: 'A4' });
await browser.close();

模拟移动设备:

import { chromium, devices } from 'playwright';

const browser = await chromium.launch();
const context = await browser.newContext(devices['iPhone 15']);
const page = await context.newPage();
await page.goto('https://playwright.dev/');
await page.screenshot({ path: 'mobile.png' });
await browser.close();

拦截网络请求:

import { chromium } from 'playwright';

const browser = await chromium.launch();
const page = await browser.newPage();
await page.route('**/*.{png,jpg,jpeg}', route => route.abort());
await page.goto('https://playwright.dev/');
await browser.close();

库文档 | API 参考

VS Code 扩展

Playwright VS Code 扩展将测试运行、调试和代码生成直接带入你的编辑器。

运行和调试测试 在编辑器中单击即可完成。通过实时浏览器视图设置断点、检查变量,并逐步执行测试。

使用 CodeGen 生成测试。 点击“记录新操作”打开浏览器——在 Playwright 为你编写测试代码的同时,导航并操作你的应用。

选择定位器。 将鼠标悬停在浏览器中的任意元素上,即可看到最佳可用定位器,然后点击即可将其复制到剪贴板。

Trace Viewer 集成。 在侧边栏中启用“Show Trace Viewer”,即可在每次测试运行后获得完整的执行轨迹——每一步的 DOM 快照、网络请求、控制台日志和截图。

安装扩展 | VS Code 指南

跨浏览器支持

所有平台均支持无头和有头执行。¹ 默认使用 Chrome for Testing。

其他语言

Playwright 还提供 Python、.NET 和 Java 版本。

Playwright Test	端到端测试	`npm init playwright@latest`
Playwright CLI	编码代理(Claude Code、Copilot)	`npm i -g @playwright/cli@latest`
Playwright MCP	AI 代理和 LLM 驱动的自动化	`npx @playwright/mcp@latest`
Playwright Library	浏览器自动化脚本	`npm i playwright`
VS Code 扩展	在 VS Code 中编写和调试测试	从 Marketplace 安装

Chromium¹ 152.0.7977.54	✅	✅	✅
WebKit 26.5	✅	✅	✅
Firefox 153.0	✅	✅	✅

playwright

最受欢迎