cbrowser

v16.4.0

Published

6 hours ago

Cognitive browser automation that thinks like your users. Simulate real user cognition with abandonment detection, constitutional safety, chaos engineering, and UX friction discovery.

CBrowser — Cognitive Browser Automation

The browser automation that thinks. After 360+ tool invocations across rigorous stress testing, CBrowser earned a Grade A assessment—17 issues tracked, 17 fixed, zero regressions.

Built for AI agents. Trusted by humans. The only browser automation that asks: "Will a confused first-timer complete this task—and exactly when will they give up?"

What Makes CBrowser Different

31 of 34 tools graded A- or above. After extensive stress testing:

| Capability | Status | Why It Matters | |------------|--------|----------------| | Natural Language Tests | ⭐ Best-in-class | Write tests in plain English. 10-step E2E flows run 100% stable. | | Cognitive User Simulation | 🔬 Novel | 12 research-backed traits model real human behavior—not just clicks. | | Empathy Accessibility Audits | 🔬 Novel | Simulate users with tremors, low vision, ADHD. No competitor offers this. | | Self-Healing Selectors | ✅ Production-ready | ARIA-first with 0.8+ confidence gating. Handles DOM changes automatically. | | Constitutional AI Safety | 🔬 Novel | Risk-classified actions prevent autonomous agents from doing damage. | | 43 MCP Tools | ✅ Production-ready | Full Claude integration—local and remote servers. |

The Problem We Solve

Traditional browser automation answers one question: "Does this button click?"

CBrowser answers the question that actually matters: "Will a confused first-timer on a slow connection find this button—and will they give up before they do?"

Built on Playwright with cognitive user simulation, constitutional AI safety, and research-backed behavioral models, CBrowser is the only testing framework designed for the AI agent era.

Core Differentiators

| Challenge | Traditional Tools | CBrowser | |-----------|-------------------|----------| | User behavior | Simulates clicks and keystrokes | Simulates human cognition—patience decay, frustration accumulation, decision fatigue | | Abandonment prediction | Fails when elements don't exist | Predicts when users give up before they do | | AI agent safety | No guardrails for autonomous agents | Constitutional AI safety—risk-classified actions with verification gates | | Selector resilience | Breaks when DOM changes | Self-healing ARIA-first selectors with 0.8+ confidence gating | | Accessibility testing | WCAG compliance checklists | Disability empathy simulation—experience your site as a user with tremors, low vision, or ADHD |

Quick Start

Installation

npm install cbrowser
npx playwright install chromium

First Commands

# Navigate with intelligent wait detection
npx cbrowser navigate "https://your-site.com"

# Self-healing click with 80%+ confidence threshold
npx cbrowser smart-click "Add to Cart"

# Natural language assertions
npx cbrowser assert "page contains 'Order Confirmed'"

# Run a cognitive journey—simulate a real user
npx cbrowser cognitive-journey \
  --persona first-timer \
  --start "https://your-site.com" \
  --goal "complete checkout"

Constitutional AI Safety

AI agents need boundaries. CBrowser classifies every action by risk level:

| Zone | Examples | Behavior | |------|----------|----------| | 🟢 Green | Navigate, read, screenshot | Auto-execute | | 🟡 Yellow | Click buttons, fill forms | Log and proceed | | 🔴 Red | Submit, delete, purchase | Requires verification | | ⬛ Black | Bypass auth, inject scripts | Never executes |

An AI agent can freely browse and gather data, but cannot accidentally submit a form, delete records, or make purchases without explicit verification.

Cognitive User Simulation

CBrowser models 12 research-backed cognitive traits to simulate how real users think and behave:

| Trait | Research Basis | What It Models | |-------|---------------|----------------| | Patience | — | How quickly users abandon on friction | | Frustration | — | Accumulates with errors, decays with success | | Decision Fatigue | Baumeister's ego depletion | Users start choosing defaults after too many decisions | | Dual-Process Thinking | Kahneman (Nobel Prize) | System 1 (fast/automatic) vs System 2 (slow/deliberate) | | Self-Efficacy | Bandura (1977) | Belief in ability to solve problems; low = faster abandonment | | Satisficing | Simon (1956) | Accept "good enough" vs. optimize; satisficers decide 50% faster | | Trust Calibration | Fogg (2003) | Baseline trust affects click-through by 40% | | Interrupt Recovery | Mark et al. (2005) | Average recovery time 23min; models context preservation |

Abandonment Detection

The simulation stops when a realistic user would give up:

# Output from cognitive journey
⚠️ ABANDONED after 8 steps
Reason: Patience depleted (0.08) - "This is taking too long..."
Friction points:
  1. Password requirements unclear (step 4)
  2. Form validation error not visible (step 6)

Natural Language Testing

Write tests in plain English:

# Test: Checkout Flow
go to https://your-site.com/products
click "Add to Cart" button
verify page contains "1 item in cart"
click checkout
fill email with "[email protected]"
click "Place Order"
verify url contains "/confirmation"

npx cbrowser test-suite checkout-test.txt --html

Self-Healing Test Repair

When tests break due to site changes:

