playwright-skill

Playwright 浏览器自动化

针对用户的请求编写并执行精简的 Playwright 脚本。优先使用此技能的执行器和辅助工具，但必要时可使用完整的 Playwright API。

路径解析

此技能可能安装在多个位置，因此请先解析其目录。将 SKILL_DIR 设置为包含此 SKILL.md 文件的目录，然后按原样运行以下命令：

export SKILL_DIR=<absolute path of the directory containing this SKILL.md>
export TMP_DIR="$(node -p 'require("node:os").tmpdir()')"

如果 shell 状态不会在命令之间保留，请在每条命令中将 $SKILL_DIR 和 $TMP_DIR 替换为对应的实际路径。

常见安装路径：

• 插件系统：~/.claude/plugins/marketplaces/playwright-skill/skills/playwright-skill
• 全局手动安装：~/.claude/skills/playwright-skill
• 项目专用：<project>/.claude/skills/playwright-skill

工作流

1. 对于 localhost 任务，请在编写 URL 前检测正在运行的服务：

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

   自动使用唯一的检测结果。若有多个结果，请询问要使用哪个 URL。若没有结果，请询问 URL，或提出启动服务。

2. 除非用户要求将脚本保存在项目中，否则将可复用脚本写入 $TMP_DIR/playwright-test-*.js。使用 PW_SCRIPT_DIR 保留脚本。

3. 默认使用可见浏览器。仅在用户要求或环境没有显示器时使用 headless: true。

4. 将目标 URL 放入常量或环境变量中。

5. 使用 node "$SKILL_DIR/run.js" <script.js> 运行脚本。

6. 报告执行的操作、失败情况和产物路径。检查结果页面后再报告成功。

设置

运行一次：

cd "$SKILL_DIR" && npm run setup

这会安装 Playwright 和 Chromium。需要 Firefox 或 WebKit 时，使用 cd "$SKILL_DIR" && npm run install-all-browsers。

最小示例

const os = require('node:os');
const path = require('node: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();
  }
})();

运行：

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

-e 进程会在代码片段执行完毕后立即退出，因此请在代码片段中关闭浏览器。

当前 Playwright 模式

优先使用能描述用户所见内容的定位器，顺序如下：

1. 使用带有可访问名称的 page.getByRole()
2. 对表单控件使用 page.getByLabel()
3. 对可见内容使用 page.getByText()
4. 应用提供测试约定时使用 page.getByTestId()

操作会自动等待元素达到可操作状态。使用面向 Web 的断言或定位器的 waitFor()，而不要使用 waitForSelector()、固定时长的休眠或 networkidle。

await page.getByLabel('Email').fill('[email protected]');
await page.getByRole('button', { name: 'Sign in' }).click();
await page.waitForURL('**/dashboard');
await page.getByRole('heading', { name: 'Dashboard' }).waitFor();

常见任务

响应式检查

{
  const os = require('node:os');
  const path = require('node:path');

  const artifactDir = process.env.PW_ARTIFACT_DIR || os.tmpdir();
  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();

保存脚本和产物

PW_SCRIPT_DIR=./playwright-tests node "$SKILL_DIR/run.js" "$TMP_DIR/playwright-test-login.js"
PW_ARTIFACT_DIR=./playwright-artifacts node "$SKILL_DIR/run.js" "$TMP_DIR/playwright-test-page.js"

PW_SCRIPT_DIR 会在执行前复制基于文件的脚本，并在文件名已存在时添加时间戳。PW_ARTIFACT_DIR 用于控制辅助工具的截图输出；默认值为操作系统的临时目录。

连接到现有 Chrome 会话

使用启用了远程调试的方式启动 Chrome，然后通过 Playwright 连接：

const browser = await chromium.connectOverCDP('http://127.0.0.1:9222');
const page = browser.contexts()[0].pages()[0];

这会复用该会话中的 Cookie 和扩展程序。除非用户明确要求，否则不要用它处理机密信息；连接的浏览器拥有用户的访问权限。

辅助工具

const 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、getExtraHeadersFromEnv、launchBrowser、createContext、handleCookieBanner 和 takeScreenshot。对于操作、等待、内容提取、身份验证、表格和重试，请直接使用 Playwright 定位器和断言。

配置

• PW_BROWSER：launchBrowser() 使用的 chromium、firefox 或 webkit。
• PW_CHANNEL：已安装的浏览器渠道，例如 chrome 或 msedge。
• PW_EXECUTABLE_PATH：浏览器可执行文件的显式路径。
• PW_HEADLESS：true 或 false；默认使用可视模式。
• SLOW_MO：操作延迟，单位为毫秒。
• PW_HEADER_NAME 和 PW_HEADER_VALUE：一个额外的 HTTP 标头。
• PW_EXTRA_HEADERS：额外 HTTP 标头的 JSON 对象。
• PW_SCRIPT_DIR：用于保留基于文件的脚本的目录。
• PW_ARTIFACT_DIR：用于存放辅助工具生成的屏幕截图的目录。

请参阅 API_REFERENCE.md，了解网络拦截、API 模拟、身份验证状态、视频、视觉检查、设备模拟和 CI 模式。