Playwright 浏览器自动化技能 - 智能检测开发服务器，可视化网页测试与自动化

Playwright Browser Automation by questfortech-investments/claude-code-skills

4 GitHub Stars

安装命令

npx skills add https://github.com/questfortech-investments/claude-code-skills --skill 'Playwright Browser Automation'

🇨🇳中文介绍

重要提示 - 路径解析： 此技能可以安装在不同的位置（插件系统、手动安装、全局安装或项目特定安装）。在执行任何命令之前，请根据加载此 SKILL.md 文件的位置确定技能目录，并在以下所有命令中使用该路径。请将 $SKILL_DIR 替换为实际发现的路径。

常见的安装路径：

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

Playwright 浏览器自动化

通用浏览器自动化技能。我将为您请求的任何自动化任务编写自定义的 Playwright 代码，并通过通用执行器执行它。

关键工作流程 - 请按顺序遵循以下步骤：

自动检测开发服务器 - 对于 localhost 测试，始终首先运行服务器检测：

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

 * 如果**找到 1 个服务器**：自动使用它，并通知用户

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

设置（首次使用）

cd $SKILL_DIR
npm run setup

这将安装 Playwright 和 Chromium 浏览器。仅需执行一次。

步骤 1：检测开发服务器（用于 localhost 测试）

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

步骤 2：将测试脚本写入 /tmp 并包含 URL 参数

// /tmp/playwright-test-page.js
const { chromium } = require('playwright');

// 参数化的 URL（检测到的或用户提供的）
const TARGET_URL = 'http://localhost:3001'; // <-- 自动检测或来自用户

(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  await page.goto(TARGET_URL);
  console.log('Page loaded:', await page.title());

  await page.screenshot({ path: '/tmp/screenshot.png', fullPage: true });
  console.log('📸 Screenshot saved to /tmp/screenshot.png');

  await browser.close();
})();

步骤 3：从技能目录执行

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

测试页面（多种视口）

// /tmp/playwright-test-responsive.js
const { chromium } = require('playwright');

const TARGET_URL = 'http://localhost:3001'; // 自动检测

(async () => {
  const browser = await chromium.launch({ headless: false, slowMo: 100 });
  const page = await browser.newPage();

  // 桌面测试
  await page.setViewportSize({ width: 1920, height: 1080 });
  await page.goto(TARGET_URL);
  console.log('Desktop - Title:', await page.title());
  await page.screenshot({ path: '/tmp/desktop.png', fullPage: true });

  // 移动端测试
  await page.setViewportSize({ width: 375, height: 667 });
  await page.screenshot({ path: '/tmp/mobile.png', fullPage: true });

  await browser.close();
})();

// /tmp/playwright-test-login.js
const { chromium } = require('playwright');

const TARGET_URL = 'http://localhost:3001'; // 自动检测

(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  await page.goto(`${TARGET_URL}/login`);

  await page.fill('input[name="email"]', 'test@example.com');
  await page.fill('input[name="password"]', 'password123');
  await page.click('button[type="submit"]');

  // 等待重定向
  await page.waitForURL('**/dashboard');
  console.log('✅ Login successful, redirected to dashboard');

  await browser.close();
})();

填写并提交表单

// /tmp/playwright-test-form.js
const { chromium } = require('playwright');

const TARGET_URL = 'http://localhost:3001'; // 自动检测

(async () => {
  const browser = await chromium.launch({ headless: false, slowMo: 50 });
  const page = await browser.newPage();

  await page.goto(`${TARGET_URL}/contact`);

  await page.fill('input[name="name"]', 'John Doe');
  await page.fill('input[name="email"]', 'john@example.com');
  await page.fill('textarea[name="message"]', 'Test message');
  await page.click('button[type="submit"]');

  // 验证提交
  await page.waitForSelector('.success-message');
  console.log('✅ Form submitted successfully');

  await browser.close();
})();

检查损坏的链接

