Playwright (Automation + MCP + Scraper)

何时使用

此技能适用于真实的浏览器任务：JS渲染的页面、多步骤表单、截图或PDF、UI调试、Playwright测试编写、MCP驱动的浏览器控制，以及从渲染页面中提取结构化数据。

当静态抓取不足时，或者当任务依赖于浏览器事件、可见的DOM状态、认证上下文、上传或下载、或面向用户的渲染时，优先使用此技能。

如果用户主要希望代理通过导航、点击、填写、截图、下载或提取等简单操作来驱动浏览器，请将MCP视为首选路径。

对于脚本和测试，直接使用Playwright。当浏览器工具已在流程中、用户明确需要MCP，或者最快路径是浏览器操作而非编写新的自动化代码时，请使用MCP。

主要适用于仓库拥有的浏览器工作：测试、调试、重现、截图和确定性自动化。将渲染页面提取视为次要用例，而非默认身份。

架构

此技能仅提供指令。默认情况下，它不会创建本地内存、设置文件夹或持久性配置文件。

仅加载任务所需的最小参考文件。除非仓库已将其标准化且用户明确希望复用浏览器会话，否则请保持认证状态为临时状态。

快速开始

MCP浏览器路径

npx @playwright/mcp --headless

当代理已具备可用的浏览器工具，或者用户希望在不编写新的Playwright代码的情况下进行浏览器自动化时，请使用此路径。

常见的MCP操作

典型的Playwright MCP工具操作包括：

• browser_navigate用于打开页面
• browser_click和browser_press用于交互
• 浏览器类型以及浏览器选择选项用于表单
• 浏览器快照和浏览器评估用于检查和提取
• 浏览器选择文件用于上传
• 通过活跃的浏览器工作流进行截图、PDF生成、跟踪和下载捕获

常见的浏览器操作结果

现有测试套件

npx playwright test
npx playwright test --headed
npx playwright test --trace on

引导选择器和流程

npx playwright codegen https://example.com

直接脚本路径

const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch({ headless: true });
  const page = await browser.newPage();
  await page.goto('https://example.com');
  await page.screenshot({ path: 'page.png', fullPage: true });
  await browser.close();
})();

快速参考

方法选择

追踪记录和产物比新代码更重要

核心规则

• 1. 测试用户可见行为和真实浏览器边界
• 不要将 Playwright 浪费在单元测试或 API 测试能以更低成本覆盖的实现细节上。

当成功依赖于渲染的 UI、可操作性、身份验证、上传或下载、导航，或仅浏览器行为时，使用 Playwright。

• 2. 先确保运行隔离，再追求巧妙
• 保持测试和脚本独立，以便重试、并行和重新运行不会继承隐藏状态。
• 在从头发明并行测试架构之前，先扩展仓库现有的 Playwright 工具、配置和固定装置。

除非测试套件明确为此设计，否则不要在并行运行之间共享可变账户、浏览器状态或服务器端数据。

• 3. 行动前先侦察
• 在锁定选择器或断言之前，先打开、等待并检查渲染状态。使用代码生成
• 、有头模式或追踪记录来发现稳定的定位器，而不是基于源代码或过时的 DOM 进行猜测。

4. 优先使用稳健的定位器和面向Web的断言

• 在CSS或XPath之前，优先使用角色、标签、文本、替代文本、标题或测试ID。
• 使用Playwright断言来验证用户可见的结果，而不仅仅是检查点击或填充命令是否已执行。
• 如果定位器存在歧义，请消除歧义。不要通过使用first()、last()或nth()来掩盖严格性要求，除非位置本身就是被测试的实际行为。

5. 等待可操作性和应用状态，而非任意时间

• 在求助于休眠或强制操作之前，先让Playwright的可操作性检查为你工作。
• 优先使用expect、URL等待、响应等待以及明确的应用就绪信号，而非通用的时间猜测。

6. 控制你无法掌控的部分

• 当目标是验证你的应用时，对第三方服务、不稳定的上游API、分析噪音和跨域依赖进行模拟或隔离。
• 对于渲染提取，在驱动完整浏览器之前，优先使用有文档记录的API或纯HTTP路径。
• 不要让实时的第三方小部件或上游集成成为你的测试套件不稳定的原因，除非该特定集成正是用户要求验证的内容。

7. 保持认证、生产环境访问和持久化的明确性

• 默认情况下不要持久化保存的浏览器状态。
• 仅在仓库已将其标准化或用户明确要求会话复用时，才复用认证状态。
• 对于具有破坏性、涉及财务、医疗、生产或其他高风险的操作流程，应优先使用预发布环境或本地环境，并在继续操作前要求用户明确确认。

Playwright 的常见陷阱 通过猜测源代码中的选择器，或使用

• first()、last()或nth()来消除歧义 -> 自动化操作可能仅成功一次，随后变得不稳定。当仓库已存在配置、固件、身份验证设置或约定时，仍创建新的 Playwright 结构 -> 新流程会与现有框架冲突，浪费时间。
• 测试内部实现细节而非可见结果 -> 测试套件通过，但用户路径仍然存在问题。
• 在并行测试中共享一个已认证的状态，而这些测试会修改服务器端数据 -> 失败变得依赖于执行顺序，难以信赖。
• 在不理解覆盖层、禁用状态或可操作性之前就使用
• force: true-> 测试会掩盖真正的缺陷。在交互式单页应用（SPA）中等待
• networkidle-> 分析、轮询或套接字连接会使页面保持“繁忙”状态，即使界面已准备就绪。当 HTTP 或 API 可以解决问题时，仍启动完整浏览器 -> 成本更高，更不稳定，信号更少。
• 将第三方小部件和实时上游服务视为自己产品的稳定组成部分 -> 失败变得无法操作。
• 外部端点

端点

其他数据不会发送至外部。

安全与隐私

离开您设备的数据：

• 发送至用户要求自动化的网站请求。
• 安装Playwright工具时，向npm发送的可选软件包安装流量。

保留在本地设备的数据：

• 源代码、追踪记录、截图、视频、PDF以及保存在工作区或系统临时目录中的临时浏览器状态。

此技能**不会**：

• 创建隐藏的内存文件或本地文件夹系统。
• 推荐浏览器指纹伪装、验证码破解服务或轮转出口节点。
• 默认情况下持久化会话或凭证。
• 在任务涉及的目标网站和可选工具安装之外，进行未声明的网络请求。
• 在未经用户明确指示的情况下，将高风险生产流程视为可安全自动化。

信任

使用此技能时，浏览器请求将发往您自动化的网站，而可选的软件包下载将通过npm进行。 仅当您信任这些服务及工作流中涉及的网站时，再进行安装。

相关技能

安装方式clawhub install <slug>若用户确认：

• web- 在升级到真实浏览器之前，优先进行HTTP层面的调查。
• scrape- 当浏览器自动化并非主要挑战时，用于更广泛的提取工作流。
• screenshots- 在浏览器操作完成后，捕获并优化视觉成果。
• multi-engine-web-search- 在自动化处理前，查找并筛选目标页面。

反馈

• 若觉得有用：clawhub star playwright
• 保持更新：clawhub sync