web-validation（网络验证）

Web Validation Skill

Overview

This skill provides comprehensive methodology for validating web applications, detecting JavaScript errors, monitoring browser console output, capturing screenshots, and testing across mobile and desktop viewports with authentication support.

Key Capabilities:

• Automated JavaScript error detection with categorization
• Browser console log capture (errors, warnings, info)
• Network request monitoring and failure detection
• Performance metrics collection
• Authentication support for protected pages (NEW)
• Screenshot capture for mobile and desktop (NEW)
• React hydration error detection (#185) (NEW)
• Multi-viewport testing (14 device presets) (NEW)
• HTML/CSS validation
• Automated testing with headless browsers

When to Apply This Skill

Use this skill when:

• Validating web-based dashboards (e.g., dashboard.py)
• Detecting JavaScript syntax errors automatically
• Monitoring console output without manual browser inspection
• Testing web applications before deployment
• Debugging web page issues
• Ensuring cross-browser compatibility
• Validating after code changes to web components
• Testing authenticated/protected pages
• Capturing visual evidence for debugging
• Testing responsive design across devices
• Detecting React hydration mismatches

Authentication Support (NEW)

Form-Based Authentication

Validate protected pages by automatically logging in:

from lib.web_page_validator import WebPageValidator, AuthConfig

auth = AuthConfig(
    login_url="http://localhost:3000/auth/signin",
    email="test@example.com",
    password="TestPass123!",
    email_selector='input[type="email"]',
    password_selector='input[type="password"]',
    submit_selector='button[type="submit"]',
    post_login_wait=2.0
)

with WebPageValidator(auth_config=auth) as validator:
    validator.authenticate()
    result = validator.validate_url('http://localhost:3000/dashboard')

Environment Variables

Credentials can be set via environment variables for CI/CD:

export TEST_EMAIL="test@example.com"
export TEST_PASSWORD="TestPass123!"

Multi-Page Authentication Flow

# Validate public and protected pages in one session
results = validator.validate_pages_with_auth(
    public_pages=[
        ("http://localhost:3000/", "Home"),
        ("http://localhost:3000/auth/signin", "Sign In"),
    ],
    protected_pages=[
        ("http://localhost:3000/dashboard", "Dashboard"),
        ("http://localhost:3000/settings", "Settings"),
    ]
)

Screenshot Capture (NEW)

Automatic Screenshots

Capture screenshots on validation for visual evidence:

from lib.web_page_validator import WebPageValidator, ScreenshotConfig, ViewportConfig

screenshot_config = ScreenshotConfig(
    enabled=True,
    output_directory=".claude/screenshots",
    capture_on_error=True,
    capture_on_success=False,
    full_page=False
)

with WebPageValidator(screenshot_config=screenshot_config) as validator:
    result = validator.validate_url('http://localhost:3000')
    for ss in result.screenshots:
        print(f"Screenshot: {ss.file_path}")

Multi-Viewport Screenshots

Capture screenshots across multiple devices:

python ${CLAUDE_PLUGIN_ROOT}/lib/web_page_validator.py http://localhost:3000 --viewport all --screenshot

Screenshot Naming Convention

Files are named: {page_name}_{viewport}_{timestamp}.png

• home_desktop_20251204_143022.png
• dashboard_mobile_20251204_143025.png

Mobile and Responsive Testing (NEW)

Available Device Presets

Mobile-First Testing

from lib.web_page_validator import WebPageValidator, ViewportConfig

# Test on mobile viewport
validator = WebPageValidator(default_viewport=ViewportConfig.mobile())
result = validator.validate_url('http://localhost:3000')

# Test all viewports
results = validator.validate_all_viewports('http://localhost:3000')

CLI Mobile Testing

# Mobile viewport
python ${CLAUDE_PLUGIN_ROOT}/lib/web_page_validator.py http://localhost:3000 --viewport mobile

# Tablet viewport
python ${CLAUDE_PLUGIN_ROOT}/lib/web_page_validator.py http://localhost:3000 --viewport tablet

# All viewports
python ${CLAUDE_PLUGIN_ROOT}/lib/web_page_validator.py http://localhost:3000 --viewport all

# Custom dimensions
python ${CLAUDE_PLUGIN_ROOT}/lib/web_page_validator.py http://localhost:3000 --viewport-width 414 --viewport-height 896

React Hydration Error Detection (NEW)

What is Hydration Error #185?

React hydration errors occur when server-rendered HTML doesn't match client-rendered content. This causes:

• Minified React error #185
• "Something went wrong" error boundary
• Content flickering or missing UI elements

Automatic Detection

The validator automatically detects:

1. Console messages containing "#185" or "hydration"
2. Error boundary UI ("Something went wrong")
3. React Error Overlay presence
4. Next.js hydration warnings

result = validator.validate_url('http://localhost:3000')

if result.has_react_hydration_error:
    print("[CRITICAL] React hydration mismatch detected!")

if result.error_boundary_visible:
    print("[WARN] Error boundary is visible to users!")

Error Categories

Errors are automatically categorized:

• REACT_HYDRATION - React #185 and hydration mismatches
• JAVASCRIPT_SYNTAX - SyntaxError
• JAVASCRIPT_RUNTIME - TypeError, ReferenceError
• NETWORK_FAILURE - Failed HTTP requests
• UNCAUGHT_EXCEPTION - Unhandled exceptions
• CONSOLE_ERROR - Generic console.error

Validation Methodology

1. Automated Browser Testing

Approach: Use headless browser automation to capture real browser behavior

Tools:

• Selenium WebDriver: Industry standard for browser automation
• Playwright: Modern alternative with better API
• Chrome DevTools Protocol: Direct browser control

Implementation:

from lib.web_page_validator import WebPageValidator

with WebPageValidator(headless=True) as validator:
    result = validator.validate_url('http://127.0.0.1:5000')

    if not result.success:
        print(f"Found {len(result.console_errors)} errors")
        for error in result.console_errors:
            print(f"  - {error.message}")

2. Console Log Monitoring

Types of Console Logs:

• Errors: Critical issues that break functionality
• Warnings: Potential problems that should be addressed
• Info: Informational messages for debugging
• Logs: General debug output

Capture Strategy:

// Enable console capture in browser
chrome_options.set_capability('goog:loggingPrefs', {'browser': 'ALL'})

// Retrieve logs after page load
logs = driver.get_log('browser')
for log in logs:
    if log['level'] == 'SEVERE':
        # Critical error detected
        handle_error(log['message'])

3. JavaScript Error Detection

Common JavaScript Error Patterns:

• SyntaxError: Invalid JavaScript syntax
• ReferenceError: Undefined variables or functions
• TypeError: Invalid type operations
• Uncaught exceptions: Unhandled runtime errors

Detection Methods:

1. Browser console logs (level: SEVERE)
2. window.onerror event handler
3. Promise rejection tracking
4. Resource loading failures

Example Detection:

# Check for SyntaxError in console logs
for log in console_logs:
    if 'SyntaxError' in log.message:
        # Extract line number and source
        # Parse error message
        # Generate fix suggestions

4. Network Request Monitoring

What to Monitor:

• Failed HTTP requests (404, 500, etc.)
• Timeout errors
• CORS issues
• Missing resources (CSS, JS, images)
• Slow-loading resources

Performance Metrics:

// Collect Resource Timing data
const resources = performance.getEntriesByType('resource');
resources.forEach(r => {
    if (r.transferSize === 0 && r.duration > 0) {
        // Resource failed to load
        console.error(`Failed to load: ${r.name}`);
    }
});

5. Performance Validation

Key Metrics:

• Load Time: Total page load duration
• DOM Ready: Time until DOM is interactive
• First Contentful Paint: Time until first content renders
• Resource Count: Number of loaded resources
• Page Size: Total transfer size

Thresholds:

• Load time < 3 seconds (good)
• Load time 3-5 seconds (acceptable)
• Load time > 5 seconds (needs optimization)

Validation Workflow

Pre-Deployment Validation

Step 1: Start Web Server

python ${CLAUDE_PLUGIN_ROOT}/lib/dashboard.py --no-browser --port 5000 &

Step 2: Wait for Server Ready

import time
import urllib.request

def wait_for_server(url, timeout=30):
    start = time.time()
    while time.time() - start < timeout:
        try:
            urllib.request.urlopen(url, timeout=1)
            return True
        except:
            time.sleep(0.5)
    return False

wait_for_server('http://127.0.0.1:5000')

Step 3: Run Validation

python ${CLAUDE_PLUGIN_ROOT}/lib/web_page_validator.py http://127.0.0.1:5000 --verbose

Step 4: Analyze Results

if result.success:
    print("[OK] No errors detected")
else:
    print(f"[ERROR] Found {len(result.console_errors)} errors")
    # Auto-fix or report to user

Continuous Validation

Integration Points:

1. On dashboard startup: Automatically validate after server starts
2. After code changes: Run validation in git pre-commit hook
3. Scheduled monitoring: Periodic validation of running dashboards
4. CI/CD pipeline: Automated testing before deployment

Error Analysis and Auto-Fix

Common Issues and Fixes:

1. Literal Newlines in JavaScript Strings

# Problem: csvContent = 'Header\n'  # Python processes \n
# Fix: csvContent = r'Header\n'     # Raw string preserves \n

2. Template Literal Interpolation

// Problem: `Value: $0`  # Tries to interpolate $0
// Fix: `Value: \$0`     # Escape the dollar sign

3. Missing Resource Files

# Problem: 404 errors for CSS/JS files
# Fix: Check file paths and ensure resources exist

4. CORS Issues

# Problem: Cross-origin request blocked
# Fix: Add CORS headers to Flask app
from flask_cors import CORS
CORS(app)

Best Practices

1. Validation Coverage

Essential Checks:

• Page loads successfully (HTTP 200)
• No JavaScript syntax errors
• No console errors
• All resources load (CSS, JS, images)
• Page title is correct
• Load time is acceptable (< 5s)

Recommended Checks:

• No console warnings
• Performance metrics within thresholds
• Mobile responsiveness
• Accessibility compliance
• Cross-browser compatibility

2. Error Reporting

Report Structure:

=== WEB PAGE VALIDATION REPORT ===
URL: http://127.0.0.1:5000
Status: FAILED
Load Time: 2.34s

CONSOLE ERRORS (3):
1. [SEVERE] Uncaught SyntaxError: Invalid or unexpected token
   Source: http://127.0.0.1:5000/:1827
   Time: 2025-11-06T09:00:00

JAVASCRIPT ERRORS (1):
1. Uncaught SyntaxError: Invalid or unexpected token at line 1827

RECOMMENDATIONS:
1. Fix JavaScript syntax errors in source files
2. Use Python raw strings (r'...') for JavaScript escape sequences
3. Validate JavaScript code before deployment

3. Automated Remediation

When Auto-Fix is Safe:

• String escaping issues (add raw strings)
• Missing CORS headers (add to Flask config)
• Outdated dependencies (update requirements.txt)
• Simple syntax errors (apply known patterns)

When Manual Review Required:

• Logic errors in JavaScript
• Complex refactoring needed
• Security-related issues
• Breaking changes to API

4. Integration with Quality Control

Quality Score Impact:

• 0 errors: Full credit (20/20 points)
• 1-2 warnings: Minor deduction (18/20 points)
• 1-2 errors: Moderate deduction (12/20 points)
• 3+ errors: Significant deduction (5/20 points)
• Critical errors: Automatic failure (0/20 points)

Tool Usage

Command-Line Usage

Basic Validation:

python ${CLAUDE_PLUGIN_ROOT}/lib/web_page_validator.py http://127.0.0.1:5000

Verbose Output:

python ${CLAUDE_PLUGIN_ROOT}/lib/web_page_validator.py http://127.0.0.1:5000 --verbose

Save Report to File:

python ${CLAUDE_PLUGIN_ROOT}/lib/web_page_validator.py http://127.0.0.1:5000 --output report.txt

JSON Output:

python ${CLAUDE_PLUGIN_ROOT}/lib/web_page_validator.py http://127.0.0.1:5000 --json > result.json

Show Browser (Debugging):

python ${CLAUDE_PLUGIN_ROOT}/lib/web_page_validator.py http://127.0.0.1:5000 --no-headless

Programmatic Usage

Python Integration:

from lib.web_page_validator import WebPageValidator, format_validation_report

# Validate URL
with WebPageValidator(headless=True, timeout=30) as validator:
    result = validator.validate_url('http://127.0.0.1:5000', wait_for_load=3)

# Check success
if result.success:
    print("[OK] Page validated successfully")
else:
    print(f"[ERROR] Validation failed: {result.error_summary}")

    # Get detailed report
    report = format_validation_report(result, verbose=True)
    print(report)

    # Access specific errors
    for error in result.console_errors:
        print(f"Error: {error.message}")

Slash Command Usage

# Validate dashboard at default URL
/validate:web http://127.0.0.1:5000

# Validate with auto-fix enabled
/validate:web http://127.0.0.1:5000 --auto-fix

# Validate and save report
/validate:web http://127.0.0.1:5000 --report

Installation Requirements

Required Dependencies

Selenium (Recommended):

pip install selenium

ChromeDriver (for Selenium):

• Download from: https://chromedriver.chromium.org/
• Or use: pip install webdriver-manager

Playwright (Alternative):

pip install playwright
playwright install chromium

Minimal Installation

If browser automation is not available, the tool falls back to basic HTTP validation:

• No additional dependencies required
• Limited error detection
• No console log capture
• Basic connectivity and HTTP status checking only

Integration Examples

Dashboard Startup Validation

Modify dashboard command to auto-validate:

# In commands/monitor/dashboard.md
# After starting server, run validation
subprocess.Popen(['python', 'lib/dashboard.py', '--no-browser', '--port', '5000'])
time.sleep(3)  # Wait for server to start

# Validate
result = subprocess.run(
    ['python', 'lib/web_page_validator.py', 'http://127.0.0.1:5000'],
    capture_output=True
)

if result.returncode != 0:
    print("[WARN] Dashboard validation failed, see report for details")

Git Pre-Commit Hook

Validate before committing dashboard changes:

#!/bin/bash
# .git/hooks/pre-commit

# Check if dashboard.py was modified
if git diff --cached --name-only | grep -q "dashboard.py"; then
    echo "Running dashboard validation..."

    # Start server
    python ${CLAUDE_PLUGIN_ROOT}/lib/dashboard.py --no-browser --port 5555 &
    PID=$!
    sleep 3

    # Validate
    python ${CLAUDE_PLUGIN_ROOT}/lib/web_page_validator.py http://127.0.0.1:5555
    RESULT=$?

    # Cleanup
    kill $PID

    if [ $RESULT -ne 0 ]; then
        echo "ERROR: Dashboard validation failed"
        exit 1
    fi
fi

Continuous Monitoring

Periodic validation of running dashboard:

import schedule
import time
from lib.web_page_validator import WebPageValidator

def validate_dashboard():
    with WebPageValidator() as validator:
        result = validator.validate_url('http://127.0.0.1:5000')

        if not result.success:
            # Alert or log errors
            print(f"[ALERT] Dashboard errors detected: {result.error_summary}")
            # Send notification, log to file, etc.

# Run validation every 5 minutes
schedule.every(5).minutes.do(validate_dashboard)

while True:
    schedule.run_pending()
    time.sleep(1)

Troubleshooting

Common Issues

1. Selenium WebDriver not found

Solution: Install ChromeDriver
- Download from: https://chromedriver.chromium.org/
- Or: pip install webdriver-manager
- Add to PATH

2. Chrome not installed

Solution: Install Google Chrome browser
- Download from: https://www.google.com/chrome/
- Or use Playwright as alternative

3. Timeout errors

Solution: Increase timeout
python ${CLAUDE_PLUGIN_ROOT}/lib/web_page_validator.py URL --timeout 60

4. No errors detected but page broken

Solution: Increase wait time after page load
python ${CLAUDE_PLUGIN_ROOT}/lib/web_page_validator.py URL --wait 10

5. Permission denied on Windows

Solution: Run as administrator or disable antivirus temporarily

Advanced Features

Custom Validation Rules

Add custom checks:

class CustomWebPageValidator(WebPageValidator):
    def validate_custom_rules(self, page):
        issues = []

        # Check for specific elements
        if not page.find_element(By.ID, 'dashboard-content'):
            issues.append("Missing dashboard-content element")

        # Check for required JavaScript globals
        has_required_js = page.execute_script("""
            return typeof Chart !== 'undefined' &&
                   typeof dashboardData !== 'undefined';
        """)

        if not has_required_js:
            issues.append("Missing required JavaScript libraries")

        return issues

Performance Budgets

Enforce performance thresholds:

def validate_performance(result):
    budget = {
        'loadTime': 3000,  # 3 seconds
        'domReady': 1000,  # 1 second
        'resourceCount': 50
    }

    violations = []

    if result.load_time > budget['loadTime'] / 1000:
        violations.append(f"Load time exceeds budget: {result.load_time:.2f}s > 3s")

    return violations

Accessibility Validation

Check for accessibility issues:

# Install axe-core for accessibility testing
page.execute_script("""
    // Inject axe-core library
    const script = document.createElement('script');
    script.src = 'https://cdnjs.cloudflare.com/ajax/libs/axe-core/4.7.2/axe.min.js';
    document.head.appendChild(script);
""")

# Run accessibility scan
results = page.execute_script("return axe.run();")
violations = results.get('violations', [])

Success Metrics

Validation Quality Indicators:

• 100% error-free: All pages load without console errors
• < 1 second validation time: Fast feedback loop
• Zero false positives: Accurate error detection
• Automated remediation: 80%+ of issues fixed automatically
• Continuous monitoring: 24/7 health checking

Summary

The web validation skill provides:

• Automated error detection without manual browser inspection
• Real-time console monitoring for JavaScript issues
• Comprehensive validation of web applications
• Performance measurement and optimization guidance
• Integration-ready for CI/CD pipelines and quality control

Use this skill whenever working with web-based components to ensure quality and catch errors early in the development cycle.