Back to docs

Tool Hunt Bugs

Crawl your site. See what breaks.

hunt_bugs crawls your site and checks every page it visits for defects: broken links, console errors, missing images, accessibility failures and more. Give it a URL. No test cases needed.

Quick Start

{
  "url": "https://example.com",
  "maxPages": 25
}

What happens:

  1. It opens your URL and checks the page.
  2. It follows links on the same host (not # anchors or javascript: links) until it has visited maxPages pages or timeout runs out.
  3. Console errors on each page are recorded as bugs.
  4. You get the bugs worst first, with a breakdown by page, type and severity.

It reads pages. It does not click buttons or fill in forms.

Parameters

Parameter Type Required Default Description
url string Yes - Starting URL
maxPages number No 10 Maximum pages to visit
limit number No 25 How many bugs to return, worst first
offset number No 0 Skip this many bugs, to page through a large result
timeout number No 60000 Time budget for the crawl, in ms

The breakdowns (byPage, byType, bySeverity) always cover every finding, so a list cut short by limit never hides the shape of what was found.

Output

Abridged:

{
  "pagesVisited": 2,
  "visitedUrls": [
    "https://example.com/",
    "https://example.com/pricing"
  ],
  "bugsFound": 7,
  "distinctBugs": 6,
  "returned": 6,
  "offset": 0,
  "byPage": {
    "https://example.com/": 4,
    "https://example.com/pricing": 2
  },
  "byType": {
    "a11y-violation": 3,
    "a11y-verify": 2,
    "broken-link": 1
  },
  "bySeverity": {
    "high": 3,
    "medium": 1,
    "low": 2
  },
  "bugs": [
    {
      "type": "a11y-violation",
      "severity": "high",
      "description": "...",
      "url": "https://example.com/",
      "selector": "...",
      "recommendation": "..."
    }
  ]
}

Repeats of the same finding on the same page are counted once, with occurrences and allSelectors on the entry. When the list is cut short, omitted and omittedNote say how many are left and which offset returns the next page.

Note on shape. Earlier revisions of this page showed a summary object with byType: { functional, visual, accessibility, security } and severities named serious / moderate / minor. The tool has never emitted that. The real response has no summary wrapper — byPage, byType and bySeverity sit at the top level, severities are critical | high | medium | low, and byType keys are the detection types listed below, not categories. Corrected 2026-08-11 against live output.

Bug types

byType keys come from this set:

type meaning
broken-link Empty or invalid href
console-error Uncaught error in the console
a11y-violation A WCAG failure — e.g. an image with no alt attribute
a11y-verify A declared-decorative alt="" on a substantial image, worth confirming — not a violation
missing-image Image failed to load
contrast-violation Text/background contrast below threshold
missing-aria Interactive element with no accessible name
duplicate-id Repeated id, which breaks selectors
missing-page-title No <title>
missing-lang No lang on <html>
autoplay-media Media that plays without user action
missing-skip-link No skip-to-content link
form-error Form-level defect
slow-resource Resource over the latency budget
keyboard-trap Focus cannot escape a region

a11y-violation and a11y-verify are deliberately separate: a missing alt attribute is an unambiguous WCAG 1.1.1 failure, while alt="" is a valid declaration that an image is decorative. The second is graded low and asks you to confirm the intent rather than prescribing a fix that is already applied.

Use Cases

1. Pre-release smoke test

Before deploying, run a quick bug hunt on staging.

{
  "url": "https://staging.example.com",
  "maxPages": 30
}

2. One section of the site

Start where the problem is. The crawl stays on the same host and follows links from the start page.

{
  "url":
    "https://example.com/checkout",
  "maxPages": 5
}

For deeper accessibility analysis, follow up with empathy_audit.

3. Page through a large result

{
  "url": "https://example.com",
  "maxPages": 50,
  "limit": 25,
  "offset": 25
}

How It Explores

  1. Starts at your URL and checks the page.
  2. Collects links on the same host.
  3. Visits them in turn, checking each page and recording console errors.
  4. Stops at maxPages pages or when timeout runs out.

CLI

npx cbrowser hunt-bugs \
  https://staging.example.com \
  --max-pages 20 --timeout 120000

The CLI (also cbrowser hunt) takes --max-pages and --timeout and prints each bug with its selector and recommendation. It has no JSON or HTML report option; use the MCP tool for structured output.

Tips

  • Start small. A first run with maxPages: 10 shows the common problems; raise it once those are fixed.
  • Read byType first. It covers every finding, so it shows where to start even when bugs is cut short.
  • a11y-verify is not a failure. It asks you to confirm that an alt="" image is meant to be decorative.

Last updated: v20.0.0

From the Blog