How to Diagnose Failing Browser Automations with the Site-Debugger Skill

The site-debugger skill automatically analyzes browser automation failures by launching an instrumented Chromium instance, detecting anti-bot measures, validating selectors, and generating a remediation playbook with actionable fixes.

Browser automations built with Playwright or Selenium often fail silently due to anti-bot defenses, brittle selectors, or timing race conditions. The site-debugger skill in the browserbase/skills repository provides a systematic diagnostic workflow that captures full Chrome DevTools Protocol (CDP) traces and pinpoints exactly why your script broke.

What the Site-Debugger Skill Diagnoses

The skill performs automated audits across five critical failure domains.

Bot Detection and Anti-Automation Defenses

The analyzer detects anti-bot scripts, challenge pages (reCAPTCHA, hCAPTCHA), and browser fingerprinting techniques. When it identifies these defenses, it reports which specific mechanisms are blocking your automation and suggests workarounds such as extra headers or stealth plugins.

Selector Stability and DOM Validation

The skill examines all CSS and XPath selectors used by your script, verifying they exist in the DOM and evaluating their stability. It flags dynamic IDs, hidden elements, or overly specific selectors that cause "element not found" errors, offering more robust alternatives.

Timing, Network, and Resource Loading

It records page load timings, network stalls, and resource-load failures. This reveals race conditions or missing wait directives that cause intermittent failures when elements appear after your script attempts interaction.

Authentication Flows and Session Handling

The debugger looks for login redirects, token-exchange flows, and session-cookie handling issues. It identifies missing authentication steps or cookie-sync problems that prematurely terminate sessions.

CAPTCHA Detection and Classification

When a CAPTCHA appears, the skill reports its type (reCAPTCHA v2/v3, hCAPTCHA, etc.) and location in the DOM. This helps you decide whether to integrate a solver service or insert a manual intervention step.

How the Site-Debugger Works Internally

According to the source code in skills/site-debugger/SKILL.md, the diagnostic pipeline executes in five stages:

1. Launches a headless Chromium instance instrumented with the browser-trace module (skills/browser-trace/SKILL.md) to capture CDP events.
2. Runs the supplied automation script inside the traced browser, recording every network request, DOM mutation, and JavaScript execution.
3. Analyzes the trace using heuristic modules for bot detection, selector auditing, timing analysis, and authentication verification.
4. Generates artifacts in the output directory: report.json containing the diagnostic findings, and playbook.yaml containing verified remediation steps.
5. Optionally uploads the trace to the Browserbase UI for visual step-through debugging.

The core implementation reuses utilities from skills/functions/REFERENCE.md for selector analysis and timing heuristics.

Running the Site-Debugger Skill

You can invoke the diagnostic via the Browserbase CLI or programmatically from a Node.js application.

Using the Browserbase CLI

Install the CLI globally, then run the skill against your automation script:

# Install the CLI (once)

npm i -g @browserbase/cli

# Run the diagnosis

bb site-debugger run --script ./my-automation.js --output ./debug-output

The --script parameter points to your failing automation file, while --output specifies the directory where trace.json, report.json, and playbook.yaml will be written.

Programmatic Implementation with Node.js

Import the runSiteDebugger function to embed diagnostics directly in your workflow:

import { runSiteDebugger } from '@browserbase/skills/site-debugger';

const scriptPath = './my-automation.js';

runSiteDebugger({
  script: scriptPath,
  options: { timeoutMs: 30_000, stealth: true },
})
  .then(({ report, playbook, trace }) => {
    console.log('Diagnostic report:', report);
    console.log('Playbook saved to:', playbook.path);
  })
  .catch(err => {
    console.error('Site-debugger failed:', err);
  });

This returns JavaScript objects for the report, playbook metadata, and trace data, allowing you to programmatically inspect results before applying fixes.

Applying Generated Playbooks to Fix Automations

The generated playbook contains concrete remediation steps. Apply them automatically using the applyPlaybook utility:

import { applyPlaybook } from '@browserbase/skills/playbook';

const playbookPath = './debug-output/playbook.yaml';

applyPlaybook({ playbook: playbookPath })
  .then(() => console.log('Automation updated with fixes'))
  .catch(console.error);

The applyPlaybook function rewrites selectors, injects explicit waits, and adds missing authentication steps as specified in the playbook, transforming diagnostic findings into working code.

Key Source Files and Architecture

The site-debugger skill is composed of the following source files:

• skills/site-debugger/SKILL.md: Skill definition, entry point configuration, and option schema.
• skills/browser-trace/SKILL.md: Shared tracing infrastructure that captures CDP logs for the debugger to analyze.
• skills/functions/REFERENCE.md: Helper utilities for DOM selector analysis, timing audits, and network inspection.
• README.md: Repository overview table listing the site-debugger entry point and dependencies.

These files implement the instrumentation pipeline and public API used by both the CLI and programmatic SDK integrations.

Summary

• The site-debugger skill systematically diagnoses Playwright and Selenium failures by analyzing bot detection, selector stability, network timing, authentication flows, and CAPTCHA challenges.
• It generates a diagnostic report (report.json) and an actionable playbook (playbook.yaml) that you can apply automatically to fix your automation.
• Invoke the skill via bb site-debugger run in the CLI or runSiteDebugger() in Node.js code.
• The implementation relies on skills/site-debugger/SKILL.md and shares tracing components with skills/browser-trace/SKILL.md.

Frequently Asked Questions

What output files does the site-debugger skill generate?

The skill produces three primary artifacts in your specified output directory: trace.json containing the full CDP browser trace, report.json containing the diagnostic analysis of failure points, and playbook.yaml containing the concrete remediation steps to fix your script.

How does the skill detect anti-bot mechanisms?

The analyzer inspects page scripts for known anti-automation signatures, evaluates browser fingerprinting attempts, and identifies challenge pages like reCAPTCHA or hCAPTCHA by analyzing DOM structure and network patterns defined in the skills/functions/REFERENCE.md heuristic modules.

Can I use the site-debugger with existing Playwright or Selenium scripts?

Yes. The skill accepts any Node.js automation script as its --script parameter or script option. It wraps your existing Playwright or Selenium code in an instrumented Chromium instance, capturing execution behavior without requiring modifications to your underlying test logic.

What is the difference between the report and the playbook?

The report (report.json) is a diagnostic document describing what failed—such as which selectors were missing or which anti-bot defenses triggered. The playbook (playbook.yaml) is an executable specification containing the actual fixes—such as updated selector strings, wait timeouts, and authentication steps—that the applyPlaybook function uses to rewrite your automation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}