AI 技能浏览器控制GUI 自动化测试【免费下载链接】playwright-skillGeneral-purpose Playwright automation for coding agents项目地址https://gitcode.com/gh_mirrors/pl/playwright-skill点击查看免费下载导读本文系统讲解 playwright-skill 这个面向编码 Agent 的通用 Playwright 自动化技能Agent Skill它让 Claude 等 Agent 能够按需编写并执行从简单页面测试到复杂多步流程的浏览器自动化脚本并附带一个可复用的通用执行器run.js、一组聚焦的辅助函数helpers以及一份完整的 API 参考文档。读完本文你将掌握该技能的安装方式skillsCLI / Claude Code 插件 / 手动拷贝 / Release 下载、环境变量配置体系、文件与内联脚本两种执行模式以及如何让 Agent 替你完成登录流程、响应式截图、表单校验、断链检查等真实浏览器任务。一、这是什么给编码 Agent 的浏览器自动化技能playwright-skill是一个实现 open Agent Skills 规范 的 Agent Skill核心定位是General-purpose Playwright automation for coding agents——让 Agent 在对话中临时编写、执行真实可跑的 Playwright 程序。与固定的预置脚本不同它强调Any Automation TaskClaude 会针对你的具体请求编写定制代码而不是受限于预设用例。与同类方案的分工来自 README.md简单的交互式浏览、工具型浏览器控制可考虑微软官方的playwright/cliplaywright-cli install --skills与playwright-mcp基于可访问性快照而当自动化本身就是要保留、可复跑、可维护的产物时本项目是代码优先code-first的选择循环、断言、多上下文、网络拦截、截图、视频、希望保存并反复运行的脚本都属于它的适用场景。注意以下标题行号等引用均指向当前仓库中的实际文件链接见文末延伸阅读。1.1 核心特性一览README 归纳了 6 项能力README.md每一项都有仓库源码支撑特性含义源码佐证Any Automation TaskAgent 针对请求编写定制代码不受预置脚本限制SKILL.md 的 WorkflowVisible Browser by Default默认headless: false可实时看到自动化过程helpers.js 中PW_HEADLESS || false的默认值Portable executorrun.js以稳定模块解析运行文件和内联脚本run.js 通过NODE_PATH注入node_modulesProgressive DisclosureSKILL.md 精简完整 API 参考按需加载SKILL.md 与 API_REFERENCE.md 的分层设计Safe Cleanup无竞态条件的临时文件管理run.js 的saveScript时间戳去重Comprehensive Helpers可选的通用任务辅助函数helpers.js 导出的 6 个函数1.2 前端元数据frontmatter技能本体由 SKILL.md 的 frontmatter 声明name: playwright-skill description: Complete browser automation with Playwright. Auto-detects dev servers, writes reusable test scripts, and supports screenshots, responsive checks, UX validation, login flows, link checks, and arbitrary browser automation. license: MIT compatibility: Requires Node.js 20, npm, and network access on first setup to install Playwright and Chromium. metadata: author: lackeyjb version: 5.0.0 allowed-tools: Bash(node:*) Bash(npm:*) Read Write从中可确认两个硬性前提package.json 亦同步声明Node.js ≥ 20engines字段Playwright 版本基线为^1.62.0见 CHANGELOG.md 中 v5.0.0 的变更说明。二、仓库结构与工程形态本仓库采用插件包内嵌技能的嵌套结构README.mdplaywright-skill/ # Plugin root ├── .claude-plugin/ # Plugin metadata └── skills/ └── playwright-skill/ # The actual skill └── SKILL.md完整文件布局README.mdplaywright-skill/ ├── .claude-plugin/ │ ├── plugin.json # Plugin metadata for distribution │ └── marketplace.json # Marketplace configuration ├── skills/ │ └── playwright-skill/ # The actual skill (Claude discovers this) │ ├── SKILL.md # What Claude reads │ ├── run.js # Universal executor (proper module resolution) │ ├── package.json # Dependencies setup scripts │ └── lib/ │ └── helpers.js # Optional utility functions │ └── API_REFERENCE.md # Full Playwright API reference ├── README.md # This file - user documentation ├── CONTRIBUTING.md # Contribution guidelines └── LICENSE # MIT License设计要点Agent 只会读取SKILL.mdAPI_REFERENCE.md仅在需要深入主题时按需加载Progressive Disclosure渐进式披露从而控制每次任务的上下文开销。安装器能自动处理这种嵌套布局手动拷贝只是无安装器客户端时的兜底方案。三、四种安装方式README 提供了 4 条安装路径任选其一安装后都需要在技能目录执行npm run setup完成 Playwright 与 Chromium 的安装该命令等价于npm install npx playwright install chromium见 package.json 的 scripts。方式一skillsCLI推荐Vercel 的skillsCLI 会把技能安装到各受支持 Agent 的原生位置# 全局安装当前用户 npx skills add lackeyjb/playwright-skill --skill playwright-skill --global --yes # 仅当前项目安装去掉 --global npx skills add lackeyjb/playwright-skill --skill playwright-skill --yes # 定向安装到指定 Agent如 claude-code、cursor npx skills add lackeyjb/playwright-skill --skill playwright-skill --agent claude-code cursor --global --yes安装后进入技能目录执行初始化npm run setup方式二Claude Code 插件通过 Claude Code 插件系统安装可获得自动更新与团队分发能力# 将本仓库添加为 marketplace /plugin marketplace add lackeyjb/playwright-skill # 安装插件 /plugin install playwright-skillplaywright-skill # 进入技能目录并完成初始化 cd ~/.claude/plugins/marketplaces/playwright-skill/skills/playwright-skill npm run setup方式三其他 AgentAgent Skills 已被 Claude Code、Cursor、GitHub Copilot、Codex、Gemini CLI、OpenCode 等客户端支持。将包含SKILL.md的目录即skills/playwright-skill/放入客户端文档规定的技能路径即可没有安装器的客户端把该目录拷贝到其技能目录后运行npm run setup。方式四下载 Release从 Release 下载并解压最新版本只拷贝skills/playwright-skill/文件夹到目标位置全局~/.claude/skills/playwright-skill项目/path/to/your/project/.claude/skills/playwright-skill进入技能目录执行npm run setup。验证安装运行/help确认技能已加载然后让 Claude 执行一个简单浏览器任务例如Test if google.com loadsREADME.md。四、Quick Start 与使用示例安装后直接对 Agent 描述需求即可Agent 会编写定制 Playwright 代码、执行它并返回带截图与控制台输出的结果README.md。README 给出了四类典型 PromptREADME.md测试任意页面Test the homepage Check if the contact form works Verify the signup flow视觉测试Take screenshots of the dashboard in mobile and desktop Test responsive design across different viewports交互测试Fill out the registration form and submit it Click through the main navigation Test the search functionality校验类Check for broken links Verify all images load Test form validation工作流程五步完成一次自动化README 明确了整体链路README.md在 SKILL.md 中被展开为更细的 6 步执行流程描述你要测试或自动化的目标Agent 为任务编写定制 Playwright 代码通用执行器run.js以正确的模块解析运行它浏览器打开默认可见并执行自动化返回控制台输出与截图结果。SKILL.md的 Workflow 补充了本地开发场景的关键细节localhost 任务先探测开发服务器见第五节可复用的脚本写到/tmp/playwright-test-*.js除非用户要求保存在项目里用PW_SCRIPT_DIR保留脚本默认可见浏览器只有用户要求或无显示环境时才用headless: true目标 URL 放进常量或环境变量统一用node $SKILL_DIR/run.js script.js运行汇报动作、失败与产物路径不检查结果页面不得宣称成功。五、核心执行器 run.js文件脚本与内联执行run.js是本技能的执行中枢run.js它解决的关键问题是模块解析module resolution技能可能被安装在任何位置直接require(playwright)会在用户的 cwd 下解析失败。其实现方式是在派生子进程时注入两个环境变量run.jsconst child spawn(process.execPath, args, { cwd: process.cwd(), // 保持调用方的 cwd相对路径按用户项目解析 env: { ...process.env, NODE_PATH: nodeModules, PW_SKILL_DIR: skillDir }, stdio: inherit, });NODE_PATH指向技能自带的node_modules保证脚本能稳定加载 PlaywrightPW_SKILL_DIR指向技能目录脚本里可以require(process.env.PW_SKILL_DIR /lib/helpers)cwd: process.cwd()让脚本内相对路径、PW_ARTIFACT_DIR都相对用户项目而非技能安装目录v5.0.0 起的行为见 CHANGELOG.md。执行前还会做依赖检查ensurePlaywright()解析不到playwright时直接报错提示先运行npm run setuprun.js。5.1 文件脚本模式node $SKILL_DIR/run.js /tmp/playwright-test-page.js若设置了PW_SCRIPT_DIRsaveScript会在执行前把脚本复制到该目录run.js自动mkdir -p目标目录文件名已存在时追加-时间戳后缀避免覆盖。这组行为被 executor.test.js 的PW_SCRIPT_DIR preserves scripts and avoids collisions用例覆盖。5.2 内联执行模式短小的一次性任务可以直接用-enode $SKILL_DIR/run.js -e const browser await chromium.launch({headless: false}); try { const page await browser.newPage(); await page.goto(https://example.com); console.log(await page.title()); } finally { await browser.close(); }run.js会为内联片段自动注入const { chromium, firefox, webkit, devices } require(playwright); const helpers require(...)前缀run.js因此片段里可直接使用chromium与helpers。两个值得注意的实现细节片段一落地即退出-e进程在片段 settle 后立即process.exit所以必须在片段内部关闭浏览器否则句柄悬空会导致进程挂起SKILL.md 明确提示run.js 有对应实现executor.test.js 用setInterval验证了即使句柄未关闭也能正常退出输出防截断退出前显式 flush stdout/stderr避免超过管道缓冲的大输出丢失对应 executor.test.js 的两条 200KB 输出用例。5.3 退出码与信号处理子进程退出码会原样传递给父进程收到SIGINT/SIGTERM时转发给子进程2 秒内未退出则升级为SIGKILL避免僵尸进程run.js。测试断言抛错脚本必须返回非零退出码executor.test.js。注意run.js已不再支持 stdin 执行v5.0.0 移除见 CHANGELOG.md请改用脚本文件或-e。六、辅助函数 helpers聚焦而非全能v5.0.0 起 helpers 被精简为 6 个聚焦浏览器环境搭建的函数helpers.js凡 Playwright 原生覆盖的操作动作、等待、提取、鉴权、表格、重试一律直接使用官方 locator 与断言不再重复封装CHANGELOG.mdconst helpers require(${process.env.PW_SKILL_DIR}/lib/helpers); const servers await helpers.detectDevServers(); const browser await helpers.launchBrowser(chromium); const context await helpers.createContext(browser); const page await context.newPage(); await helpers.handleCookieBanner(page); await helpers.takeScreenshot(page, result);各函数职责与实现细节detectDevServers(customPorts?)对一组常见开发端口3000/3001/3002/5173/8080/8000/4200/5000/9000/1234 及自定义端口并发发HEAD localhost请求返回可用的http://localhost:port列表helpers.js。SKILL.md建议探测到唯一结果就直接使用多结果时向用户询问无结果时询问 URL 或主动起一个服务器。测试用例detects a running HTTP server on a custom port验证了该逻辑helpers.test.js。launchBrowser(browserType, options)按PW_BROWSER选择 chromium/firefox/webkit读取PW_HEADLESS空值视为未设置回退到可见模式、SLOW_MO、PW_CHANNEL、PW_EXECUTABLE_PATHhelpers.js。v5.0.0 起--no-sandbox仅在 Chromium 且以 root 运行时自动追加其余场景需显式传args: [--no-sandbox]CHANGELOG.md。createContext(browser, options)默认视口 1280×720、locale: en-US、时区America/New_York并自动合并环境变量指定的额外请求头mobile选项已移除改用 Playwright 设备描述符如devices[iPhone 15]helpers.js、CHANGELOG.md。handleCookieBanner(page, timeout)按常见文案/选择器序列Accept/Accept all/OK/Got it/I agree 按钮、.cookie-accept、#cookie-accept、[data-testidcookie-accept]依次尝试点击可见项找到即返回truehelpers.js。takeScreenshot(page, name, options)默认输出到PW_ARTIFACT_DIR或系统临时目录文件名带 ISO 时间戳默认整页截图fullPage可通过参数关闭helpers.js。getExtraHeadersFromEnv()优先解析单头PW_HEADER_NAME/PW_HEADER_VALUE其次解析PW_EXTRA_HEADERS的 JSON 对象解析失败会告警并返回nullhelpers.jshelpers.test.js 覆盖了单头与多头两种解析。七、环境变量配置体系7.1 技能级配置SKILL.md 定义变量取值作用PW_BROWSERchromium/firefox/webkit指定launchBrowser()的浏览器类型PW_CHANNEL如chrome、msedge使用已安装的浏览器渠道PW_EXECUTABLE_PATH路径显式指定浏览器可执行文件PW_HEADLESStrue/false是否无头可见模式为默认空值回退可见SLOW_MO毫秒数操作间延时调试慢动作用PW_HEADER_NAME/PW_HEADER_VALUE字符串附加一个自定义 HTTP 头PW_EXTRA_HEADERSJSON 对象字符串附加多个 HTTP 头PW_SCRIPT_DIR目录路径保留文件型脚本重名自动加时间戳PW_ARTIFACT_DIR目录路径指定 helper 截图的输出目录默认系统临时目录README 的默认配置项与此对应README.mdHeadless 默认falseSlow Motion 默认0ms需要时设置SLOW_MOhelper 截图默认输出 OS 临时目录可用PW_ARTIFACT_DIR改址。7.2 请求头注入与优先级PW_EXTRA_HEADERS让自动化流量自带标识典型用途是让后端为 LLM 返回优化响应如纯文本错误而非渲染好的 HTMLAPI_REFERENCE.md# 单头 PW_HEADER_NAMEX-Automated-By PW_HEADER_VALUEplaywright-skill # 多头JSON PW_EXTRA_HEADERS{X-Automated-By:playwright-skill,X-Request-ID:123}优先级从高到低options.extraHTTPHeaders显式传入 → 环境变量头 → Playwright 默认值。7.3 保存脚本与产物PW_SCRIPT_DIR./playwright-tests node $SKILL_DIR/run.js /tmp/playwright-test-login.js PW_ARTIFACT_DIR./playwright-artifacts node $SKILL_DIR/run.js /tmp/playwright-test-page.jsPW_SCRIPT_DIR在文件脚本执行前复制并如重名打时间戳PW_ARTIFACT_DIR控制 helper 截图输出。八、标准 Playwright 编程模式SKILL.md提供了可直接复制的现代 Playwright 模式与 API_REFERENCE.md 的完整参考互补8.1 最小示例const { chromium } require(playwright); const targetUrl process.env.TARGET_URL || http://localhost:3000; (async () { const browser await chromium.launch({ headless: false }); try { const page await browser.newPage(); await page.goto(targetUrl); console.log(Page loaded:, await page.title()); await page.screenshot({ path: /tmp/page.png, fullPage: true }); } finally { await browser.close(); } })();运行node $SKILL_DIR/run.js /tmp/playwright-test-page.js。8.2 Locator 优先级与 Web-First 等待选择器按用户所见优先排序SKILL.mdpage.getByRole() 可访问名称page.getByLabel()表单控件page.getByText()可见文本page.getByTestId()应用提供测试契约时。动作自带可操作性自动等待断言优先用web-first 断言或 locator 的waitFor()避免waitForSelector()、固定 sleep 与networkidleawait page.getByLabel(Email).fill(testexample.com); await page.getByRole(button, { name: Sign in }).click(); await page.waitForURL(**/dashboard); await page.getByRole(heading, { name: Dashboard }).waitFor();这与仓库测试完全一致冒烟测试 smoke.js 用getByLabel/getByRole/waitForURL/waitFor对 login.html 完成登录并断言 Dashboard 可见。8.3 响应式检查const viewports [ { name: desktop, width: 1440, height: 900 }, { name: mobile, width: 390, height: 844 }, ]; for (const viewport of viewports) { await page.setViewportSize(viewport); await page.goto(targetUrl); await page.screenshot({ path: /tmp/${viewport.name}.png, fullPage: true }); }8.4 登录流程务必使用用户提供的测试凭据绝不发明或暴露真实凭据并同时校验导航跳转与登录后元素await page.goto(${targetUrl}/login); await page.getByLabel(Email).fill(process.env.TEST_EMAIL); await page.getByLabel(Password).fill(process.env.TEST_PASSWORD); await page.getByRole(button, { name: /sign in|log in/i }).click(); await page.waitForURL(**/dashboard); await page.getByRole(heading, { name: /dashboard/i }).waitFor();8.5 连接已有 Chrome 会话先以远程调试模式启动 Chrome再用 CDP 连接可复用该会话的 Cookie 与扩展const browser await chromium.connectOverCDP(http://127.0.0.1:9222); const page browser.contexts()[0].pages()[0];注意被连接的浏览器拥有用户当前权限除非用户明确要求不得用其处理机密信息。九、Advanced Usage按需加载的完整 API 参考当任务涉及选择器、网络拦截、鉴权、视觉回归、移动端模拟、性能测试、调试等主题时Claude 会自动加载 API_REFERENCE.mdREADME.md。该文档涵盖安装与配置、核心模式、选择器与 Locator、常见动作、等待策略、断言、Page Object Model、网络与 API 测试、鉴权与会话、视觉测试、移动端测试、调试、性能、并行执行、数据驱动测试、可访问性测试、CI/CD 集成、最佳实践与排障并给出playwright.config.ts完整示例与npx playwright test --debug、--headed、codegen、show-report等调试命令。常用能力速览网络拦截与 API Mockpage.route(**/api/users, route route.fulfill({...}))、route.abort()屏蔽图片等资源视觉对比await expect(page).toHaveScreenshot(homepage.png)移动端模拟const iPhone devices[iPhone 12]; browser.newContext({ ...iPhone, locale, permissions, geolocation })弹窗/下载/iframePromise.all([page.waitForEvent(popup), page.click(...)])、page.frameLocator(#my-iframe)等模式。十、依赖与排障依赖README.mdNode.js≥ 20package.jsonenginesPlaywrightnpm run setup安装Chromiumnpm run setup安装npm run install-all-browsers可补装 Firefox 与 WebKit等价于npx playwright install chromium firefox webkit。常见问题README.md症状处理Playwright not installed进入技能目录运行npm run setupModule not found errors确保通过run.js执行它负责模块解析Browser doesnt open确认设置了headless: false技能默认可见模式需要所有浏览器技能目录运行npm run install-all-browsersrun.js在找不到playwright时也会直接提示运行 setup脚本路径不存在时报Script not found并以非零码退出executor.test.js。十一、什么是 Agent Skill以及如何参与Agent Skills 是指令、脚本与资源的文件夹Agent 发现后可用于更准确高效地完成任务README.md当你让 Claude 测试网页或自动化浏览器交互时Claude 发现本技能、加载必要指令、执行定制 Playwright 代码并返回带截图与控制台输出的结果。本技能实现 open Agent Skills 规范可跨 Agent 平台使用。仓库欢迎贡献fork、创建特性分支、提交 PR细节见 CONTRIBUTING.md许可证为 MIT见 LICENSE。延伸阅读仓库内SKILL.md——Agent 实际读取的操作指令工作流、模式、配置API_REFERENCE.md——完整 Playwright API 参考与进阶模式run.js——通用执行器实现模块解析、信号处理、内联执行helpers.js——辅助函数实现服务器探测、浏览器/上下文、Cookie、截图executor.test.js 与 helpers.test.js——执行器与辅助函数的单元测试smoke.js 与 tests/fixtures——端到端冒烟测试及登录/仪表盘夹具页面CHANGELOG.md——v5.0.0 的行为变更含破坏性变更说明。如需本地体验可git clone本仓库后按第三节任一方式安装随后运行npm run setup并对 Agent 说一句Test if google.com loads即可验证全链路。赞分享AI 技能浏览器控制GUI 自动化测试【免费下载链接】playwright-skillGeneral-purpose Playwright automation for coding agents项目地址https://gitcode.com/gh_mirrors/pl/playwright-skill点击查看免费下载相关推荐Playwright Skill 实战指南让编码 Agent 自动完成浏览器测试与网页自动化Playwright Skill 实战指南让编码 Agent 自动完成浏览器测试与网页自动化 导读 SKILL.md https://link.gitcodeAI 技能浏览器控制GUI 自动化测试VoltAgent Workspace 技能实战用 playwright-cli SKILL 驱动浏览器自动化VoltAgent Workspace 技能实战用 playwright cli SKILL 驱动浏览器自动化 导读 本文以 VoltAgent 仓库中 wi人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音Umi-OCR 离线 OCR截图、批量图片到可搜索 PDFUmi OCR 离线 OCR截图、批量图片到可搜索 PDF 屏幕里的字想直接复制扫描件想导出成能检索的 PDF或者想在自己的脚本里调一行文字识别——遇到这OCR桌面应用上一篇暗黑破坏神2存档编辑器 Diablo Edit2 完整使用指南从入门到精通下一篇Diablo Edit2 实战指南用免费的暗黑2存档编辑器拯救养废的角色创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考