const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  await page.goto('http://localhost:3000');

  const links = await page.locator('a[href^="http"]').all();
  const results = { working: 0, broken: [] };

  for (const link of links) {
    const href = await link.getAttribute('href');
    try {
      const response = await page.request.head(href);
      if (response.ok()) {
        results.working++;
      } else {
        results.broken.push({ url: href, status: response.status() });
      }
    } catch (e) {
      results.broken.push({ url: href, error: e.message });
    }
  }

  console.log(`✅ Working links: ${results.working}`);
  console.log(`❌ Broken links:`, results.broken);

  await browser.close();
})();

截图并包含错误处理

const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  try {
    await page.goto('http://localhost:3000', {
      waitUntil: 'networkidle',
      timeout: 10000
    });

    await page.screenshot({
      path: '/tmp/screenshot.png',
      fullPage: true
    });

    console.log('📸 Screenshot saved to /tmp/screenshot.png');
  } catch (error) {
    console.error('❌ Error:', error.message);
  } finally {
    await browser.close();
  }
})();

测试响应式设计

// /tmp/playwright-test-responsive-full.js
const { chromium } = require('playwright');

const TARGET_URL = 'http://localhost:3001'; // 自动检测

(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  const viewports = [
    { name: 'Desktop', width: 1920, height: 1080 },
    { name: 'Tablet', width: 768, height: 1024 },
    { name: 'Mobile', width: 375, height: 667 }
  ];

  for (const viewport of viewports) {
    console.log(`Testing ${viewport.name} (${viewport.width}x${viewport.height})`);

    await page.setViewportSize({
      width: viewport.width,
      height: viewport.height
    });

    await page.goto(TARGET_URL);
    await page.waitForTimeout(1000);

    await page.screenshot({
      path: `/tmp/${viewport.name.toLowerCase()}.png`,
      fullPage: true
    });
  }

  console.log('✅ All viewports tested');
  await browser.close();
})();

内联执行（简单任务）

对于快速的一次性任务，您可以内联执行代码而无需创建文件：

# 快速截图
cd $SKILL_DIR && node run.js "
const browser = await chromium.launch({ headless: false });
const page = await browser.newPage();
await page.goto('http://localhost:3001');
await page.screenshot({ path: '/tmp/quick-screenshot.png', fullPage: true });
console.log('Screenshot saved');
await browser.close();
"

何时使用内联与文件：

内联：快速的一次性任务（截图、检查元素是否存在、获取页面标题）
文件：复杂的测试、响应式设计检查、用户可能希望重新运行的任何内容

可用的辅助函数

lib/helpers.js 中的可选实用函数：

const helpers = require('./lib/helpers');

// 检测正在运行的开发服务器（关键 - 首先使用这个！）
const servers = await helpers.detectDevServers();
console.log('Found servers:', servers);

// 带重试的安全点击
await helpers.safeClick(page, 'button.submit', { retries: 3 });

// 带清除的安全输入
await helpers.safeType(page, '#username', 'testuser');

// 获取带时间戳的截图
await helpers.takeScreenshot(page, 'test-result');

// 处理 Cookie 横幅
await helpers.handleCookieBanner(page);

// 提取表格数据
const data = await helpers.extractTableData(page, 'table.results');

完整列表请参见 lib/helpers.js。

有关完整的 Playwright API 文档，请参阅 API_REFERENCE.md：

选择器和定位器最佳实践
网络拦截和 API 模拟
身份验证和会话管理
视觉回归测试
移动设备模拟
性能测试
调试技术
CI/CD 集成

关键：首先检测服务器 - 在为 localhost 测试编写测试代码之前，始终运行 detectDevServers()
使用 /tmp 存放测试文件 - 写入 /tmp/playwright-test-*.js，切勿写入技能目录或用户项目
参数化 URL - 在每个脚本的顶部将检测到/提供的 URL 放入 TARGET_URL 常量中
默认：可见浏览器 - 除非用户明确要求无头模式，否则始终使用 headless: false
无头模式 - 仅当用户明确请求"无头"或"后台"执行时才使用 headless: true
放慢速度： 使用 slowMo: 100 使操作可见且更易于跟踪
等待策略： 使用 waitForURL、waitForSelector、waitForLoadState 而不是固定的超时
错误处理： 始终使用 try-catch 以实现稳健的自动化
控制台输出： 使用 console.log() 来跟踪进度并显示正在发生的情况

