Chrome DevTools 自动化脚本：Puppeteer 浏览器自动化与性能监控工具

chrome-devtools by mrgoonie/claudekit-skills

480 周安装量

1,900 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/mrgoonie/claudekit-skills --skill chrome-devtools

自动化性能优化测试

🇨🇳中文介绍

Chrome DevTools Agent Skill

通过可执行的 Puppeteer 脚本实现浏览器自动化。所有脚本都输出 JSON，便于解析。

快速开始

重要提示：运行脚本前务必检查 pwd。

安装

步骤 1：安装系统依赖项（仅限 Linux/WSL）

在 Linux/WSL 上，Chrome 需要系统库。请先安装它们：

pwd  # 应显示当前工作目录
cd .claude/skills/chrome-devtools/scripts
./install-deps.sh  # 自动检测操作系统并安装所需库

支持：Ubuntu、Debian、Fedora、RHEL、CentOS、Arch、Manjaro

macOS/Windows：跳过此步骤（依赖项已与 Chrome 捆绑）

步骤 2：安装 Node 依赖项

npm install  # 安装 puppeteer、debug、yargs

步骤 3：安装 ImageMagick（可选，推荐）

ImageMagick 支持自动截图压缩，以保持文件大小在 5MB 以下：

macOS:

brew install imagemagick

Ubuntu/Debian/WSL:

sudo apt-get install imagemagick

广告位招租

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

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

联系我们

链式命令（复用浏览器）

# 使用 --close false 保持浏览器打开
node navigate.js --url https://example.com/login --close false
node fill.js --selector "#email" --value "user@example.com" --close false
node fill.js --selector "#password" --value "secret" --close false
node click.js --selector "button[type=submit]"

# 使用 jq 提取特定字段
node performance.js --url https://example.com | jq '.vitals.LCP'

# 保存到文件
node network.js --url https://example.com --output /tmp/requests.json

在执行任何脚本之前：

使用 pwd 检查当前工作目录
确认在 .claude/skills/chrome-devtools/scripts/ 目录下
如果目录错误，请 cd 到正确位置
对所有输出文件使用绝对路径

pwd  # 应显示：.../chrome-devtools/scripts
# 如果错误：
cd .claude/skills/chrome-devtools/scripts

在截图/捕获操作之后：

使用 ls -lh <output-path> 验证文件已创建
使用 Read 工具读取截图以确认内容
检查 JSON 输出中 success:true
报告文件大小和压缩状态

node screenshot.js --url https://example.com --output ./docs/screenshots/page.png
ls -lh ./docs/screenshots/page.png  # 验证文件存在
# 然后使用 Read 工具进行视觉检查

如果脚本失败：

检查错误信息以查找选择器问题
使用 snapshot.js 发现正确的选择器
如果 CSS 选择器失败，尝试 XPath 选择器
验证元素是否可见且可交互

# CSS 选择器失败
node click.js --url https://example.com --selector ".btn-submit"
# 错误：等待选择器 ".btn-submit" 失败

# 发现正确的选择器
node snapshot.js --url https://example.com | jq '.elements[] | select(.tagName=="BUTTON")'

# 尝试 XPath
node click.js --url https://example.com --selector "//button[contains(text(),'Submit')]"

❌ 工作目录错误 → 输出文件保存到错误位置 ❌ 跳过输出验证 → 静默失败 ❌ 使用复杂 CSS 选择器而不测试 → 选择器错误 ❌ 不检查元素可见性 → 超时错误

✅ 运行脚本前始终验证 pwd ✅ 截图后始终验证输出 ✅ 使用 snapshot.js 发现选择器 ✅ 先用简单命令测试选择器

node evaluate.js --url https://example.com --script "
  Array.from(document.querySelectorAll('.item')).map(el => ({
    title: el.querySelector('h2')?.textContent,
    link: el.querySelector('a')?.href
  }))
" | jq '.result'

