web-automation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ABOUTME: Claude Code skill for web automation, debugging, and E2E testing using Playwright

关于我：基于Playwright的Claude Code技能，用于网页自动化、调试和E2E测试

ABOUTME: Covers interactive automation, passive monitoring, screenshots, and security verification

关于我：覆盖交互自动化、被动监控、截图和安全验证能力

Web Automation with Playwright

基于Playwright的网页自动化

Browser automation and debugging using Playwright in Python or JavaScript/TypeScript.

Detailed patterns: See

references/python-patterns.md

and

references/javascript-patterns.md

使用Python或JavaScript/TypeScript基于Playwright实现浏览器自动化和调试。

详细模式参考：查看

references/python-patterns.md

和

references/javascript-patterns.md

Quick Reference

快速参考

Task	Helper Script
Login / fill forms	`examples/python/form_interaction.py`
Take screenshots	`examples/python/screenshot_capture.py`
Handle cookie consent	`scripts/cookie_consent.py`
Discover page elements	`examples/python/element_discovery.py`
Capture network traffic	`scripts/network_inspector.py`
Debug console errors	`scripts/console_debugger.py`
Full debug (network+console)	`scripts/combined_debugger.py`
Compare websites visually	`examples/python/visual_compare.py`

Always run helpers first:

bash

uv run ~/.claude/skills/web-automation/examples/python/element_discovery.py http://localhost:3000
uv run ~/.claude/skills/web-automation/examples/python/screenshot_capture.py http://localhost:3000 --output /tmp/shots

任务	辅助脚本
登录/填写表单	`examples/python/form_interaction.py`
截图	`examples/python/screenshot_capture.py`
处理Cookie consent弹窗	`scripts/cookie_consent.py`
发现页面元素	`examples/python/element_discovery.py`
捕获网络流量	`scripts/network_inspector.py`
调试控制台错误	`scripts/console_debugger.py`
全量调试（网络+控制台）	`scripts/combined_debugger.py`
网站视觉对比	`examples/python/visual_compare.py`

请始终优先运行辅助脚本：

bash

uv run ~/.claude/skills/web-automation/examples/python/element_discovery.py http://localhost:3000
uv run ~/.claude/skills/web-automation/examples/python/screenshot_capture.py http://localhost:3000 --output /tmp/shots

Modes of Operation

运行模式

Mode	When to Use	Example
Interactive	Click, type, navigate	Login flow, form submission
Passive	Observe only	Network capture, console monitoring
E2E Testing	Automated test suites	Playwright Test framework

模式	使用场景	示例
交互模式	点击、输入、导航操作	登录流程、表单提交
被动模式	仅观测	网络捕获、控制台监控
E2E测试	自动化测试套件	Playwright Test框架

When to Invoke (Proactive)

主动触发场景

Verifying UI fixes - After changing frontend code
Testing form fields/dropdowns - Verify correct values display
Confirming visual changes - Take screenshots
Reproducing bugs - Automate steps to reproduce
Security verification - After Gemini/static analysis finds issues

UI修复验证 - 前端代码变更后
表单字段/下拉框测试 - 验证展示值正确
视觉变更确认 - 截图对比
Bug复现 - 自动化执行复现步骤
安全验证 - Gemini/静态分析发现问题后

🔄 RESUMED SESSION CHECKPOINT

🔄 会话恢复检查点

┌─────────────────────────────────────────────────────────────┐
│  SESSION RESUMED - WEB AUTOMATION VERIFICATION              │
│                                                             │
│  1. Was I in the middle of browser automation?              │
│     → Run: ps aux | grep -E "chromium|playwright|node"      │
│                                                             │
│  2. Were there UI verification tasks pending?               │
│     → Check summary for "verify", "test UI", "screenshot"   │
│                                                             │
│  3. Did previous automation capture any findings?           │
│     → Check /tmp/ for screenshots, debug outputs            │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│  会话已恢复 - 网页自动化验证检查                            │
│                                                             │
│  1. 我是否正在执行浏览器自动化任务？                         │
│     → 执行命令: ps aux | grep -E "chromium|playwright|node"  │
│                                                             │
│  2. 是否有未完成的UI验证任务？                               │
│     → 检查摘要中是否包含"verify"、"test UI"、"screenshot"  |
│                                                             │
│  3. 之前的自动化是否捕获了结果？                             │
│     → 检查/tmp/目录下的截图、调试输出文件                    │
└─────────────────────────────────────────────────────────────┘

Decision Flow

决策流程

Task:
    +-- Need to interact? (click, type, submit) → Interactive mode
    +-- Just observe/capture? → Passive mode (combined_debugger.py)
    +-- Security verification? → Passive mode + grep for sensitive patterns

任务:
    +-- 需要交互？（点击、输入、提交） → 交互模式
    +-- 仅观测/捕获？ → 被动模式（使用combined_debugger.py）
    +-- 安全验证？ → 被动模式 + 敏感特征grep扫描

CRITICAL: Handling Overlays

关键注意点：处理覆盖层

Overlays WILL block automation. Always dismiss after

page.goto()

