Claude Puppeteer Tester Skill

AI-powered web testing made simple - Test any website using natural language commands

🚀 Quick Start (3 Steps)

# 1. Go to your project
cd /path/to/your-project

# 2. Initialize (one command)
npx claude-puppeteer-test init

# 3. Restart Claude Code, then test!
claude "测试 https://your-site.com 的登录表单"
claude "Test the login form at https://your-site.com"

That's it! No installation, no configuration, no git clone. Just run and test.

✨ Features

• 🤖 Natural Language Testing - Describe what you want to test in plain English or Chinese
• 🌐 Real Browser Automation - Uses Puppeteer MCP for realistic testing
• 📸 Automatic Screenshots - Captures key moments automatically
• 📝 Auto-Generated Reports - Saves detailed test results to markdown
• 🔄 Smart Retry Logic - Handles transient failures automatically
• ⚡ One-Command Setup - Ready to test in seconds
• 🎯 Professional Testing - Industry-standard testing methodology
• 📁 Intelligent Path Selection - Asks where to save artifacts based on project structure

📖 How It Works

Traditional Testing:

// Write this manually
const puppeteer = require('puppeteer');
(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://example.com');
  // ... write more code
})();

With Claude Puppeteer Tester:

# Just describe what you want
claude "测试登录表单"

Claude automatically:

1. ✅ Analyzes your project structure
2. ✅ Asks where to save test reports and screenshots (intelligent suggestions based on project)
3. ✅ Understands your request
4. ✅ Launches browser
5. ✅ Finds elements
6. ✅ Performs actions
7. ✅ Verifies results
8. ✅ Saves report to chosen location

📦 Installation

Note: The npm package name is claude-puppeteer-tester-skill, but the command is claude-puppeteer-test (shorter for easier typing).

Method 1: npx (Recommended - No Installation)

cd your-project
npx claude-puppeteer-test init

Method 2: Global Install

npm install -g claude-puppeteer-tester-skill

Then run from any project:

claude-puppeteer-test init

Method 3: Install to Project

cd your-project
npm install claude-puppeteer-tester-skill
npx claude-puppeteer-test init

What init does:

• Checks/installs Puppeteer MCP server
• Creates .claude/ configuration directory
• Sets up skill.md with testing instructions
• Configures MCP server settings
• Test reports and screenshots are created automatically when you run tests

🎯 Usage Examples

Example 1: Simple Login Test

claude "测试 https://example.com/login - 填写用户名'testuser'和密码'pass123'，点击登录，验证成功"

claude "Test https://example.com/login - fill username 'testuser' and password 'pass123', click login, verify success"

Example 2: Form with Validation

claude "测试联系表单：填写所有字段，验证邮箱格式，检查必填项，提交并确认消息"

claude "Test contact form: fill all fields, validate email format, check required fields, submit and confirm message"

Example 3: E-commerce Flow

claude "测试电商结账：添加商品到购物车，查看购物车，进入结账，填写配送信息，确认订单"

claude "Test checkout: add item to cart, view cart, proceed to checkout, fill shipping info, confirm order"

Example 4: Multi-Step User Journey

claude "测试用户注册流程：1. 导航到注册页面 2. 填写用户信息 3. 验证邮箱 4. 提交表单 5. 验证欢迎消息"

claude "Test user registration: 1. Navigate to signup 2. Fill user info 3. Verify email 4. Submit form 5. Verify welcome message"

📊 Test Report Output

After each test, Claude generates a detailed report:

# Test Report

**Date**: 2026-01-27 23:45:00
**Test URL**: https://example.com/login
**Tester**: Claude (Puppeteer MCP)
**Duration**: 2.5 minutes

## Test Summary

- **Total Steps**: 5
- **Passed**: 5
- **Failed**: 0
- **Success Rate**: 100%

## Test Execution Log

### Step 1: Navigate to login page
**Status**: ✅ PASS
**Duration**: 1.2 seconds
**Action**: Navigated to https://example.com/login
**Verification**: URL matches expected

### Step 2: Fill username field
**Status**: ✅ PASS
**Duration**: 0.5 seconds
**Action**: Filled input[name="username"] with 'testuser'
**Verification**: Value matches input
**Screenshot**: test-screenshots/step-2.png

### Step 3: Fill password field
**Status**: ✅ PASS
**Duration**: 0.3 seconds
**Action**: Filled input[name="password"] with 'pass123'
**Verification**: Value matches input
**Screenshot**: test-screenshots/step-3.png

### Step 4: Click login button
**Status**: ✅ PASS
**Duration**: 0.8 seconds
**Action**: Clicked button[type="submit"]
**Verification**: Button clicked, navigation started
**Screenshot**: test-screenshots/step-4.png