PERF=$(node performance.js --url https://example.com)
LCP=$(echo $PERF | jq '.vitals.LCP')
if (( $(echo "$LCP < 2500" | bc -l) )); then
  echo "✓ LCP 通过：${LCP}ms"
else
  echo "✗ LCP 失败：${LCP}ms"
fi

node fill.js --url https://example.com --selector "#search" --value "query" --close false
node click.js --selector "button[type=submit]"

node console.js --url https://example.com --types error,warn --duration 5000 | jq '.messageCount'

所有脚本都支持：

--headless false - 显示浏览器窗口
--close false - 保持浏览器打开以进行链式操作
--timeout 30000 - 设置超时（毫秒）
--wait-until networkidle2 - 等待策略

完整选项请参见 ./scripts/README.md。

所有脚本都向 stdout 输出 JSON：

{
  "success": true,
  "url": "https://example.com",
  ... // 脚本特定数据
}

错误输出到 stderr：

{
  "success": false,
  "error": "错误信息"
}

使用 snapshot.js 来发现选择器：

node snapshot.js --url https://example.com | jq '.elements[] | {tagName, text, selector}'

"Cannot find package 'puppeteer'"

在 scripts 目录下运行：npm install

"error while loading shared libraries: libnss3.so" (Linux/WSL)

缺少系统依赖项
修复：在 scripts 目录下运行 ./install-deps.sh
手动安装：sudo apt-get install -y libnss3 libnspr4 libasound2t64 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1

"Failed to launch the browser process"

检查系统依赖项是否已安装（Linux/WSL）
验证 Chrome 是否已下载：ls ~/.cache/puppeteer
尝试：npm rebuild 然后 npm install

Chrome not found

Puppeteer 在 npm install 期间会自动下载 Chrome
如果失败，手动触发：npx puppeteer browsers install chrome

Element not found

首先获取快照以找到正确的选择器：node snapshot.js --url <url>

增加超时时间：--timeout 60000
更改等待策略：--wait-until load 或 --wait-until domcontentloaded

Blank screenshot

等待页面加载：--wait-until networkidle2
增加超时时间：--timeout 30000

Permission denied on scripts

使其可执行：chmod +x *.sh

Screenshot too large ( >5MB)

安装 ImageMagick 以进行自动压缩
手动设置较低的阈值：--max-size 3
使用 JPEG 格式代替 PNG：--format jpeg --quality 80
捕获特定元素而非整个页面：--selector .main-content

Compression not working

验证 ImageMagick 是否已安装：magick -version 或 convert -version
检查输出 JSON 中文件是否确实被压缩："compressed": true
对于非常大的页面，使用 --selector 仅捕获所需区域

详细指南可在 ./references/ 中找到：

CDP 域参考 - 47 个 Chrome DevTools 协议域
Puppeteer 快速参考 - 完整的 Puppeteer API 模式
性能分析指南 - 核心网页指标优化

使用共享库创建自定义脚本：

import { getBrowser, getPage, closeBrowser, outputJSON } from './lib/browser.js';
// 你的自动化逻辑

const client = await page.createCDPSession();
await client.send('Emulation.setCPUThrottlingRate', { rate: 4 });

高级模式和完整 API 覆盖范围请参见参考文档。

2026 年 1 月 22 日

🇺🇸English

Chrome DevTools Agent Skill

Browser automation via executable Puppeteer scripts. All scripts output JSON for easy parsing.

Quick Start

CRITICAL : Always check pwd before running scripts.

Installation

Step 1: Install System Dependencies (Linux/WSL only)

On Linux/WSL, Chrome requires system libraries. Install them first:

pwd  # Should show current working directory
cd .claude/skills/chrome-devtools/scripts
./install-deps.sh  # Auto-detects OS and installs required libs

Supports: Ubuntu, Debian, Fedora, RHEL, CentOS, Arch, Manjaro

macOS/Windows : Skip this step (dependencies bundled with Chrome)

Step 2: Install Node Dependencies

npm install  # Installs puppeteer, debug, yargs

Step 3: Install ImageMagick (Optional, Recommended)

ImageMagick enables automatic screenshot compression to keep files under 5MB:

macOS:

brew install imagemagick

Ubuntu/Debian/WSL:

sudo apt-get install imagemagick

Verify:

magick -version  # or: convert -version

Without ImageMagick, screenshots >5MB will not be compressed (may fail to load in Gemini/Claude).

Test

node navigate.js --url https://example.com
# Output: {"success": true, "url": "https://example.com", "title": "Example Domain"}

Available Scripts

All scripts are in .claude/skills/chrome-devtools/scripts/

CRITICAL : Always check pwd before running scripts.

Script Usage

./scripts/README.md

Core Automation

navigate.js - Navigate to URLs
screenshot.js - Capture screenshots (full page or element)
click.js - Click elements
fill.js - Fill form fields
evaluate.js - Execute JavaScript in page context

Analysis & Monitoring

snapshot.js - Extract interactive elements with metadata
console.js - Monitor console messages/errors
network.js - Track HTTP requests/responses
performance.js - Measure Core Web Vitals + record traces

Usage Patterns

Single Command

pwd  # Should show current working directory
cd .claude/skills/chrome-devtools/scripts
node screenshot.js --url https://example.com --output ./docs/screenshots/page.png

Important : Always save screenshots to ./docs/screenshots directory.

Automatic Image Compression

Screenshots are automatically compressed if they exceed 5MB to ensure compatibility with Gemini API and Claude Code (which have 5MB limits). This uses ImageMagick internally:

# Default: auto-compress if >5MB
node screenshot.js --url https://example.com --output page.png

# Custom size threshold (e.g., 3MB)
node screenshot.js --url https://example.com --output page.png --max-size 3

# Disable compression
node screenshot.js --url https://example.com --output page.png --no-compress

Compression behavior:

PNG: Resizes to 90% + quality 85 (or 75% + quality 70 if still too large)
JPEG: Quality 80 + progressive encoding (or quality 60 if still too large)
Other formats: Converted to JPEG with compression
Requires ImageMagick installed (see imagemagick skill)

Output includes compression info:

{
  "success": true,
  "output": "/path/to/page.png",
  "compressed": true,
  "originalSize": 8388608,
  "size": 3145728,
  "compressionRatio": "62.50%",
  "url": "https://example.com"
}

Chain Commands (reuse browser)

# Keep browser open with --close false
node navigate.js --url https://example.com/login --close false
node fill.js --selector "#email" --value "user@example.com" --close false
node fill.js --selector "#password" --value "secret" --close false
node click.js --selector "button[type=submit]"

Parse JSON Output

# Extract specific fields with jq
node performance.js --url https://example.com | jq '.vitals.LCP'

# Save to file
node network.js --url https://example.com --output /tmp/requests.json

Execution Protocol

Working Directory Verification

BEFORE executing any script:

Check current working directory with pwd
Verify in .claude/skills/chrome-devtools/scripts/ directory
If wrong directory, cd to correct location
Use absolute paths for all output files

Example:

pwd  # Should show: .../chrome-devtools/scripts
# If wrong:
cd .claude/skills/chrome-devtools/scripts

Output Validation

AFTER screenshot/capture operations:

Verify file created with ls -lh <output-path>
Read screenshot using Read tool to confirm content
Check JSON output for success:true
Report file size and compression status

Example:

node screenshot.js --url https://example.com --output ./docs/screenshots/page.png
ls -lh ./docs/screenshots/page.png  # Verify file exists
# Then use Read tool to visually inspect

5. Restart working directory to the project root.

Error Recovery

If script fails:

Check error message for selector issues
Use snapshot.js to discover correct selectors
Try XPath selector if CSS selector fails
Verify element is visible and interactive

Example:

# CSS selector fails
node click.js --url https://example.com --selector ".btn-submit"
# Error: waiting for selector ".btn-submit" failed

# Discover correct selector
node snapshot.js --url https://example.com | jq '.elements[] | select(.tagName=="BUTTON")'

# Try XPath
node click.js --url https://example.com --selector "//button[contains(text(),'Submit')]"

Common Mistakes

❌ Wrong working directory → output files go to wrong location ❌ Skipping output validation → silent failures ❌ Using complex CSS selectors without testing → selector errors ❌ Not checking element visibility → timeout errors

✅ Always verify pwd before running scripts ✅ Always validate output after screenshots ✅ Use snapshot.js to discover selectors ✅ Test selectors with simple commands first

Common Workflows

Web Scraping

node evaluate.js --url https://example.com --script "
  Array.from(document.querySelectorAll('.item')).map(el => ({
    title: el.querySelector('h2')?.textContent,
    link: el.querySelector('a')?.href
  }))
" | jq '.result'

Performance Testing

PERF=$(node performance.js --url https://example.com)
LCP=$(echo $PERF | jq '.vitals.LCP')
if (( $(echo "$LCP < 2500" | bc -l) )); then
  echo "✓ LCP passed: ${LCP}ms"
else
  echo "✗ LCP failed: ${LCP}ms"
fi

Form Automation

node fill.js --url https://example.com --selector "#search" --value "query" --close false
node click.js --selector "button[type=submit]"

Error Monitoring

node console.js --url https://example.com --types error,warn --duration 5000 | jq '.messageCount'

Script Options

All scripts support:

--headless false - Show browser window
--close false - Keep browser open for chaining
--timeout 30000 - Set timeout (milliseconds)
--wait-until networkidle2 - Wait strategy

See ./scripts/README.md for complete options.

Output Format

All scripts output JSON to stdout:

{
  "success": true,
  "url": "https://example.com",
  ... // script-specific data
}

Errors go to stderr:

{
  "success": false,
  "error": "Error message"
}

Finding Elements

Use snapshot.js to discover selectors:

node snapshot.js --url https://example.com | jq '.elements[] | {tagName, text, selector}'

Troubleshooting

Common Errors

"Cannot find package 'puppeteer'"

Run: npm install in the scripts directory

"error while loading shared libraries: libnss3.so" (Linux/WSL)

Missing system dependencies
Fix: Run ./install-deps.sh in scripts directory
Manual install: sudo apt-get install -y libnss3 libnspr4 libasound2t64 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1

"Failed to launch the browser process"

Check system dependencies installed (Linux/WSL)
Verify Chrome downloaded: ls ~/.cache/puppeteer
Try: npm rebuild then npm install

Chrome not found

Puppeteer auto-downloads Chrome during npm install
If failed, manually trigger: npx puppeteer browsers install chrome

Script Issues

Element not found

Get snapshot first to find correct selector: node snapshot.js --url <url>

Script hangs

Increase timeout: --timeout 60000
Change wait strategy: --wait-until load or --wait-until domcontentloaded

Blank screenshot

Wait for page load: --wait-until networkidle2
Increase timeout: --timeout 30000

Permission denied on scripts

Make executable: chmod +x *.sh

Screenshot too large ( >5MB)

Install ImageMagick for automatic compression
Manually set lower threshold: --max-size 3
Use JPEG format instead of PNG: --format jpeg --quality 80
Capture specific element instead of full page: --selector .main-content

Compression not working

Verify ImageMagick installed: magick -version or convert -version
Check file was actually compressed in output JSON: "compressed": true
For very large pages, use --selector to capture only needed area

Reference Documentation

Detailed guides available in ./references/:

CDP Domains Reference - 47 Chrome DevTools Protocol domains
Puppeteer Quick Reference - Complete Puppeteer API patterns
Performance Analysis Guide - Core Web Vitals optimization

Advanced Usage

Custom Scripts

Create custom scripts using shared library:

import { getBrowser, getPage, closeBrowser, outputJSON } from './lib/browser.js';
// Your automation logic

Direct CDP Access

const client = await page.createCDPSession();
await client.send('Emulation.setCPUThrottlingRate', { rate: 4 });

See reference documentation for advanced patterns and complete API coverage.

External Resources

Weekly Installs

472

Repository

mrgoonie/claude…t-skills

GitHub Stars

1.9K

First Seen

Jan 22, 2026

Security Audits

Gen Agent Trust HubWarn SocketPass SnykFail

Installed on

opencode388

gemini-cli365

claude-code349

codex347

github-copilot313

cursor289

Lark Task CLI 任务管理工具 - 飞书任务创建、分配、更新与协作完整指南

7,100 周安装

Chrome DevTools 自动化脚本：Puppeteer 浏览器自动化与性能监控工具

🇨🇳中文介绍

Chrome DevTools Agent Skill

快速开始

安装

步骤 1：安装系统依赖项（仅限 Linux/WSL）

步骤 2：安装 Node 依赖项

步骤 3：安装 ImageMagick（可选，推荐）

相关 Skills

测试

可用脚本

脚本用法

核心自动化

分析与监控

使用模式

单条命令

自动图像压缩

链式命令（复用浏览器）

解析 JSON 输出

执行协议

工作目录验证

输出验证

错误恢复

常见错误

常见工作流

网页抓取

性能测试

表单自动化

错误监控

脚本选项

输出格式

查找元素

故障排除

常见错误

脚本问题

参考文档

高级用法

自定义脚本

直接 CDP 访问

外部资源

🇺🇸English

Chrome DevTools Agent Skill

Quick Start

Installation

Step 1: Install System Dependencies (Linux/WSL only)

Step 2: Install Node Dependencies

Step 3: Install ImageMagick (Optional, Recommended)

Test

Available Scripts

Script Usage

Core Automation

Analysis & Monitoring

Usage Patterns

Single Command

Automatic Image Compression

Chain Commands (reuse browser)

Parse JSON Output

Execution Protocol

Working Directory Verification

Output Validation

Error Recovery

Common Mistakes

Common Workflows

Web Scraping

Performance Testing

Form Automation

Error Monitoring

Script Options

Output Format

Finding Elements

Troubleshooting

Common Errors

Script Issues

Reference Documentation

Advanced Usage

Custom Scripts

Direct CDP Access

External Resources

最新 Skills