覆盖层一定会阻塞自动化操作，请在

page.goto()

执行后始终先关闭覆盖层：

Python (Quick Pattern)

Python 快速实现

python

page.goto('https://example.com')
page.wait_for_load_state('networkidle')

python

page.goto('https://example.com')
page.wait_for_load_state('networkidle')

Dismiss cookie consent

关闭Cookie consent弹窗

for sel in ['button:has-text("Accept all")', '[class*="cookie"] button[class*="accept"]']: try: btn = page.locator(sel).first if btn.is_visible(timeout=2000): btn.click() break except: continue

undefined

for sel in ['button:has-text("Accept all")', '[class*="cookie"] button[class*="accept"]']: try: btn = page.locator(sel).first if btn.is_visible(timeout=2000): btn.click() break except: continue

undefined

Nuclear Option (Remove All Overlays)

终极方案：移除所有覆盖层

python

page.evaluate('''() => {
    const patterns = ['cookie', 'consent', 'modal', 'overlay', 'popup', 'backdrop'];
    for (const p of patterns) {
        document.querySelectorAll(`[class*="${p}"], [id*="${p}"]`).forEach(el => {
            if (getComputedStyle(el).position === 'fixed') el.remove();
        });
    }
    document.body.style.overflow = 'auto';
}''')

Full implementation: See

references/python-patterns.md

python

page.evaluate('''() => {
    const patterns = ['cookie', 'consent', 'modal', 'overlay', 'popup', 'backdrop'];
    for (const p of patterns) {
        document.querySelectorAll(`[class*="${p}"], [id*="${p}"]`).forEach(el => {
            if (getComputedStyle(el).position === 'fixed') el.remove();
        });
    }
    document.body.style.overflow = 'auto';
}''')

完整实现：参考

references/python-patterns.md

Core Patterns

核心模式

Python

python

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page()
    page.goto('http://localhost:3000')
    page.wait_for_load_state('networkidle')  # CRITICAL
    # ... automation
    browser.close()

python

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page()
    page.goto('http://localhost:3000')
    page.wait_for_load_state('networkidle')  # 关键步骤
    # ... 自动化逻辑
    browser.close()

JavaScript

javascript

import { test, expect } from '@playwright/test';

test('example', async ({ page }) => {
  await page.goto('/');
  await page.waitForLoadState('networkidle');
  await expect(page.locator('.element')).toBeVisible();
});

javascript

import { test, expect } from '@playwright/test';

test('example', async ({ page }) => {
  await page.goto('/');
  await page.waitForLoadState('networkidle');
  await expect(page.locator('.element')).toBeVisible();
});

Common Operations

常用操作

Operation	Python	JavaScript
Screenshot	`page.screenshot(path='/tmp/s.png')`	`await page.screenshot({ path: '/tmp/s.png' })`
Full page	`page.screenshot(path='/tmp/s.png', full_page=True)`	`await page.screenshot({ path: '/tmp/s.png', fullPage: true })`
Fill input	`page.fill('input[name="email"]', 'x@y.com')`	`await page.fill('input[name="email"]', 'x@y.com')`
Select dropdown	`page.select_option('select#id', 'value')`	`await page.selectOption('select#id', 'value')`
Click	`page.click('button[type="submit"]')`	`await page.click('button[type="submit"]')`
Wait network	`page.wait_for_load_state('networkidle')`	`await page.waitForLoadState('networkidle')`
Wait element	`page.wait_for_selector('.result')`	`await page.waitForSelector('.result')`

操作	Python实现	JavaScript实现
截图	`page.screenshot(path='/tmp/s.png')`	`await page.screenshot({ path: '/tmp/s.png' })`
全页截图	`page.screenshot(path='/tmp/s.png', full_page=True)`	`await page.screenshot({ path: '/tmp/s.png', fullPage: true })`
填写输入框	`page.fill('input[name="email"]', 'x@y.com')`	`await page.fill('input[name="email"]', 'x@y.com')`
选择下拉框	`page.select_option('select#id', 'value')`	`await page.selectOption('select#id', 'value')`
点击	`page.click('button[type="submit"]')`	`await page.click('button[type="submit"]')`
等待网络空闲	`page.wait_for_load_state('networkidle')`	`await page.waitForLoadState('networkidle')`
等待元素加载	`page.wait_for_selector('.result')`	`await page.waitForSelector('.result')`

Selector Strategies (Order of Preference)

选择器优先级策略

Role-based:

page.get_by_role('button', name='Submit')

Text-based:
```
page.get_by_text('Click me')
```
Test IDs:
```
page.get_by_test_id('submit-btn')
```
CSS:
```
page.locator('.btn-primary')
```

XPath (last resort):

page.locator('//button[@type="submit"]')

基于角色：

page.get_by_role('button', name='Submit')

基于文本：
```
page.get_by_text('Click me')
```
测试ID：
```
page.get_by_test_id('submit-btn')
```
CSS选择器：
```
page.locator('.btn-primary')
```

XPath（最后选择）：

page.locator('//button[@type="submit"]')

Verification Checklist

验证检查清单

