适用场景

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

当静态 fetch 无法满足需求，或任务依赖于浏览器事件、可见 DOM 状态、认证上下文、上传/下载行为、或面向用户的内容渲染时，优先选用本技能。

若用户主要希望智能体通过简单操作（如 navigate、click、fill、screenshot、download 或 extract）来驱动浏览器，请将 MCP 视为首选路径。

编写脚本和测试时请直接使用 Playwright；当浏览器工具已集成至当前工作流、用户明确要求使用 MCP，或浏览器操作比编写新自动化代码更快捷时，则选用 MCP。

本技能的核心适用场景是仓库自有（repo-owned）的浏览器相关工作：测试、调试、问题复现、截图及确定性自动化。将“已渲染页面的数据提取”视为次要用例，而非默认定位。

架构设计

该技能仅接受指令，不默认创建本地内存、不自动建立文件夹结构、也不持久化浏览器配置文件。

仅加载完成任务所需的最小参考文件。除非仓库已有标准化的认证状态管理机制，且用户明确要求复用浏览器会话，否则应保持认证状态为临时性。

快速入门

MCP 浏览器路径

npx @playwright/mcp --headless

当智能体已具备可用的浏览器工具，或用户希望实现浏览器自动化而无需编写新的 Playwright 代码时，采用此路径。

常用 MCP 操作

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

• browser_navigate：打开页面
• browser_click 和 browser_press：交互操作
• browser_type 和 browser_select_option：表单输入与选项选择
• browser_snapshot 和 browser_evaluate：页面检查与数据提取
• browser_choose_file：文件上传
• 通过当前活跃的浏览器工作流完成截图、PDF、trace 及下载捕获

常见浏览器任务结果

现有测试套件

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 测试框架、配置与 fixture，而非从零构建一套并行测试体系。
• 除非测试套件明确设计为支持共享状态，否则禁止在并行运行间共享可变账号、浏览器状态或服务端数据。

3. 行动前先侦察

• 在锁定选择器或断言前，先打开页面、等待并检查已渲染的状态。
• 使用 codegen、headed 模式或 trace 来发现稳定定位符，而非基于源码或过期 DOM 猜测。
• 对于偶发性失败或仅在 CI 中出现的问题，应在重写选择器或等待逻辑前先捕获 trace。

4. 优先使用高韧性定位符与面向 Web 的断言

• 优先使用 role、label、text、alt 文本、title 或 test ID，其次才是 CSS 选择器或 XPath。
• 使用 Playwright 断言验证用户可见的结果，而非仅确认 click 或 fill 命令是否执行成功。
• 若定位符存在歧义，请明确消歧；除非位置本身即为被测行为，否则不应使用 first()、last() 或 nth() 来压制严格性警告。

5. 基于可交互性与应用状态等待，而非任意时间延迟

• 在引入 sleep 或强制操作前，优先利用 Playwright 内置的可交互性检查机制。
• 相比泛化的定时猜测，优先使用 expect、URL 等待、响应等待及显式的应用就绪信号。

6. 控制你未拥有的外部依赖

• 当目标是验证自身应用时，应 Mock 或隔离第三方服务、不稳定的上游 API、分析埋点噪声及跨域依赖。
• 对于已渲染页面的数据提取，应优先使用有文档支持的 API 或纯 HTTP 接口，而非驱动完整浏览器。
• 除非用户明确要求验证该集成本身，否则不应让第三方小部件或上游集成成为测试套件不稳定的根本原因。

7. 显式管理认证、生产环境访问与状态持久化

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

Playwright 常见陷阱

• 从源码猜测选择器，或使用 first()、last()、nth() 抑制歧义警告 → 自动化仅能成功一次，随后即出现不稳定（flake）。
• 在仓库已存在配置、fixture、认证设置或约定的情况下，另行新建 Playwright 结构 → 新流程与现有测试框架冲突，徒耗时间。
• 测试内部实现细节而非用户可见结果 → 测试套件全部通过，但用户实际路径仍不可用。
• 在并行测试间共享同一认证状态，且这些测试会变更服务端数据 → 失败变为顺序依赖型，结果难以信任。
• 在尚未理解遮罩层、禁用状态或可交互性前提下即启用 force: true → 测试掩盖了真实缺陷。
• 对高频通信的单页应用（SPA）使用 networkidle 等待 → 分析埋点、轮询请求或 WebSocket 连接会使页面持续处于“忙碌”状态，即使 UI 已准备就绪。
• 本可通过 HTTP 或 API 解决问题，却仍驱动完整浏览器 → 成本更高、更不稳定、有效信号更少。
• 将第三方小部件与实时上游服务视作自身产品中稳定的一部分 → 故障变得不可归因、不可修复。

外部端点

除此之外，不向任何其他外部服务发送数据。

安全与隐私

离开您设备的数据：

• 发送至用户指定需自动化的网站的请求。
• 安装 Playwright 工具时可选的 npm 包下载流量。

保留在本地的数据：

• 源代码、trace、截图、视频、PDF 及暂存于 workspace 或系统临时目录中的浏览器状态。

本技能不会：

• 创建隐藏内存文件或本地文件夹系统。
• 推荐浏览器指纹伪造技巧、验证码破解服务或代理出口轮换方案。
• 默认持久化会话或凭据。
• 在任务目标站点及可选工具安装之外发起未声明的网络请求。
• 将高风险的生产环境操作流程视为默认安全，不经用户明确指示即自动执行。

可信度说明

使用本技能时，浏览器请求将发送至您所指定的自动化目标网站，可选的包下载则经由 npm 完成。仅当您信任这些服务及工作流中涉及的网站时，才应安装并使用本技能。

相关技能

若用户确认，可通过 clawhub install 安装以下技能：

• web —— 在升级至真实浏览器前，优先采用 HTTP 方式开展初步调查。
• scrape —— 当浏览器自动化并非主要挑战时，适用于更广泛的提取类工作流。
• screenshots —— 浏览器操作完成后，用于捕获并优化视觉产物。
• multi-engine-web-search —— 在自动化前，用于查找并筛选目标页面。

反馈

• 若本技能有用：clawhub star playwright
• 保持更新：clawhub sync