npx cbrowser repair-tests broken-test.txt --auto-apply --verify

CBrowser analyzes failures, generates alternative selectors, and repairs tests automatically.

Visual Testing Suite

AI Visual Regression

Semantic comparison—understands what changed, not just pixel differences:

npx cbrowser ai-visual capture "https://your-site.com" --name homepage
npx cbrowser ai-visual test "https://staging.your-site.com" homepage --html

Cross-Browser & Responsive

# Compare Chrome, Firefox, Safari rendering
npx cbrowser cross-browser "https://your-site.com" --html

# Test across mobile, tablet, desktop
npx cbrowser responsive "https://your-site.com" --html

# A/B comparison (staging vs production)
npx cbrowser ab "https://staging.your-site.com" "https://your-site.com" --html

UX Analysis Suite

Agent-Ready Audit

Analyze any website for AI-agent friendliness:

npx cbrowser agent-ready-audit "https://your-site.com" --html

Returns:

Findability score — Can agents locate elements? (ARIA labels, semantic HTML)
Stability score — Will selectors break? (hidden inputs, overlays)
Letter grade (A-F) with prioritized remediation and code examples

Competitive UX Benchmark

Run identical cognitive journeys across your site and competitors:

npx cbrowser competitive-benchmark \
  --sites "https://your-site.com,https://competitor-a.com,https://competitor-b.com" \
  --goal "sign up for free trial" \
  --persona first-timer \
  --html

Accessibility Empathy Mode

Simulate how users with disabilities experience your site:

npx cbrowser empathy-audit "https://your-site.com" \
  --goal "complete signup" \
  --disabilities "motor-tremor,low-vision,adhd" \
  --html

Available personas: motor-tremor, low-vision, cognitive-adhd, dyslexic, deaf, elderly

MCP Server Integration

CBrowser runs as an MCP server for Claude Desktop and claude.ai.

Remote MCP (claude.ai)

Public Demo Server (rate-limited, no auth):

https://cbrowser-mcp-demo.wyldfyre.ai/mcp

Deploy your own: see Remote MCP Server Guide

Local MCP (Claude Desktop)

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

43 MCP Tools

| Category | Tools | |----------|-------| | Navigation | navigate, screenshot, extract | | Interaction | click, smart_click, fill, scroll | | Testing | test_suite, repair_tests, flaky_check | | Visual | visual_baseline, visual_compare, responsive_test, cross_browser_test, ab_compare | | Cognitive | cognitive_journey_init, cognitive_journey_update_state, compare_personas | | Analysis | hunt_bugs, chaos_test, agent_ready_audit, competitive_benchmark, empathy_audit |

CI/CD Integration

GitHub Actions

name: CBrowser Tests
on: [pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: alexandriashai/cbrowser@v12
        with:
          test-file: tests/e2e/checkout.txt
          sensitivity: strict

Docker

docker run --rm -v $(pwd)/tests:/work/tests ghcr.io/alexandriashai/cbrowser:latest \
  test-suite tests/checkout.txt --html

Modular Architecture

Tree-shakeable imports for minimal bundle size:

// Import specific modules
import { runVisualRegression, runCrossBrowserTest } from 'cbrowser/visual';
import { runNLTestSuite, detectFlakyTests, repairTest } from 'cbrowser/testing';
import { huntBugs, runChaosTest, findElementByIntent } from 'cbrowser/analysis';
import { capturePerformanceBaseline, detectPerformanceRegression } from 'cbrowser/performance';

API Reference

import { CBrowser } from 'cbrowser';

const browser = new CBrowser({
  headless: true,
  persistent: true,  // Maintain cookies between sessions
});

await browser.navigate('https://example.com');

const result = await browser.smartClick('Sign In', {
  maxRetries: 3,
  minConfidence: 0.8  // v12.0.0: Raised threshold for reliable healing
});

const assertion = await browser.assert("page contains 'Welcome'");
if (!assertion.passed) {
  console.error(assertion.message);
}

await browser.close();

Configuration

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | CBROWSER_DATA_DIR | ~/.cbrowser | Data storage directory | | CBROWSER_HEADLESS | true | Run headless | | CBROWSER_BROWSER | chromium | Browser engine | | CBROWSER_TIMEOUT | 30000 | Default timeout (ms) |

API Key (for Cognitive Journeys)

npx cbrowser config set-api-key

Examples

| Example | Description | |---------|-------------| | examples/basic-usage.ts | Navigation, extraction, sessions | | examples/cognitive-journey.ts | Cognitive simulation with personas | | examples/visual-testing.ts | Visual regression, cross-browser, A/B | | examples/workflows/ | E2E recipes for common scenarios | | examples/ci-cd/ | GitHub Actions, GitLab CI setup |

License

Business Source License 1.1 (BSL-1.1)

✅ Free for non-production use: development, testing, personal projects, evaluation
✅ Read, modify, and contribute to the source
⚠️ Production use (including production testing pipelines) requires a commercial license

Note: Non-production use means evaluation of CBrowser itself, not using CBrowser as part of a production testing service.

Converts to Apache 2.0 on February 5, 2030.

For commercial licensing: [email protected]