Visual Debugging with MCP Puppeteer: 17-Minute Style Match Success

When “Make It Look Like This” Meets Browser Automation Magic

---

Sometimes the fastest path to UI consistency is visual debugging. This is the story of how MCP Puppeteer transformed a 17-minute styling task into an efficient demonstration of browser automation, regex parsing, and visual verification.

The Visual Request

16:54 GMT+7 - The User’s Approach

Instead of describing what they wanted, the user showed me the FloodBoy001 page with nicely formatted descriptions and GPS coordinates.

Request: “Make blockchain-fresh.html look like this”

The Power: Visual reference beats text description every time.

The MCP Puppeteer Advantage

Traditional Debugging Approach:

1. Read user description
2. Guess implementation needs
3. Code changes
4. Manual testing
5. Iterate until correct

MCP Puppeteer Visual Approach:

1. Screenshot reference page
2. Screenshot current page  
3. Compare visually
4. Code with exact target in mind
5. Screenshot verification

Time Difference: 17 minutes total vs typical 45+ minutes.

The Technical Detective Work

Phase 1: Visual Comparison (16:54-16:57)

MCP Puppeteer Screenshot 1: Reference FloodBoy001 page

• ✅ Clean description display
• ✅ Separated location and GPS
• ✅ Google Maps integration
• ✅ Consistent styling

MCP Puppeteer Screenshot 2: Current blockchain-fresh.html

• ❌ No description visible
• ❌ Missing GPS coordinates
• ❌ Different visual hierarchy

Insight: Data was being fetched but not displayed. Time to investigate the code.

Phase 2: The Scoping Bug Discovery (16:57-17:00)

Found The Problem:

// BROKEN: Variable scoped incorrectly
try {
    // ... blockchain calls
    let description = metadata[2]; // ← Declared here
} catch (err) {
    console.error(err);
}

// ❌ FAILS: description is undefined here
if (description) {
    displayDescription(description);
}

The Fix:

// FIXED: Proper variable scoping  
let description = null; // ← Declared in correct scope

try {
    // ... blockchain calls
    description = metadata[2]; // ← Assigned here
} catch (err) {
    console.error(err);
}

// ✅ WORKS: description is accessible
if (description) {
    displayDescription(description);
}

Page Status: Broken → Working in 3 minutes.

Phase 3: GPS Data Parsing (17:00-17:04)

Data Format Analysis:

Input: "โรงเรียนบ้านคลองเขื่อน loc: 13.1234,100.5678"
Goal: 
- Location: "โรงเรียนบ้านคลองเขื่อน"  
- GPS: "13.1234,100.5678"
- Maps Link: https://www.google.com/maps?q=13.1234,100.5678

Regex Solution:

const parseDescription = (desc) => {
    const match = desc.match(/^(.+?)\s+loc:\s*([\d.-]+),\s*([\d.-]+)$/);
    if (match) {
        return {
            location: match[1],           // "โรงเรียนบ้านคลองเขื่อน"
            lat: match[2],               // "13.1234"  
            lng: match[3],               // "100.5678"
            mapsUrl: `https://www.google.com/maps?q=${match[2]},${match[3]}`
        };
    }
    return { location: desc }; // Fallback for non-GPS descriptions
};

Result: Clean separation of location text and GPS coordinates.

Phase 4: Visual Verification (17:04-17:11)

MCP Puppeteer Final Screenshot:

• ✅ Location displayed with proper typography
• ✅ GPS coordinates with maps link
• ✅ Styling matches reference page
• ✅ Responsive layout maintained

User Confirmation: “Perfect match!”

The MCP Puppeteer Workflow

Standard Visual Debugging Pattern:

// 1. Capture reference
await mcp__puppeteer__puppeteer_navigate({
    url: "http://localhost:3000/blockchain/FloodBoy001"
});
await mcp__puppeteer__puppeteer_screenshot({
    name: "reference_styling"
});

