browser-edge-cases skill | PlugMCP

browser-edge-cases

by aden-hive11k

Autonomous Agents

SOP for debugging browser automation failures on complex websites. Use when browser tools fail on specific sites like LinkedIn, Twitter/X, SPAs, or sites with Shadow DOM.

Install

Use withClaudeCursorCodex

The file stays in the publisher's repository. PlugMCP does not host or rewrite it.

Download skill .claude/skills/browser-edge-cases/SKILL.md on GitHub

Related skills

View all

paperclipThe open-source app everyone uses to manage agents at work
paperclip-task-bridgeCreate, comment on, update, and list Paperclip tasks from Hermes using scoped Paperclip API credentials.
add-product-e2e-evalAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution.

SOP for debugging browser automation failures on complex websites. Use when browser tools fail on specific sites like LinkedIn, Twitter/X, SPAs, or sites with Shadow DOM.

name: browser-edge-cases description: SOP for debugging browser automation failures on complex websites. Use when browser tools fail on specific sites like LinkedIn, Twitter/X, SPAs, or sites with Shadow DOM. license: MIT

Browser Tool Edge Cases

Standard Operating Procedure for debugging and fixing browser automation failures on complex websites.

When to Use This Skill

browser_interact(action="scroll") succeeds but page doesn't move
browser_interact(action="left_click") succeeds but no action triggered
browser_interact(action="type") text disappears or doesn't work
browser_snapshot hangs or returns stale content
browser_navigate loads wrong content

SOP: Debugging Browser Tool Failures

Phase 1: Reproduce & Isolate

1. Create minimal test case demonstrating failure
2. Test against simple site (example.com) to verify tool works
3. Test against problematic site to confirm issue

Quick isolation test:

# Test 1: Does the tool work at all?
await browser_navigate(tab_id, "https://example.com")
result = await browser_interact(action="scroll", tab_id=tab_id, scroll_direction="down", scroll_amount=100)
# Should work on simple sites

# Test 2: Does it fail on the problematic site?
await browser_navigate(tab_id, "https://linkedin.com/feed")
result = await browser_interact(action="scroll", tab_id=tab_id, scroll_direction="down", scroll_amount=100)
# If this fails but example.com works → site-specific edge case

console = await browser_console(tab_id)
# Look for: CSP violations, React errors, JavaScript exceptions

html = await browser_html(tab_id)
snapshot = await browser_snapshot(tab_id)
# Look for:
# - Nested scrollable divs (overflow: scroll/auto)
# - Shadow DOM roots
# - iframes
# - Custom widgets

Symptom	Likely Cause	Check
Scroll doesn't move	Nested scroll container	Look for `overflow: scroll` divs
Click no effect	Element covered	Check `getBoundingClientRect` vs viewport
Type clears	Autocomplete/React	Check for event listeners on input; try a `type` action with no selector
Snapshot hangs	Huge DOM	Check node count in snapshot
Snapshot stale	SPA hydration	Wait after navigation

async def robust_operation(tab_id):
    # Method 1: Primary approach
    try:
        result = await primary_method(tab_id)
        if verify_success(result):
            return result
    except Exception:
        pass

    # Method 2: CDP fallback
    try:
        result = await cdp_fallback(tab_id)
        if verify_success(result):
            return result
    except Exception:
        pass

    # Method 3: JavaScript fallback
    return await javascript_fallback(tab_id)

# Bad - can hang forever
result = await browser_snapshot(tab_id)

# Good - fails fast with useful error
try:
    result = await browser_snapshot(tab_id, timeout_s=10.0)
except asyncio.TimeoutError:
    # Handle timeout gracefully
    result = await fallback_snapshot(tab_id)

1. Run against problematic site → should work
2. Run against simple site → should still work (regression check)
3. Document in registry.md

// Find largest scrollable container
const candidates = [];
document.querySelectorAll('*').forEach(el => {
    const style = getComputedStyle(el);
    if (style.overflow.includes('scroll') || style.overflow.includes('auto')) {
        const rect = el.getBoundingClientRect();
        if (rect.width > 100 && rect.height > 100) {
            candidates.push({el, area: rect.width * rect.height});
        }
    }
});
candidates.sort((a, b) => b.area - a.area);
return candidates[0]?.el;

const rect = element.getBoundingClientRect();
const centerX = rect.left + rect.width / 2;
const centerY = rect.top + rect.height / 2;
const topElement = document.elementFromPoint(centerX, centerY);
return topElement === element || element.contains(topElement);

element.click();

document.querySelectorAll('*').length > 5000

// Check if React app has hydrated
document.querySelector('[data-reactroot]') ||
document.querySelector('[data-reactid]')

await browser_navigate(tab_id, url, wait_until="load")
await browser_interact(action="wait", tab_id=tab_id, wait_for_selector='[data-testid="content"]', timeout_ms=5000)

document.querySelectorAll('*').some(el => el.shadowRoot)

function queryShadow(selector) {
    const parts = selector.split('>>>');
    let node = document;
    for (const part of parts) {
        if (node.shadowRoot) {
            node = node.shadowRoot.querySelector(part.trim());
        } else {
            node = node.querySelector(part.trim());
        }
    }
    return node;
}

Issue	Primary Fix	Fallback
Scroll not working	Find scrollable container	Mouse wheel at container center
Click no effect	JavaScript click()	CDP mouse events
Type clears	`use_insert_text=False` (per-keystroke)	Use a `type` action (Input.insertText)
Snapshot hangs	Add timeout_s	DOM snapshot fallback
Stale content	Wait for selector	Increase wait_until timeout
Shadow DOM	Pierce selector	JavaScript traversal

browser-edge-cases

Install

Related skills

name: browser-edge-cases description: SOP for debugging browser automation failures on complex websites. Use when browser tools fail on specific sites like LinkedIn, Twitter/X, SPAs, or sites with Shadow DOM. license: MIT

Browser Tool Edge Cases

When to Use This Skill

SOP: Debugging Browser Tool Failures

Phase 1: Reproduce & Isolate

Phase 2: Analyze Root Cause

Phase 3: Implement Multi-Layer Fix

Phase 4: Verify Fix

Pattern Library

P1: Nested Scrollable Containers

P2: Element Covered by Overlay

P3: React Synthetic Events

P4: Huge DOM / Accessibility Tree

P5: SPA Hydration Delay

P6: Shadow DOM

Quick Reference

References