playwright-skill

详细功能介绍：

通用浏览器自动化技能。根据用户描述的需求编写自定义 Playwright 代码，通过统一执行器运行。支持开发服务器自动发现、可见浏览器调试、参数化 URL 配置，所有临时脚本自动写入 /tmp 避免污染项目目录。

核心工作流

四步强制流程：

1. 自动检测开发服务器 — 本地测试时首先运行：

cd $SKILL_DIR && node -e "require('./lib/helpers').detectDevServers().then(servers => console.log(JSON.stringify(servers)))"

• 发现 1 个服务器：自动使用并告知用户
• 发现多个服务器：询问用户选择
• 未发现服务器：询问 URL 或协助启动开发服务器

2. 脚本写入 /tmp — 所有测试文件写入 /tmp/playwright-test-*.js，绝不写入技能目录或用户项目
3. 默认可见浏览器 — 使用 headless: false 运行，除非用户明确要求无头模式
4. 参数化 URL — 通过环境变量或脚本顶部常量配置目标 URL

能力矩阵

任务类型	功能描述	典型场景
页面测试	加载页面、获取标题、截图保存	验证页面渲染、捕获 UI 状态
响应式检查	多视口测试（Desktop/Tablet/Mobile）	验证断点布局、跨设备兼容性
表单自动化	填写输入框、提交表单、验证结果	联系表单、注册流程、数据录入
登录验证	输入凭据、等待跳转、确认状态	身份验证、权限检查、会话管理
链接检查	遍历页面链接、检测 404/错误	断链扫描、外链有效性验证
截图捕获	全页/元素截图、带时间戳命名	视觉回归、文档插图、问题报告
UX 验证	元素存在性检查、交互流程测试	按钮可用性、弹窗行为、错误提示

常见模式

多视口响应式测试

自动切换 Desktop (1920×1080)、Tablet (768×1024)、Mobile (375×667) 三种尺寸，分别截图对比。

登录流程测试

填写邮箱密码 → 点击提交 → 等待 URL 跳转 → 验证目标页面加载成功。

表单提交验证

填写字段 → 提交 → 等待成功提示选择器出现 → 确认提交结果。

断链检测

遍历所有外链 → 发送 HEAD 请求 → 统计可用/失效链接，输出详细报告。

执行方式

文件模式（复杂任务）：

cd $SKILL_DIR && node run.js /tmp/playwright-test-*.js

内联模式（快速任务）：

cd $SKILL_DIR && node run.js "内联 JavaScript 代码"

辅助工具库

lib/helpers.js 提供实用函数：

函数	功能
detectDevServers()	自动发现运行中的开发服务器（端口扫描）
safeClick()	带重试的安全点击
safeType()	带清空的安全输入
takeScreenshot()	带时间戳的截图
handleCookieBanner()	自动处理 Cookie 横幅
extractTableData()	提取表格数据
createContext()	自动注入自定义 Headers 的 Context

自定义 HTTP 头部

通过环境变量配置全局请求头，便于：

• 标识自动化流量来源
• 获取 LLM 优化的纯文本错误响应
• 添加全局认证 Token

# 单 Header
PW_HEADER_NAME=X-Automated-By PW_HEADER_VALUE=playwright-skill \
 cd $SKILL_DIR && node run.js /tmp/my-script.js

# 多 Header（JSON）
PW_EXTRA_HEADERS='{"X-Automated-By":"playwright-skill","X-Debug":"true"}' \
 cd $SKILL_DIR && node run.js /tmp/my-script.js

关键配置

选项	默认值	说明
headless	false	可见浏览器，方便调试
slowMo	无	添加延迟使动作可见
waitUntil	networkidle	页面加载等待策略
timeout	10000ms	操作超时时间

最佳实践

• 先检测服务器：本地测试务必先运行 detectDevServers()
• 使用 /tmp：所有脚本写入临时目录，系统自动清理
• 参数化 URL：脚本顶部定义 TARGET_URL 常量
• 等待优于超时：使用 waitForURL、waitForSelector 替代固定等待
• 错误处理：关键操作包裹 try-catch
• 进度日志：使用 console.log() 展示执行状态

安装

首次使用需安装 Playwright 和 Chromium：

cd $SKILL_DIR && npm run setup

故障排查

问题	解决
Playwright 未安装	运行npm run setup
模块未找到	确保通过run.js 从技能目录执行
浏览器未打开	检查headless: false 和显示可用性
元素未找到	添加waitForSelector 延长等待时间