Playwright 扩展与迁移

本章介绍 Playwright 生态的扩展功能，包括 Library 脚本模式、MCP 服务、Test Agents，以及从其他框架迁移到 Playwright 的指南。

---

Playwright Library 脚本模式

Playwright Library 是单独的浏览器自动化库，适用于测试运行器之外的场景。

安装

npm i playwright

典型用法

实例

// 截图脚本

import { chromium } from 'playwright';

(async () => {

  const browser = await chromium.launch({ headless: true });

  const page = await browser.newPage();

  await page.goto('https://www.runoob.com/');

  await page.screenshot({ path: 'runoob.png', fullPage: true });

  await browser.close();

  console.log('截图已保存到 runoob.png');

})();

PDF 生成

实例

import { chromium } from 'playwright';

(async () => {

  const browser = await chromium.launch();

  const page = await browser.newPage();

  await page.goto('https://www.runoob.com/');

  // 生成 PDF（仅 Chromium 支持）

  await page.pdf({

    path: 'runoob.pdf',

    format: 'A4',

    margin: { top: '20px', bottom: '20px' },

  });

  await browser.close();

})();

Library 模式 vs Test Runner 的选择

场景	推荐
编写 E2E 测试	Playwright Test Runner
网页截图、生成 PDF	Playwright Library
网页数据抓取	Playwright Library
一次性自动化脚本	Playwright Library

---

Playwright MCP 简介

Playwright MCP（Model Context Protocol）服务器让 AI 助手可以直接控制浏览器。

MCP 安装与配置

# 为 Claude Code 添加 Playwright MCP
claude mcp add playwright npx @playwright/mcp@latest

在 VS Code 或其他 MCP 客户端中配置：

实例

{

  "mcpServers": {

    "playwright": {

      "command": "npx",

      "args": ["@playwright/mcp@latest"]

    }

  }

}

MCP 的工作方式

AI Agent 通过结构化的可访问性快照（Accessibility Snapshot）来感知页面内容。

每条可访问性信息有一个 ref 标识，Agent 通过这个 ref 来进行点击、输入等操作。

这种方式不需要截图，完全基于结构化数据交互，速度快且确定性高。

---

Playwright Test Agents

Test Agents 是实验性的 AI 驱动测试工具，可以自动生成和修复测试。

Agent	功能	触发方式
Planner	自动探索应用，生成 Markdown 测试计划	LLM Agent 驱动
Generator	将测试计划转为 Playwright 测试代码	LLM Agent 驱动
Healer	执行测试套件，自动修复失败的测试	LLM Agent 驱动

初始化 Test Agents：

# 为 VS Code 初始化
npx playwright init-agents --loop=vscode

# 为 Claude Code 初始化
npx playwright init-agents --loop=claude

---

组件测试概览（实验性）

Playwright 支持直接挂载和测试 React/Vue 组件，无需完整的页面环境。

实例

test('按钮组件测试', async ({ mount }) => {

  // 挂载 React 组件

  const component = await mount(

    <Button title="提交" />

  );

  // 断言组件显示的文本

  await expect(component).toContainText('提交');

  // 点击按钮

  await component.click();

});

---

无障碍测试

Playwright 提供了无障碍名称和描述的断言，帮助验证页面的可访问性。

实例

// 验证元素有正确的无障碍名称

await expect(page.getByRole('button'))

  .toHaveAccessibleName('提交表单');

// 验证元素有无障碍描述

await expect(page.getByLabel('用户名'))

  .toHaveAccessibleDescription('请输入 4-16 位字母数字组合');

---

从其他框架迁移

从 Puppeteer 迁移

Playwright 与 Puppeteer 共享 Chrome DevTools Protocol 的能力，迁移相对简单。

Puppeteer	Playwright
puppeteer.launch()	chromium.launch()
page.waitForSelector()	不需要（自动等待）或 page.locator()
page.$(selector)	page.locator(selector)
page.evaluate()	page.evaluate()（相同）
page.setRequestInterception()	page.route()

从 Cypress 迁移

Playwright 的 Locator 理念与 Cypress 的查询链类似，但有一些关键差异：

Cypress	Playwright
cy.get('.class')	page.locator('.class')
cy.contains('text')	page.getByText('text')
cy.get('[data-cy="btn"]')	page.getByTestId('btn')（配合 testIdAttribute: 'data-cy'）
cy.intercept()	page.route()
cy.wait()	不需要（自动等待）

从 Selenium 迁移

Selenium 使用 WebDriver 协议，Playwright 直接控制浏览器协议，API 风格差异较大。

Selenium	Playwright
driver.findElement(By.id('x'))	page.locator('#x')
driver.get(url)	page.goto(url)
element.click()	locator.click()
WebDriverWait	不需要（内置自动等待）
new RemoteWebDriver()	chromium.connect(url)

迁移建议：不要试图一步完成所有测试的迁移。

先选择一两个核心功能的测试用 Playwright 重写，验证通过后再逐步迁移其余测试。

AI 思考中...

Playwright 最佳实践

Playwright 核心类 API