未安装 Playwright：

cd $SKILL_DIR && npm run setup

找不到模块： 确保通过 run.js 包装器从技能目录运行

浏览器未打开： 检查 headless: false 并确保显示可用

找不到元素： 添加等待：await page.waitForSelector('.element', { timeout: 10000 })

User: "Test if the marketing page looks good"

Claude: I'll test the marketing page across multiple viewports. Let me first detect running servers...
[Runs: detectDevServers()]
[Output: Found server on port 3001]
I found your dev server running on http://localhost:3001

[Writes custom automation script to /tmp/playwright-test-marketing.js with URL parameterized]
[Runs: cd $SKILL_DIR && node run.js /tmp/playwright-test-marketing.js]
[Shows results with screenshots from /tmp/]



User: "Check if login redirects correctly"

Claude: I'll test the login flow. First, let me check for running servers...
[Runs: detectDevServers()]
[Output: Found servers on ports 3000 and 3001]
I found 2 dev servers. Which one should I test?
- http://localhost:3000
- http://localhost:3001

User: "Use 3001"

[Writes login automation to /tmp/playwright-test-login.js]
[Runs: cd $SKILL_DIR && node run.js /tmp/playwright-test-login.js]
[Reports: ✅ Login successful, redirected to /dashboard]

每次自动化都是根据您的特定请求定制的
不限于预构建的脚本 - 任何浏览器任务都可能实现
自动检测正在运行的开发服务器以消除硬编码的 URL
测试脚本写入 /tmp 以便自动清理（无杂乱）
代码通过 run.js 以正确的模块解析可靠地执行
渐进式披露 - API_REFERENCE.md 仅在需要高级功能时加载

🇺🇸English

IMPORTANT - Path Resolution: This skill can be installed in different locations (plugin system, manual installation, global, or project-specific). Before executing any commands, determine the skill directory based on where you loaded this SKILL.md file, and use that path in all commands below. Replace $SKILL_DIR with the actual discovered path.

Common installation paths:

Plugin system: ~/.claude/plugins/marketplaces/playwright-skill/skills/playwright-skill
Manual global: ~/.claude/skills/playwright-skill
Project-specific: <project>/.claude/skills/playwright-skill

Playwright Browser Automation

General-purpose browser automation skill. I'll write custom Playwright code for any automation task you request and execute it via the universal executor.

CRITICAL WORKFLOW - Follow these steps in order:

Auto-detect dev servers - For localhost testing, ALWAYS run server detection FIRST:

cd $SKILL_DIR && node -e "require('./lib/helpers').detectDevServers().then(servers => console.log(JSON.stringify(servers)))"
- If 1 server found : Use it automatically, inform user
- If multiple servers found : Ask user which one to test
- If no servers found : Ask for URL or offer to help start dev server
Write scripts to /tmp - NEVER write test files to skill directory; always use /tmp/playwright-test-*.js
Use visible browser by default - Always use headless: false unless user specifically requests headless mode
Parameterize URLs - Always make URLs configurable via environment variable or constant at top of script

How It Works

You describe what you want to test/automate
I auto-detect running dev servers (or ask for URL if testing external site)
I write custom Playwright code in /tmp/playwright-test-*.js (won't clutter your project)
I execute it via: cd $SKILL_DIR && node run.js /tmp/playwright-test-*.js
Results displayed in real-time, browser window visible for debugging
Test files auto-cleaned from /tmp by your OS

Setup (First Time)

cd $SKILL_DIR
npm run setup

This installs Playwright and Chromium browser. Only needed once.

Execution Pattern

Step 1: Detect dev servers (for localhost testing)

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

Step 2: Write test script to /tmp with URL parameter

// /tmp/playwright-test-page.js
const { chromium } = require('playwright');

// Parameterized URL (detected or user-provided)
const TARGET_URL = 'http://localhost:3001'; // <-- Auto-detected or from user

(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  await page.goto(TARGET_URL);
  console.log('Page loaded:', await page.title());

  await page.screenshot({ path: '/tmp/screenshot.png', fullPage: true });
  console.log('📸 Screenshot saved to /tmp/screenshot.png');

  await browser.close();
})();

