用途
playwright-skill 是一个通用型浏览器自动化技能，基于 Playwright 实现。用户描述想要测试或自动化的内容后，该技能会编写自定义 Playwright 代码并执行，适用于页面测试、表单填写、截图、响应式检查、登录流程验证、失效链接检查等浏览器任务。它不局限于预置脚本，理论上可完成任意浏览器自动化任务。
主要能力
- 自动检测本地开发服务器：对 localhost 测试，会先运行 detectDevServers() 检测运行中的服务器。若发现 1 个则自动使用并告知用户；若发现多个则询问用户选择；若未发现则询问 URL 或协助启动开发服务器。
- 编写并执行自定义脚本：根据用户请求编写 Playwright 代码，脚本写入系统临时目录（如 /tmp/playwright-test-*.js），不污染项目目录，由操作系统自动清理。
- 默认可见浏览器：除非用户明确要求无头模式，否则使用 headless: false，便于实时观察与调试。
- URL 参数化：脚本顶部以 TARGET_URL 常量或环境变量方式配置目标地址。
- 常见模式支持：多视口响应式测试、登录流程测试、表单填写与提交、失效链接检查、带错误处理的截图、响应式设计测试等。
- 内联执行：简单一次性任务（如快速截图、检查元素是否存在、获取页面标题）可直接内联执行，无需创建文件。
- 辅助函数：lib/helpers.js 提供 detectDevServers、safeClick、safeType、takeScreenshot、handleCookieBanner、extractTableData 等工具。
- 自定义 HTTP 头：可通过环境变量为所有请求配置自定义头，用于标识自动化流量、获取 LLM 优化响应或全局添加认证令牌。
使用方式
首次安装：进入技能目录后运行 cd $SKILL_DIR && npm run setup，安装 Playwright 与 Chromium 浏览器，仅需一次。
执行流程：
- 检测开发服务器（本地测试时）：
cd $SKILL_DIR && node -e "require('./lib/helpers').detectDevServers().then(servers => console.log(JSON.stringify(servers)))" - 将测试脚本写入临时目录，例如 /tmp/playwright-test-page.js，并在脚本顶部设置 TARGET_URL。
- 从技能目录执行：
cd $SKILL_DIR && node run.js /tmp/playwright-test-page.js
内联执行示例：cd $SKILL_DIR && node run.js "..."，适用于快速一次性任务。
自定义 HTTP 头配置：
- 单个头：
PW_HEADER_NAME=X-Automated-By PW_HEADER_VALUE=playwright-skill cd $SKILL_DIR && node run.js /tmp/my-script.js - 多个头（JSON）：
PW_EXTRA_HEADERS='{"X-Automated-By":"playwright-skill","X-Debug":"true"}' cd $SKILL_DIR && node run.js /tmp/my-script.js
路径解析：该技能可安装在不同位置（插件系统、手动全局安装、项目级安装）。执行命令前需根据加载 SKILL.md 的位置确定技能目录，并将命令中的 $SKILL_DIR 替换为实际路径。常见路径包括：插件系统 ~/.claude/plugins/marketplaces/playwright-skill/skills/playwright-skill；手动全局 ~/.claude/skills/playwright-skill；项目级 <project>/.claude/skills/playwright-skill。
适用场景
- 测试页面在桌面、平板、移动等多种视口下的表现并截图。
- 验证登录流程是否正确跳转。
- 填写并提交表单，验证提交结果。
- 检查页面中的失效链接。
- 带错误处理地截取整页截图。
- 需要向本地后端标识自动化流量或全局添加请求头的场景。
限制与注意事项
- 首次使用必须运行 npm run setup 安装 Playwright 与 Chromium。
- 脚本应写入系统临时目录，不应写入技能目录或用户项目目录。
- 默认使用可见浏览器；仅在用户明确要求无头或后台执行时才使用 headless: true。
- 建议使用 waitForURL、locator().waitFor() 或 waitForLoadState 等等待策略，而非固定超时；waitForSelector 已被软弃用，推荐基于 locator 的等待。
- 建议使用 try-catch 进行健壮的错误处理。
- 若出现模块未找到错误，需确保通过 run.js 包装器从技能目录运行。
- 若浏览器未打开，需检查 headless: false 并确保有可用显示环境。
- 高级功能（选择器最佳实践、网络拦截与 API 模拟、认证与会话管理、视觉回归测试、移动设备模拟、性能测试、调试技巧、CI/CD 集成）参见 API_REFERENCE.md，该文件仅在需要高级功能时加载。
- 关于收费、价格、平台支持范围等具体信息，资料中暂未提供。