lackeyjb/playwright-skill · 上手攻略

• 仓库：lackeyjb/playwright-skill
• 链接：https://github.com/lackeyjb/playwright-skill
• 分类：ai
• 作者：Tom
• 更新：2026-08-19

是什么

playwright-skill 是一个通用浏览器自动化 Skill，基于 Playwright 实现，专为 AI Coding Agent 设计。它遵循开放的 Agent Skills 规范，可被 Claude Code、Cursor、GitHub Copilot、Codex、Gemini CLI、OpenCode 等主流 Coding Agent 自动发现并调用。

核心思路不是提供预制脚本，而是让 Agent 在对话中现场编写定制化 Playwright 代码并执行——从简单的页面测试到复杂多步流程均可。

仓库结构：

playwright-skill/
├── .claude-plugin/          # 插件元数据
└── skills/
    └── playwright-skill/
        ├── SKILL.md         # Agent 读取的核心指令文件
        ├── run.js           # 通用执行器（模块解析）
        ├── package.json
        ├── lib/
        │   └── helpers.js   # 工具函数（dev server 检测等）
        └── API_REFERENCE.md  # Playwright 全 API 参考（按需加载）

解决什么问题

Coding Agent 需要执行真实的浏览器自动化任务时，往往缺乏稳定执行 Playwright 代码的途径。传统方案要么是预置脚本覆盖范围有限，要么是直接调 Playwright API 但模块解析和依赖安装容易出问题。

playwright-skill 解决了三个痛点： 1. 动态编写：Agent 根据用户描述实时生成定制代码，不受预置脚本限制 2. 可靠执行：通过 run.js 执行器稳定处理 Node.js 模块解析，无需 Agent 自己处理 node -e 边界情况 3. 渐进披露：SKILL.md 仅包含核心指令，完整 API 参考（网络拦截、认证、视频、视觉回归测试等）在需要时才加载

快速安装

方式一：Vercel Skills CLI（推荐）

# 全局安装
npx skills add lackeyjb/playwright-skill --skill playwright-skill --global --yes

# 项目级安装（不加 --global）
npx skills add lackeyjb/playwright-skill --skill playwright-skill --yes

# 指定目标 Agent
npx skills add lackeyjb/playwright-skill --skill playwright-skill --agent claude-code cursor --global --yes

安装后，进入 Skill 目录并运行 setup：

cd ~/.claude/plugins/marketplace/playwright-skill/skills/playwright-skill
npm run setup

方式二：Claude Code 插件系统

/plugin marketplace add lackeyjb/playwright-skill
/plugin install playwright-skill@playwright-skill
cd ~/.claude/plugins/marketplaces/playwright-skill/skills/playwright-skill
npm run setup

方式三：手动下载（无安装器时）

从 GitHub Releases 下载最新压缩包，解压后仅复制 skills/playwright-skill/ 目录：

# 全局
cp -r skills/playwright-skill ~/.claude/skills/playwright-skill
# 项目级
cp -r skills/playwright-skill /path/to/project/.claude/skills/playwright-skill
cd ~/.claude/skills/playwright-skill
npm run setup

验证安装

/help

或让 Agent 执行一个简单任务：

"Test if google.com loads."

核心用法

安装完成后，直接用自然语言向 Agent 描述你的需求即可。Agent 会自动发现 Skill、写代码、执行并返回结果。

基础页面测试

// Agent 自动生成，保存到临时文件并执行
const os = require('node:os');
const path = require('path');
const { chromium } = require('playwright');

const targetUrl = process.env.TARGET_URL || 'http://localhost:3000';
const artifactDir = process.env.PW_ARTIFACT_DIR || os.tmpdir();

(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: path.join(artifactDir, 'page.png'), fullPage: true });
  } finally {
    await browser.close();
  }
})();

# Agent 通过 run.js 执行脚本
node "$SKILL_DIR/run.js" "$TMP_DIR/playwright-test-page.js"

快捷内联执行（短任务）

node "$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(); }"

响应式截图

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: path.join(artifactDir, `${viewport.name}.png`), fullPage: true });
}

登录流程测试

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();

本地 dev server 自动检测

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

关键环境变量

元素定位优先级

按以下顺序使用 Playwright Locator（符合可访问性原则）：

1. page.getByRole() — 语义化角色定位（推荐）
2. page.getByLabel() — 表单控件标签
3. page.getByText() — 可见文本内容
4. page.getByTestId() — 开发者指定的测试 ID

⚠️ 避免使用 CSS 选择器或 XPath，除非无其他选择；元素结构变化时 Locator 更稳定。

典型适用场景

• 网页功能测试：表单提交、登录流程、多步向导
• 响应式/跨端验证：多 viewport 截图，验证移动端和桌面端布局
• 自动化巡检：检查 broken links、图片加载失败、表单验证行为
• 数据抓取：需要 JavaScript 渲染后才可获取的页面内容
• 与 Coding Agent 集成：Agent 在修复 bug 时自动验证 UI 行为是否符合预期
• CI 集成：headless: true 模式下可在 GitHub Actions 等 CI 中运行

坑与注意

1. Node.js 版本要求：SKILL.md 标注需 Node.js 20+，实测 18 可能存在兼容问题，优先使用 20+。
2. 首次安装网络依赖：setup 阶段需下载 Chromium（约 150MB），国内网络可能较慢，可提前配置 npm 镜像或使用 --install-all-browsers 一次性装完。
3. 浏览器显示模式默认非 headless：生产/CI 场景需主动设置 PW_HEADLESS=true，否则会尝试打开可见窗口。
4. 模块解析必须通过 run.js：不要直接 node -e 执行 Playwright 代码——run.js 处理了模块路径，裸 node -e 会报 MODULE_NOT_FOUND。
5. 临时文件不持久化：默认脚本和截图放在系统临时目录，任务结束后自动清理；需要保留则设置 PW_SCRIPT_DIR 和 PW_ARTIFACT_DIR。
6. Agent 生成的代码质量依赖 Agent 能力：Skill 提供执行环境和 API 指引，生成的测试代码本身是否符合业务逻辑需要人工审核。

与同类对比

一句话总结：如果你在使用 Coding Agent，想让它做浏览器自动化，playwright-skill 是最高效的接入方式；如果你直接写脚本，微软的 @playwright/cli 或直接用 Playwright 库更直接。

一句话推荐结论

AI Coding Agent 时代的浏览器自动化入口——以 Skill 形式让 Agent 现场写、现场跑 Playwright 代码，比预置脚本灵活，比裸调用稳定。

原始链接：https://github.com/lackeyjb/playwright-skill 版本：5.0.0（SKILL.md 元数据）