web-automation

ABOUTME: 使用 Playwright 进行网页自动化、调试和端到端测试的 Claude Code 技能

ABOUTME: 涵盖交互式自动化、被动监控、截图和安全验证

使用 Playwright 进行网页自动化

使用 Python 或 JavaScript/TypeScript 进行浏览器自动化和调试。

详细模式：参见 references/python-patterns.md 和 references/javascript-patterns.md

---

快速参考

任务	辅助脚本
登录 / 填写表单	examples/python/form_interaction.py
截图	examples/python/screenshot_capture.py
处理 Cookie 同意	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

务必先运行辅助脚本：

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

---

操作模式

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

---

何时调用（主动触发）

1. 验证 UI 修复 - 更改前端代码后
2. 测试表单字段/下拉菜单 - 验证是否显示正确的值
3. 确认视觉更改 - 截图
4. 重现错误 - 自动执行重现步骤
5. 安全验证 - Gemini/静态分析发现问题后

---

🔄 恢复会话检查点

┌─────────────────────────────────────────────────────────────┐
│  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            │
└─────────────────────────────────────────────────────────────┘

---

决策流程

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

---

重要：处理叠加层

叠加层会阻碍自动化。 每次调用 page.goto() 后都要将其关闭：

Python（快速模式）

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

# Dismiss 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

终极方案（移除所有叠加层）

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

---

核心模式

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

JavaScript

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

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

---

常见操作

操作	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"]', '[email protected]')	await page.fill('input[name="email"]', '[email protected]')
选择下拉菜单	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')

---

选择器策略（优先级从高到低）

1. 基于角色：page.get_by_role('button', name='Submit')
2. 基于文本：page.get_by_text('Click me')
3. 测试 ID：page.get_by_test_id('submit-btn')
4. CSS：page.locator('.btn-primary')
5. XPath（最后手段）：page.locator('//button[@type="submit"]')

---

验证清单

验证内容	方法
下拉菜单的值	page.locator('select').input_value()
输入文本	page.locator('input').input_value()
元素是否可见	page.locator('.element').is_visible()
文本内容	page.locator('.element').text_content()
页面 URL	操作后查看 page.url

---

被动调试脚本

脚本	用途	示例
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

安全验证

# After Gemini found sensitive data logging
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

---

视觉对比

绝不要说“我无法进行视觉浏览”。请改为：

# 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

---

语言选择

使用场景	推荐语言	原因
现有 JS/TS 项目	JavaScript	工具链一致
现有 Python 项目	Python	工具链一致
快速脚本	Python	使用 uv run 设置更简单
测试套件	JavaScript	@playwright/test 框架更出色

---

测试框架集成

请参阅 references/test-framework.md，了解：

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

# Detect and run tests with server
uv run ~/.claude/skills/web-automation/scripts/test_utils.py . --run --with-server

---

常见问题

问题	解决方案
覆盖层阻止点击	每次页面加载后都调用覆盖层关闭功能
JS 加载前检查 DOM	始终先执行 wait_for_load_state('networkidle')
CI 中使用有头浏览器	始终使用 headless: true
选择器不稳定	优先使用角色/文本选择器，而非 CSS 类
竞态条件	使用显式等待，而非 wait_for_timeout

---

前置条件

Python

脚本包含内联依赖（PEP 723）；uv run 会自动安装这些依赖。

JavaScript

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

---

运行端到端测试

JavaScript

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

Python

pip install pytest-playwright
pytest tests/