Back to docs

FAQ

Frequently asked questions about CBrowser. Use Ctrl+F or the search bar to find specific topics.

General

What is CBrowser?

CBrowser is a cognitive browser automation tool with 120 MCP tools. It simulates how real humans think, struggle, and give up on your site. It goes beyond testing whether buttons click.

Built on Playwright, it includes 26 cognitive traits, 10 motivational values per persona, Wasserstein optimal transport for visual analysis, and constitutional safety.

How is it different from Playwright / Puppeteer / Selenium?

Feature Playwright CBrowser
Element selection Exact CSS selectors AI finds elements from descriptions
When UI changes Tests break Self-healing selectors adapt
User simulation None 26 cognitive traits per persona
Visual regression Basic pixel diff Wasserstein optimal transport (40-60% fewer false positives)
Accessibility None Perceptual transport — measures actual info loss per persona
Safety None Constitutional safety zones (green/yellow/orange/red/black)
Integration API only Native MCP for Claude Desktop, Claude.ai, Claude Code

How many tools does CBrowser have?

120 MCP tools in 11 categories: Browser Automation, Visual & Optimal Transport, Cognitive Transport, Accessibility, Testing, Personas, Marketing, AI Friendliness, Site Knowledge, Session Management, and Utilities.

Is CBrowser free?

Yes. MIT licensed, free to use. The demo MCP server is free with rate limits. Self-hosted and Enterprise have no rate limits.

What browsers are supported?

Chromium (default), Firefox, and WebKit (Safari). All three available for cross-browser testing.

Installation

System requirements?

  • Node.js 18+ or Bun 1.0+
  • Linux, macOS, or Windows
  • ~500MB for browser binaries

Quick install?

npx cbrowser --version            # Run without installing
npm install -g cbrowser            # Install globally
bun add cbrowser                   # With Bun

How do I connect to Claude?

Claude Desktop (local MCP):

{
  "mcpServers": {
    "cbrowser": {
      "command": "npx",
      "args": ["cbrowser", "mcp-server"]
    }
  }
}

Claude.ai (remote MCP): Add https://demo.cbrowser.ai/mcp as a connector.

Claude Code: Install the CBrowser skill.

Wasserstein Optimal Transport

What is Wasserstein distance?

The minimum "cost" of turning one distribution into another. It measures how much mass needs to move and how far. CBrowser uses it for visual comparison, persona modeling, and attention analysis.

Why is it better than pixel diff?

Pixel diff treats every pixel independently. A button that moved 2px looks the same as one that moved 200px.

Wasserstein distance understands spatial relationships. Small shifts cost little; large shifts cost more. This reduces false positives by 40-60% in visual regression testing.

What are Smart Baselines?

Instead of one screenshot, CBrowser captures N screenshots. It computes the Wasserstein barycenter (the optimal "average" distribution) and rejects outlier captures. It then derives an adaptive threshold.

This eliminates false positives from dynamic content, timing variations, and animation states.

What is a Transport Map?

A visualization showing where visual content moved between two page states. It includes:

  • A heatmap (blue to red by change size)
  • Flow arrows (direction and size of movement)
  • Hotspot regions with descriptions

What is Attention Analysis?

Computes persona-specific attention maps using W₂ distance on CIE-Lab color distributions. Shows where each persona looks.

For example, an ADHD user's attention is captured by animations (entropy: 0.915). A motor-impaired user narrows attention to the center (center-heavy filter).

What is Cognitive Distance?

The Wasserstein-1 distance between two persona trait distributions. It treats 26 cognitive traits as a probability measure.

For example, W₁(first-timer, power-user) = 0.2305 means they are "substantially different" profiles. Used for max-coverage persona selection and geodesic interpolation.

Personas & Cognitive Simulation

What personas are built-in?

21 built-in personas. These include first-timer, power-user, mobile-user, elderly-user, impatient-user, screen-reader-user, motor-impairment-tremor, low-vision-magnified, cognitive-adhd, dyslexic-user, deaf-user, color-blind-deuteranopia, autism-spectrum, intellectual-disability, aphasia-receptive, dyscalculia, and more.

How are personas modeled?

