机器翻译正文由机器翻译自项目原始文档（英文），排版经程序统一处理，可能存在偏差，请以原项目仓库为准。

🎭 剧作家

文档 | API 参考

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

入门

选择适合您工作流程的路径：

Playwright 测试

Playwright Test 是一个功能齐全的测试运行器，用于端到端测试。它可以在 Chromium、Firefox 和 WebKit 上运行测试，具有完整的浏览器隔离、自动等待和以网络为中心的断言。

安装

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

测试在所有已配置的浏览器中并行运行，默认情况下以无头模式运行。每个测试都会获得一个全新的浏览器上下文——完全隔离且开销几乎为零。

关键功能

自动等待和以网页为先的断言。 无需人为超时。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 命令行工具

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

安装

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

剧作家 MCP

剧作家 MCP 服务器通过模型上下文协议为 AI 代理提供完整的浏览器控制。代理通过结构化的辅助功能快照与页面交互——无需视觉模型或截图。

设置

添加到您的 MCP 客户端（VS Code、Cursor、Claude Desktop、Windsurf 等）：

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

VS Code 一键安装：

用于 Claude 代码：

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 库

将 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 集成。 在侧边栏启用“显示 Trace Viewer”，在每次测试运行后获取完整的执行追踪——包括每一步的 DOM 快照、网络请求、控制台日志和截图。

安装扩展 | VS Code 指南

跨浏览器支持

156.0.8078.4

| :white_check_mark: | :white_check_mark: | :white_check_mark: |
| WebKit

26.6

| :白色对勾: | :白色对勾: | :白色对勾: |
| 火狐

157.0

| :白色对勾: | :白色对勾: | :白色对勾: |

在所有平台上进行无头和有头执行。¹ 默认使用 Chrome for Testing。

其他语言

Playwright 也可用于 Python、.NET 和 Java。

资源

• 文档
• API参考
• MCP 服务器
• 用于编码代理的命令行界面
• VS Code 扩展
• 贡献指南
• 更新日志
• Discord