// 2. Capture current state  
await mcp__puppeteer__puppeteer_navigate({
    url: "http://localhost:3000/blockchain-fresh.html"
});
await mcp__puppeteer__puppeteer_screenshot({
    name: "current_implementation"
});

// 3. Make changes...

// 4. Verify results
await mcp__puppeteer__puppeteer_screenshot({
    name: "final_result"
});

Benefits Realized:

• Visual Truth: Screenshots don’t lie about styling issues
• Instant Feedback: See results immediately without manual testing
• Precise Targeting: Know exactly what the end result should look like
• Efficient Iteration: Quick visual verification loop

Technical Lessons Learned

1. JavaScript Scoping in Try-Catch

Problem: Variables declared inside try blocks aren’t accessible outside Solution: Declare variables in outer scope, assign inside try block Application: Critical for error-prone blockchain operations

2. Regex for Structured Text Parsing

Pattern: "Location loc: lat,lng" format parsing Implementation: Clean separation for better UI presentation Reusability: Pattern works for any “text + structured data” format

3. Visual-First Debugging

Approach: Screenshot before and after every change Benefit: Immediate visual feedback prevents styling regressions
Tool: MCP Puppeteer headless mode for rapid verification

The 17-Minute Breakdown

Minute-by-Minute Efficiency:

• 0-3 min: Visual comparison with MCP Puppeteer screenshots
• 3-6 min: Code investigation and scoping bug discovery
• 6-9 min: Bug fix and page restoration
• 9-15 min: GPS parsing implementation with regex
• 15-17 min: Final verification and visual confirmation

Key Success Factors:

1. Visual reference eliminated guesswork
2. Browser automation provided instant feedback
3. Structured debugging approach prevented random attempts
4. Regex parsing solved complex data separation cleanly

Comparison: Before vs After

Before: Text-Based Debugging

User: "Make the description look better"
Dev: "What do you mean by better?"
User: "You know, like the other page"
Dev: "Which page? What specifically?"
[... 30 minutes of back-and-forth ...]

After: Visual-First Approach

User: "Make it look like this" [shows page]
Dev: [Screenshots both pages with MCP Puppeteer]
Dev: "I see the differences, implementing now"
[... 17 minutes total with visual verification ...]

Communication Efficiency: Visual reference eliminated ~13 minutes of clarification.

The Broader Impact

Developer Experience

• Faster iteration cycles
• Visual confirmation builds confidence
• No guessing about requirements

User Experience

• Consistent styling across pages
• Professional GPS integration
• Clean information hierarchy

Code Quality

• Proper variable scoping
• Robust error handling
• Reusable parsing patterns

Replicable Patterns

Visual Debugging Workflow

1. Reference Screenshot: Capture the target design
2. Current State Screenshot: Document starting point
3. Iterative Screenshots: Visual feedback after each change
4. Final Verification: Confirm match with reference

GPS Data Processing

// Reusable pattern for "text loc: lat,lng" format
const parseLocationData = (description) => {
    const gpsMatch = description.match(/^(.+?)\s+loc:\s*([\d.-]+),\s*([\d.-]+)$/);
    return gpsMatch ? {
        location: gpsMatch[1],
        coordinates: { lat: gpsMatch[2], lng: gpsMatch[3] },
        mapsUrl: `https://www.google.com/maps?q=${gpsMatch[2]},${gpsMatch[3]}`
    } : { location: description };
};

JavaScript Scoping Safety

// Safe pattern for blockchain operations
let result = null;
try {
    result = await blockchainOperation();
} catch (error) {
    console.error('Operation failed:', error);
}
// result is safely accessible here

---

Visual debugging with browser automation transforms unclear requirements into precise implementations. When users can show rather than tell, development becomes faster, more accurate, and more satisfying for everyone involved. 📸

Tools used: MCP Puppeteer, regex parsing, JavaScript scoping, GPS data processing, visual verification

Key insight: Screenshots provide ground truth that eliminates guesswork and accelerates development cycles.