Step 3: Execute from skill directory

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

Common Patterns

Test a Page (Multiple Viewports)

// /tmp/playwright-test-responsive.js
const { chromium } = require('playwright');

const TARGET_URL = 'http://localhost:3001'; // Auto-detected

(async () => {
  const browser = await chromium.launch({ headless: false, slowMo: 100 });
  const page = await browser.newPage();

  // Desktop test
  await page.setViewportSize({ width: 1920, height: 1080 });
  await page.goto(TARGET_URL);
  console.log('Desktop - Title:', await page.title());
  await page.screenshot({ path: '/tmp/desktop.png', fullPage: true });

  // Mobile test
  await page.setViewportSize({ width: 375, height: 667 });
  await page.screenshot({ path: '/tmp/mobile.png', fullPage: true });

  await browser.close();
})();

Test Login Flow

// /tmp/playwright-test-login.js
const { chromium } = require('playwright');

const TARGET_URL = 'http://localhost:3001'; // Auto-detected

(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  await page.goto(`${TARGET_URL}/login`);

  await page.fill('input[name="email"]', 'test@example.com');
  await page.fill('input[name="password"]', 'password123');
  await page.click('button[type="submit"]');

  // Wait for redirect
  await page.waitForURL('**/dashboard');
  console.log('✅ Login successful, redirected to dashboard');

  await browser.close();
})();

Fill and Submit Form

// /tmp/playwright-test-form.js
const { chromium } = require('playwright');

const TARGET_URL = 'http://localhost:3001'; // Auto-detected

(async () => {
  const browser = await chromium.launch({ headless: false, slowMo: 50 });
  const page = await browser.newPage();

  await page.goto(`${TARGET_URL}/contact`);

  await page.fill('input[name="name"]', 'John Doe');
  await page.fill('input[name="email"]', 'john@example.com');
  await page.fill('textarea[name="message"]', 'Test message');
  await page.click('button[type="submit"]');

  // Verify submission
  await page.waitForSelector('.success-message');
  console.log('✅ Form submitted successfully');

  await browser.close();
})();

Check for Broken Links

const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  await page.goto('http://localhost:3000');

  const links = await page.locator('a[href^="http"]').all();
  const results = { working: 0, broken: [] };

  for (const link of links) {
    const href = await link.getAttribute('href');
    try {
      const response = await page.request.head(href);
      if (response.ok()) {
        results.working++;
      } else {
        results.broken.push({ url: href, status: response.status() });
      }
    } catch (e) {
      results.broken.push({ url: href, error: e.message });
    }
  }

  console.log(`✅ Working links: ${results.working}`);
  console.log(`❌ Broken links:`, results.broken);

  await browser.close();
})();

Take Screenshot with Error Handling

const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  try {
    await page.goto('http://localhost:3000', {
      waitUntil: 'networkidle',
      timeout: 10000
    });

    await page.screenshot({
      path: '/tmp/screenshot.png',
      fullPage: true
    });

    console.log('📸 Screenshot saved to /tmp/screenshot.png');
  } catch (error) {
    console.error('❌ Error:', error.message);
  } finally {
    await browser.close();
  }
})();

Test Responsive Design

// /tmp/playwright-test-responsive-full.js
const { chromium } = require('playwright');

const TARGET_URL = 'http://localhost:3001'; // Auto-detected

(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  const viewports = [
    { name: 'Desktop', width: 1920, height: 1080 },
    { name: 'Tablet', width: 768, height: 1024 },
    { name: 'Mobile', width: 375, height: 667 }
  ];

  for (const viewport of viewports) {
    console.log(`Testing ${viewport.name} (${viewport.width}x${viewport.height})`);

    await page.setViewportSize({
      width: viewport.width,
      height: viewport.height
    });

    await page.goto(TARGET_URL);
    await page.waitForTimeout(1000);

    await page.screenshot({
      path: `/tmp/${viewport.name.toLowerCase()}.png`,
      fullPage: true
    });
  }

  console.log('✅ All viewports tested');
  await browser.close();
})();

Inline Execution (Simple Tasks)