Each persona has:

  • 26 cognitive traits (patience, comprehension, risk tolerance, etc.) — research-backed with 5 behavioral levels each
  • 10 motivational values (Schwartz universal values + SDT psychological needs)
  • Perceptual profile — visual filter, attention mode, motor cost, processing speed
  • Barrier weights — per-barrier-type severity multipliers

Why do different personas get different empathy scores?

Each persona has different barrier severity multipliers. Touch targets are 3x worse for motor-impaired users but 0.5x for ADHD users. Cognitive load is 3x for ADHD but 0.8x for motor-impaired users.

The scoring is weighted per persona using optimal transport profiles.

Can I create custom personas?

Yes — three ways:

npx cbrowser persona create "anxious parent checking school portal" --name worried-parent

Or via questionnaire, or manual trait specification. All produce full 26-trait profiles.

What is Cognitive Load Estimation?

An 8-dimensional analysis of how overwhelming a page is for each persona. Dimensions: information density, visual complexity, interactive elements, text density, animation level, choice count, navigation depth, and patience.

It identifies the bottleneck dimension for each persona.

Empathy & Accessibility

How does the Empathy Audit work?

  1. Navigates to the page as the disability persona
  2. Runs barrier detection (touch targets, contrast, cognitive load, timing, color-only, alt text, labels)
  3. Applies persona-specific barrier weights (motor 3x on touch, ADHD 3x on cognitive load)
  4. Captures screenshot, applies perceptual filter, computes Wasserstein distance (information loss)
  5. Estimates cognitive load across 8 dimensions
  6. Analyzes attention via W₂ CIE-Lab saliency with persona filter
  7. Generates remediation priorities

What's Perceptual Transport?

Applies the persona's visual filter (blur for low vision, color attenuation for color blindness, contrast reduction for elderly) to a screenshot, then computes Wasserstein distance from the original. This quantifies how much visual information each persona actually loses — not just "does it pass WCAG" but "how different does this page look through this persona's eyes."

Session Continuity

What is _browserToken?

A session token returned by browser tools (navigate, click, etc.). It keeps the same browser open across MCP tool calls. Pass it from one call to the next to keep cookies, page state, and navigation history.

Why do I need it?

Without _browserToken, each MCP tool call opens a fresh browser (blank page). With it, navigate, screenshot, and click all share the same browser instance.

Does it work on Claude.ai?

Yes. _browserToken works through any MCP proxy. It is a regular tool parameter, not an HTTP header.

Visual Testing

What visual testing tools are available?

  • visual_baseline / visual_regression — Traditional baseline comparison
  • visual_baseline (captures=5) / visual_regression (auto-detects smart baselines) — Wasserstein barycenter consensus baselines
  • transport_map — Shows where content moved (heatmap + arrows)
  • attention_analysis / attention_compare — Persona-specific saliency
  • cross_browser_test / cross_browser_diff — Multi-browser comparison
  • responsive_test — Viewport testing
  • ab_comparison — Side-by-side comparison

How do I reduce false positives?

Use visual_baseline with captures=5. It takes multiple screenshots, computes the Wasserstein barycenter, and derives a threshold from observed variance.

This reduces false positives by 40-60%.

Testing & QA

Can I write tests in plain English?

Yes:

Go to https://example.com
Click "Sign Up"
Fill email with "[email protected]"
Verify page contains "Welcome"

Does CBrowser work in CI/CD?

Yes. Runs headless by default. See Examples for GitHub Actions config.

AI Friendliness

What is an Agent-Ready Audit?

Grades your site on AI-agent compatibility (A through F). Scores four areas: Findability (35%), Stability (30%), Accessibility (20%), Semantics (15%).

What is llms.txt?

A machine-readable file that helps AI agents understand your site. Think of it like robots.txt, but for AI. CBrowser can generate, validate, and diff llms.txt files.

Performance & Troubleshooting

Browser won't start?

npx playwright install --force     # Reinstall browsers
npx playwright install --dry-run   # Check installation

"Display not found" on Linux?

CBROWSER_HEADLESS=true npx cbrowser ...

Tests timing out?

Increase timeout: npx cbrowser test-suite tests.txt --timeout 60000

Empathy audit timing out on Claude.ai?

The empathy audit runs in under 2 seconds now (v18.25+). If it still times out, the MCP proxy connection may be dropping. Try running via CLI instead.

Related

From the Blog