playwright

🎭 Playwright

文档 | API 参考

Playwright 是一个用于 Web 自动化和测试的框架。它通过统一的 API 驱动 Chromium、Firefox 和 WebKit，可用于测试、脚本以及作为 AI Agent 的工具。

开始使用

选择适合你工作流的方式：

	适用场景	安装
Playwright Test	端到端测试	npm init playwright@latest
Playwright CLI	编码 Agent（Claude Code、Copilot）	npm i -g @playwright/cli@latest
Playwright MCP	AI Agent 和由大模型驱动的自动化	npx @playwright/mcp@latest
Playwright Library	浏览器自动化脚本	npm i playwright
VS Code Extension	在 VS Code 中编写和调试测试	从 Marketplace 安装

---

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

跟踪记录。 在失败时捕获执行跟踪记录、屏幕截图和视频。在跟踪查看器中检查每项操作、DOM 快照、网络请求和控制台消息：

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

npx playwright show-trace trace.zip

并行运行。 测试默认会在所有已配置的浏览器中并行运行。

完整的测试文档

---

Playwright CLI

Playwright CLI 是一款面向编码 Agent 的浏览器自动化命令行界面。与 MCP 相比，它使用的令牌更少，因为命令无需将大型工具架构和无障碍树加载到模型上下文中。

安装

npm install -g @playwright/cli@latest

也可以安装 skills，以增强 Agent 集成：

playwright-cli install --skills

使用方法

向编码 Agent 提出任务：

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 服务通过模型上下文协议为 AI Agent 提供完整的浏览器控制能力。Agent 使用结构化的无障碍快照与页面交互，无需视觉模型或屏幕截图。

设置

添加到你的 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.

Agent 会以结构化无障碍树的形式查看页面：

- 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 库

将 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 生成测试。**单击“Record new”以打开浏览器，在应用中导航和交互，Playwright 会为你编写测试代码。

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

**集成 Trace Viewer。**在侧边栏中启用“Show Trace Viewer”，即可在每次测试运行后查看完整的执行跟踪，包括每一步的 DOM 快照、网络请求、控制台日志和屏幕截图。

安装扩展 | VS Code 指南

---

跨浏览器支持

	Linux	macOS	Windows
Chromium1 157.0.8103.15	:white_check_mark:	:white_check_mark:	:white_check_mark:
WebKit 27.2	:white_check_mark:	:white_check_mark:	:white_check_mark:
Firefox 158.0	:white_check_mark:	:white_check_mark:	:white_check_mark:

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

其他语言

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

资源

• 文档
• API 参考
• MCP 服务
• 编码 Agent 命令行工具
• VS Code 扩展
• 贡献指南
• 更新日志
• Discord