For quick one-off tasks, you can execute code inline without creating files:

# Take a quick screenshot
cd $SKILL_DIR && node run.js "
const browser = await chromium.launch({ headless: false });
const page = await browser.newPage();
await page.goto('http://localhost:3001');
await page.screenshot({ path: '/tmp/quick-screenshot.png', fullPage: true });
console.log('Screenshot saved');
await browser.close();
"

When to use inline vs files:

Inline : Quick one-off tasks (screenshot, check if element exists, get page title)
Files : Complex tests, responsive design checks, anything user might want to re-run

Available Helpers

Optional utility functions in lib/helpers.js:

const helpers = require('./lib/helpers');

// Detect running dev servers (CRITICAL - use this first!)
const servers = await helpers.detectDevServers();
console.log('Found servers:', servers);

// Safe click with retry
await helpers.safeClick(page, 'button.submit', { retries: 3 });

// Safe type with clear
await helpers.safeType(page, '#username', 'testuser');

// Take timestamped screenshot
await helpers.takeScreenshot(page, 'test-result');

// Handle cookie banners
await helpers.handleCookieBanner(page);

// Extract table data
const data = await helpers.extractTableData(page, 'table.results');

See lib/helpers.js for full list.

Advanced Usage

For comprehensive Playwright API documentation, see API_REFERENCE.md:

Selectors & Locators best practices
Network interception & API mocking
Authentication & session management
Visual regression testing
Mobile device emulation
Performance testing
Debugging techniques
CI/CD integration

Tips

CRITICAL: Detect servers FIRST - Always run detectDevServers() before writing test code for localhost testing
Use /tmp for test files - Write to /tmp/playwright-test-*.js, never to skill directory or user's project
Parameterize URLs - Put detected/provided URL in a TARGET_URL constant at the top of every script
DEFAULT: Visible browser - Always use headless: false unless user explicitly asks for headless mode
Headless mode - Only use headless: true when user specifically requests "headless" or "background" execution
Slow down: Use slowMo: 100 to make actions visible and easier to follow
Wait strategies: Use waitForURL, , instead of fixed timeouts

Troubleshooting

Playwright not installed:

cd $SKILL_DIR && npm run setup

Module not found: Ensure running from skill directory via run.js wrapper

Browser doesn't open: Check headless: false and ensure display available

Element not found: Add wait: await page.waitForSelector('.element', { timeout: 10000 })

Example Usage

User: "Test if the marketing page looks good"

Claude: I'll test the marketing page across multiple viewports. Let me first detect running servers...
[Runs: detectDevServers()]
[Output: Found server on port 3001]
I found your dev server running on http://localhost:3001

[Writes custom automation script to /tmp/playwright-test-marketing.js with URL parameterized]
[Runs: cd $SKILL_DIR && node run.js /tmp/playwright-test-marketing.js]
[Shows results with screenshots from /tmp/]



User: "Check if login redirects correctly"

Claude: I'll test the login flow. First, let me check for running servers...
[Runs: detectDevServers()]
[Output: Found servers on ports 3000 and 3001]
I found 2 dev servers. Which one should I test?
- http://localhost:3000
- http://localhost:3001

User: "Use 3001"

[Writes login automation to /tmp/playwright-test-login.js]
[Runs: cd $SKILL_DIR && node run.js /tmp/playwright-test-login.js]
[Reports: ✅ Login successful, redirected to /dashboard]

Notes

Each automation is custom-written for your specific request
Not limited to pre-built scripts - any browser task possible
Auto-detects running dev servers to eliminate hardcoded URLs
Test scripts written to /tmp for automatic cleanup (no clutter)
Code executes reliably with proper module resolution via run.js
Progressive disclosure - API_REFERENCE.md loaded only when advanced features needed

Weekly Installs

–

Repository

questfortech-in…e-skills

GitHub Stars

First Seen

–

Security Audits

Gen Agent Trust HubFail SocketPass SnykWarn

通过 LiteLLM 代理让 Claude Code 对接 GitHub Copilot 运行 | 高级变通方案指南

27,600 周安装

Error handling: Always use try-catch for robust automation

Console output: Use console.log() to track progress and show what's happening