### Step 5: Verify successful login
**Status**: ✅ PASS
**Duration**: 1.5 seconds
**Verification**: Success message visible, URL changed to /dashboard
**Screenshot**: test-screenshots/step-5.png

## Issues Found

No issues detected during test execution.

## Conclusion

All test steps passed successfully. The login functionality is working as expected.

🏗️ Project Structure

After npx claude-puppeteer-test init:

your-project/
├── .claude/
│   └── skills/
│       └── puppeteer-web-tester/
│           └── SKILL.md              # Testing skill configuration
│   └── settings.local.json          # MCP Puppeteer server settings
└── your-code/                        # Your existing files

Skill Package Structure:

claude-puppeteer-tester-skill/
├── .claude/
│   └── skills/
│       └── puppeteer-web-tester/
│           ├── SKILL.md       # Main skill file (overview)
│           ├── reference.md   # Detailed API reference
│           └── examples.md    # Usage examples
├── bin/
│   └── cli.js                 # CLI tool
├── docs/
│   ├── SETUP.md               # Setup instructions
│   ├── USAGE_EXAMPLES.md      # More examples
│   └── MCP_TESTING_GUIDE.md   # MCP usage guide
├── package.json
└── README.md

Note: Test results files are created automatically when you run tests:

• test-report.md - Generated after each test run
• test-screenshots/ - Created when tests need screenshots

📁 Intelligent Path Selection

Before running tests, Claude analyzes your project structure and asks where to save test artifacts. This ensures test results integrate seamlessly with your project.

Example interaction:

📁 Where should I save test results?

1. Project root (simplest)
   Save in project root - easiest to find
   → Report: test-report.md
   → Screenshots: test-screenshots/

2. tests/ directory (recommended)
   Integrates with existing test structure
   → Report: tests/test-report.md
   → Screenshots: tests/screenshots/

3. docs/tests/ directory (documentation)
   Keep test results with documentation
   → Report: docs/tests/test-report.md
   → Screenshots: docs/tests/screenshots/

4. Custom paths
   Specify your own paths

How it works:

• Scans your project for common directories (tests/, test/, docs/, etc.)
• Suggests appropriate locations based on what exists
• Creates directories automatically if needed
• Uses your choice for all test reports and screenshots

🎓 Testing Best Practices

✅ DO

• Be specific in your test descriptions
• Use natural language - describe what to test, not how
• Test user workflows - not just individual elements
• Let Claude handle selectors, waiting, and verification
• Check test-report.md after each test run
• Keep tests focused - one user journey per test

❌ DON'T

• Don't write code - describe the test instead
• Don't specify selectors - Claude will find them
• Don't assume implementation details
• Don't test production systems with real data
• Don't skip verification steps

🔧 Advanced Features

Automatic Retry Logic

Every action includes built-in retry logic (max 3 attempts):

// Claude will automatically retry failed actions
claude "点击提交按钮"  // Will retry if click fails
claude "Click submit button"  // Will retry if click fails

Programmatic Verification

Claude prefers code-based verification over visual inspection:

// ✅ This is what Claude does (behind the scenes)
const result = await page.evaluate(() => ({
  successVisible: document.querySelector('.success') !== null,
  buttonText: document.querySelector('button')?.textContent
}));

// ⚠️ Only uses screenshots as fallback
if (!result.successVisible) {
  await page.screenshot({ path: 'verification-failed.png' });
}

Issue Documentation

All issues are automatically documented with:

• Severity level (High/Medium/Low)
• Retry attempts
• Screenshots
• Recommendations

🐛 Troubleshooting

"MCP server not found"

# Fix: Install Puppeteer MCP
claude mcp add puppeteer -- npx -y @modelcontextprotocol/server-puppeteer
# Then restart Claude Code

"Tool not found: puppeteer_navigate"

Cause: Claude Code wasn't restarted after init

Solution:

1. Quit Claude Code completely
2. Restart Claude Code
3. Try again

"Browser fails to launch"

Linux:

sudo apt-get install -y libnss3 libatk-bridge2.0 libcups2 libxkbcommon0 libasound2

macOS:

xcode-select --install

Windows: Run as Administrator

"Element not found"

Solution: Add wait times

claude "测试表单，等待30秒让页面加载"
claude "Test the form, wait 30 seconds for page to load"

📚 Documentation

• Setup Guide - Complete setup instructions
• MCP Testing Guide - Puppeteer MCP usage
• Usage Examples - More examples

🤝 Contributing

Contributions welcome! Please read our contributing guidelines first.

📄 License

MIT License - see LICENSE file for details

🔗 Links

• Puppeteer MCP: https://github.com/modelcontextprotocol/servers/tree/main/src/puppeteer
• Claude Code: https://claude.com/claude-code
• MCP Protocol: https://modelcontextprotocol.io/

Made with ❤️ by Prudent Owl Limited

Powered by Claude • Puppeteer • Model Context Protocol