Back to docs

Tool Hunt Bugs

Turn AI loose on your site. See what breaks.

hunt_bugs runs autonomous exploratory testing. Give it a URL and it crawls your site for bugs. It finds broken links, JS errors, a11y issues, visual glitches, and security problems. No test cases needed.

Quick Start

{
  "url": "https://example.com",
  "scope": "all",
  "depth": 4,
  "maxPages": 50
}

What happens:

  1. AI starts at your URL and begins exploring.
  2. On each page, it checks for functional, visual, accessibility, and security issues.
  3. It follows links, fills forms, and clicks buttons to find things that break.
  4. You get a report with repro steps and screenshots.

Parameters

Parameter Type Required Default Description
url string Yes — Starting URL
scope string No all Bug types: all, functional, visual, accessibility, security
depth number No 3 How many levels deep to crawl
maxPages number No 20 Maximum pages to visit
focus string No — Focus area (e.g., "forms", "checkout", "navigation")
exclude array No — URL patterns to skip

What It Finds

Functional Bugs

Bug Type How It's Detected
Broken links Links that return 4xx/5xx errors
Dead ends Pages with no way to leave
Form errors Submissions that fail silently
JavaScript exceptions Console errors during interaction
Failed network requests XHR/fetch calls that error
Infinite loops Redirect chains, infinite scrolls
Missing content Empty states, placeholder text

Visual Bugs

Bug Type How It's Detected
Overlapping elements Content that covers other content
Horizontal overflow Content breaking the viewport
Missing images Broken src attributes
Layout breaks Elements far from expected position
Z-index issues Content hidden behind other layers
Responsive failures Elements that break at viewport edges

Accessibility Bugs

Bug Type How It's Detected
Missing alt text Images without descriptions
Low contrast Text that fails WCAG contrast
Keyboard traps Cannot escape a component with keyboard
Missing labels Form fields without associated labels
Focus issues Interactive elements without focus styles
ARIA violations Invalid ARIA attributes

Security Issues

Bug Type How It's Detected
Exposed credentials Visible API keys, passwords
Insecure forms HTTP forms on HTTPS pages
Data in URLs Sensitive info in query strings
Missing HTTPS Insecure resource loading
Open redirects Redirects to external domains
Debug endpoints Exposed dev/debug routes

Output

{
  "url": "https://example.com",
  "pagesVisited": 34,
  "timeElapsed": 187,
  "bugs": [
    {
      "severity": "critical",
      "type": "functional",
      "category": "form-error",
      "url": "https://example.com/checkout",
      "description": "Payment form silently fails when CVV is left empty",
      "reproduction": [
        "Navigate to /checkout",
        "Fill all fields except CVV",
        "Click 'Pay Now'",
        "Form shows loading spinner but never completes"
      ],
      "screenshot": "base64...",
      "consoleErrors": [
        "Uncaught TypeError: Cannot read property 'value' of null at payment.js:142"
      ]
    },
    {
      "severity": "serious",
      "type": "accessibility",
      "category": "missing-label",
      "url": "https://example.com/contact",
      "description": "Phone number field has no associated label",
      "wcag": "1.3.1",
      "element": "<input type='tel' name='phone' placeholder='Phone'>",
      "remediation": "Add <label for='phone'>Phone Number</label>"
    },
    {
      "severity": "moderate",
      "type": "visual",
      "category": "overflow",
      "url": "https://example.com/pricing",
      "description": "Pricing table overflows viewport on mobile",
      "viewport": "375x667",
      "screenshot": "base64..."
    },
    {
      "severity": "serious",
      "type": "security",
      "category": "exposed-credentials",
      "url": "https://example.com/config",
      "description": "API key visible in page source",
      "evidence": "const API_KEY = 'sk-...'",
      "recommendation": "Move API key to environment variable"
    }
  ],
  "summary": {
    "critical": 1,
    "serious": 4,
    "moderate": 7,
    "minor": 12,
    "byType": {
      "functional": 6,
      "visual": 8,
      "accessibility": 5,
      "security": 5
    }
  }
}

Use Cases

1. Pre-Release Smoke Test

Before deploying, run a quick bug hunt.

{
  "url": "https://staging.example.com",
  "scope": "functional",
  "depth": 3,
  "maxPages": 30
}

This catches obvious breaks before they reach production.

2. Security Reconnaissance

Find exposed secrets and vulnerabilities.

{
  "url": "https://example.com",
  "scope": "security",
  "depth": 5,
  "maxPages": 100
}

3. Accessibility Sweep

Find accessibility issues across the entire site.

{
  "url": "https://example.com",
  "scope": "accessibility",
  "depth": 5
}

For deeper analysis, follow up with empathy_audit.

4. Focused Testing

Hunt bugs only in a specific area.

{
  "url": "https://example.com/checkout",
  "focus": "checkout",
  "exclude": ["/blog/*", "/docs/*"]
}

How It Explores

  1. Starts at your URL and analyzes the page.
  2. Finds interactive elements -- links, buttons, forms.
  3. Runs interactions -- clicks, fills fields, submits forms.
  4. Records everything -- console logs, network calls, screenshots.
  5. Follows promising paths -- prioritizes unexplored areas.
  6. Avoids traps -- detects infinite loops, skips logout/delete.
  7. Moves to the next page and repeats.

Safety rules prevent destructive actions. It will not click "Delete Account" or "Cancel Subscription."

CI/CD Integration

# Run in CI, fail if critical bugs found
npx cbrowser hunt-bugs https://staging.example.com \
  --scope all \
  --depth 3 \
  --fail-on critical \
  --output bugs.json

# Generate HTML report
npx cbrowser hunt-bugs https://example.com \
  --output report.html

Tips

Start Shallow, Go Deep

// First run: quick sweep
{ "depth": 2, "maxPages": 20 }

// Second run: deep dive on problem areas
{ "url": "https://example.com/checkout", "depth": 5 }

Exclude Known Issues

{
  "exclude": [
    "/legacy/*",  // Old pages being deprecated
    "/admin/*"    // Requires auth
  ]
}

Focus on What Matters

// Only care about checkout working?
{ "focus": "checkout", "scope": "functional" }

// Preparing for accessibility audit?
{ "scope": "accessibility", "depth": 10 }

Related Tools

Last updated: v18.9.0

From the Blog