What to Verify	Approach
Dropdown value	`page.locator('select').input_value()`
Input text	`page.locator('input').input_value()`
Element visible	`page.locator('.element').is_visible()`
Text content	`page.locator('.element').text_content()`
Page URL	`page.url` after action

验证内容	实现方式
下拉框值	`page.locator('select').input_value()`
输入框文本	`page.locator('input').input_value()`
元素可见性	`page.locator('.element').is_visible()`
文本内容	`page.locator('.element').text_content()`
页面URL	操作完成后读取 `page.url`

Passive Debugging Scripts

被动调试脚本

Script	Purpose	Example
`combined_debugger.py`	Network + Console + Errors	`uv run ... --duration 30 --output /tmp/debug.json`
`network_inspector.py`	Network only	`uv run ... --errors-only`
`console_debugger.py`	Console/errors only	`uv run ... --with-stack-traces`

脚本	用途	示例
`combined_debugger.py`	网络+控制台+错误捕获	`uv run ... --duration 30 --output /tmp/debug.json`
`network_inspector.py`	仅网络捕获	`uv run ... --errors-only`
`console_debugger.py`	仅控制台/错误捕获	`uv run ... --with-stack-traces`

Security Verification

安全验证

bash

undefined

bash

undefined

After Gemini found sensitive data logging

当Gemini发现敏感数据日志问题后执行

uv run ~/.claude/skills/web-automation/scripts/console_debugger.py
http://localhost:3000 --duration 60 --output /tmp/security.json

grep -i "password|token|secret|bearer" /tmp/security.json

---

uv run ~/.claude/skills/web-automation/scripts/console_debugger.py
http://localhost:3000 --duration 60 --output /tmp/security.json

grep -i "password|token|secret|bearer" /tmp/security.json

---

Visual Comparison

视觉对比

NEVER say "I cannot visually browse". Instead:

bash

undefined

永远不要说"我无法视觉浏览"，而是使用以下方式：

bash

undefined

Compare two sites

对比两个站点

uv run ~/.claude/skills/web-automation/examples/python/visual_compare.py
https://reference-site.com
http://localhost:3000
--output /tmp/compare

Then read the screenshots using Read tool

然后使用读取工具读取生成的截图

---

---

Language Selection

语言选择

Use Case	Recommended	Reason
Existing JS/TS project	JavaScript	Consistent tooling
Existing Python project	Python	Consistent tooling
Quick scripts	Python	Simpler setup with `uv run`
Test suites	JavaScript	Better `@playwright/test` framework

使用场景	推荐语言	原因
现有JS/TS项目	JavaScript	工具链统一
现有Python项目	Python	工具链统一
快速脚本开发	Python	使用 `uv run` 启动更简单
测试套件开发	JavaScript	`@playwright/test` 框架支持更完善

Test Framework Integration

测试框架集成

See

references/test-framework.md

for:

Unified test runner (
```
test_utils.py
```
)
Server auto-detection and startup
Framework detection (Playwright, Jest, pytest, etc.)

bash

undefined

查看

references/test-framework.md

了解以下内容：

统一测试运行器（
```
test_utils.py
```
）
服务自动检测和启动
框架检测（Playwright、Jest、pytest等）

bash

undefined

Detect and run tests with server

检测并启动服务运行测试

uv run ~/.claude/skills/web-automation/scripts/test_utils.py . --run --with-server

---

uv run ~/.claude/skills/web-automation/scripts/test_utils.py . --run --with-server

---

Common Pitfalls

常见坑点

Pitfall	Solution
Overlay blocking clicks	Call overlay dismissal after EVERY page load
DOM inspection before JS loads	Always `wait_for_load_state('networkidle')` first
Headful browser in CI	Always use `headless: true`
Flaky selectors	Prefer role/text selectors over CSS classes
Race conditions	Use explicit waits, not `wait_for_timeout`

坑点	解决方案
覆盖层阻塞点击操作	每次页面加载后都调用覆盖层关闭逻辑
JS加载完成前就执行DOM检测	始终先执行 `wait_for_load_state('networkidle')`
CI环境中使用有头浏览器	始终设置 `headless: true`
选择器不稳定	优先使用角色/文本选择器，而非CSS类选择器
竞态条件	使用显式等待，不要用 `wait_for_timeout`

Prerequisites

前置依赖

Python

Scripts include inline dependencies (PEP 723);

uv run

auto-installs them.

脚本内置了行内依赖（PEP 723标准）；

uv run

会自动安装依赖。

JavaScript

bash

npm init -y
npm install -D @playwright/test
npx playwright install chromium

bash

npm init -y
npm install -D @playwright/test
npx playwright install chromium

Running E2E Tests

运行E2E测试

JavaScript

bash

npx playwright test                    # Run all
npx playwright test --ui               # UI mode
npx playwright test --headed           # See browser

bash

npx playwright test                    # 运行所有测试
npx playwright test --ui               # UI模式
npx playwright test --headed           # 显示浏览器窗口

Python

bash

pip install pytest-playwright
pytest tests/

bash

pip install pytest-playwright
pytest tests/