API Reference

Use CBrowser from TypeScript or JavaScript code.

---

Installation

npm install cbrowser

---

Quick Start

import { CBrowser } from 'cbrowser';

const browser = new CBrowser({
  headless: true,
  persistent: true,
});

await browser.navigate('https://example.com');
await browser.smartClick('Login');
await browser.fill('email', '[email protected]');
await browser.close();

---

CBrowser Class

Constructor

const browser = new CBrowser(options?: CBrowserOptions);

Options:

Option	Type	Default	Description
headless	boolean	true	Run without visible browser
persistent	boolean	false	Keep context between calls
browser	string	'chromium'	Browser engine
timeout	number	30000	Default timeout (ms)
viewport	object	-	{ width, height }
device	string	-	Device to emulate

navigate(url)

const result = await browser.navigate(url: string): Promise<NavigationResult>;

Returns:

interface NavigationResult {
  url: string;
  title: string;
  screenshot: string;  // Base64 or file path
  loadTime: number;
  errors: string[];
  warnings: string[];
}

smartClick(selector, options?)

const result = await browser.smartClick(
  selector: string,
  options?: SmartClickOptions
): Promise<ClickResult>;

Options:

interface SmartClickOptions {
  maxRetries?: number;  // Default: 3
  force?: boolean;      // Bypass safety
}

Returns:

interface ClickResult {
  success: boolean;
  finalSelector: string;  // The selector that worked
  attempts: Array<{
    selector: string;
    success: boolean;
    error?: string;
  }>;
  aiSuggestion?: string;  // If all attempts failed
}

fill(selector, value)

await browser.fill(selector: string, value: string): Promise<void>;

assert(assertion)

const result = await browser.assert(assertion: string): Promise<AssertionResult>;

Returns:

interface AssertionResult {
  passed: boolean;
  message: string;
  expected: string;
  actual: string;
}

screenshot(options?)

const result = await browser.screenshot(options?: ScreenshotOptions): Promise<string>;

Options:

interface ScreenshotOptions {
  path?: string;      // File path
  fullPage?: boolean; // Capture full page
  element?: string;   // Capture element only
}

extract(what)

const result = await browser.extract(what: string): Promise<ExtractResult>;

Returns:

interface ExtractResult {
  data: unknown;
  screenshot: string;
}

close()

await browser.close(): Promise<void>;

---

Test Suite Functions

parseNLTestSuite(content, name)

Parse natural language test files into structured test suites.

import { parseNLTestSuite } from 'cbrowser';

const suite = parseNLTestSuite(
  content: string,
  name: string
): NLTestSuite;

Returns:

interface NLTestSuite {
  name: string;
  tests: NLTestCase[];
}

interface NLTestCase {
  name: string;
  steps: NLTestStep[];
}

interface NLTestStep {
  instruction: string;
  type: 'navigate' | 'click' | 'fill' | 'assert' | 'wait' | 'screenshot';
  args: Record<string, string>;
}

runNLTestSuite(suite, options?)

import { runNLTestSuite } from 'cbrowser';

const result = await runNLTestSuite(
  suite: NLTestSuite,
  options?: NLTestOptions
): Promise<NLTestSuiteResult>;

Options:

interface NLTestOptions {
  continueOnFailure?: boolean;
  screenshotOnFailure?: boolean;
  headless?: boolean;
  timeout?: number;
}

Returns:

interface NLTestSuiteResult {
  suiteName: string;
  timestamp: string;
  duration: number;
  summary: {
    total: number;
    passed: number;
    failed: number;
    passRate: number;
  };
  testResults: NLTestResult[];
}

formatNLTestReport(result)

import { formatNLTestReport } from 'cbrowser';

const report = formatNLTestReport(result: NLTestSuiteResult): string;

---

Test Repair Functions

repairTestSuite(suite, options?)

import { repairTestSuite } from 'cbrowser';

const result = await repairTestSuite(
  suite: NLTestSuite,
  options?: RepairOptions
): Promise<RepairResult>;

Options:

interface RepairOptions {
  autoApply?: boolean;
  verifyRepairs?: boolean;
  headless?: boolean;
}

Returns:

interface RepairResult {
  testResults: TestRepairResult[];
  summary: {
    totalFailed: number;
    repaired: number;
    repairSuccessRate: number;
  };
}

formatRepairReport(result)

import { formatRepairReport } from 'cbrowser';

const report = formatRepairReport(result: RepairResult): string;

exportRepairedTest(testResult)

import { exportRepairedTest } from 'cbrowser';

const testContent = exportRepairedTest(result: TestRepairResult): string;

---

Flaky Detection Functions

detectFlakyTests(suite, options?)

import { detectFlakyTests } from 'cbrowser';

const result = await detectFlakyTests(
  suite: NLTestSuite,
  options?: FlakyTestOptions
): Promise<FlakyTestSuiteResult>;

Options:

interface FlakyTestOptions {
  runs?: number;              // Default: 5
  flakinessThreshold?: number; // Default: 20
  delayBetweenRuns?: number;  // Default: 500
  headless?: boolean;
}

Returns:

interface FlakyTestSuiteResult {
  suiteName: string;
  timestamp: string;
  duration: number;
  runsPerTest: number;
  testAnalyses: FlakyTestAnalysis[];
  summary: {
    totalTests: number;
    stablePassTests: number;
    stableFailTests: number;
    flakyTests: number;
    mostFlakyTest?: string;
    mostFlakyStep?: string;
    overallFlakinessScore: number;
  };
}

interface FlakyTestAnalysis {
  testName: string;
  totalRuns: number;
  passCount: number;
  failCount: number;
  flakinessScore: number;
  isFlaky: boolean;
  classification: 'stable_pass' | 'stable_fail' | 'flaky' | 'mostly_pass' | 'mostly_fail';
  stepAnalysis: FlakyStepAnalysis[];
  avgDuration: number;
  durationVariance: number;
}

formatFlakyTestReport(result)

import { formatFlakyTestReport } from 'cbrowser';

const report = formatFlakyTestReport(result: FlakyTestSuiteResult): string;

---

Persona Functions

runCognitiveJourney(options)

Note: This function is not in the main cbrowser export. Import it from the cognitive submodule, or use the CLI: npx cbrowser cognitive-journey.

import { runCognitiveJourney } from 'cbrowser/analysis';

const result = await runCognitiveJourney(options: JourneyOptions): Promise<JourneyResult>;

Options:

interface JourneyOptions {
  persona: string;
  startUrl: string;
  goal: string;
  maxSteps?: number;
  headless?: boolean;
}

comparePersonas(options)

import { comparePersonas } from 'cbrowser';

const result = await comparePersonas(options: CompareOptions): Promise<ComparisonResult>;

Options:

interface CompareOptions {
  startUrl: string;
  goal: string;
  personas: string[];
  headless?: boolean;
}

---

Session Functions

saveSession(name, options?)

await browser.saveSession(name: string, options?: SessionOptions): Promise<void>;

loadSession(name)

await browser.loadSession(name: string): Promise<void>;

listSessions()

const sessions = await browser.listSessions(): Promise<string[]>;

---

Self-Healing Functions

getSelectorCacheStats()

const stats = browser.getSelectorCacheStats(): SelectorCacheStats;

Returns:

interface SelectorCacheStats {
  totalEntries: number;
  totalSuccesses: number;
  topDomains: Array<{ domain: string; count: number }>;
}

clearSelectorCache()

browser.clearSelectorCache(): void;

---

Complete Example

import {
  CBrowser,
  parseNLTestSuite,
  runNLTestSuite,
  detectFlakyTests,
  repairTestSuite,
  formatNLTestReport,
  formatFlakyTestReport,
  formatRepairReport,
} from 'cbrowser';

// Run natural language tests
const suite = parseNLTestSuite(`
  # Test: Homepage
  go to https://example.com
  verify title contains "Example"
  click "More information"
  verify url contains "iana.org"
`, "My Tests");

const testResult = await runNLTestSuite(suite, {
  continueOnFailure: true,
  screenshotOnFailure: true,
});

console.log(formatNLTestReport(testResult));

// Check for flaky tests
const flakyResult = await detectFlakyTests(suite, {
  runs: 10,
  flakinessThreshold: 25,
});

console.log(formatFlakyTestReport(flakyResult));

// Repair any broken tests
if (testResult.summary.failed > 0) {
  const repairResult = await repairTestSuite(suite, {
    autoApply: true,
    verifyRepairs: true,
  });
  console.log(formatRepairReport(repairResult));
}

---

Related

• CLI Reference - Command-line usage
• Natural Language Tests - Test file format
• Examples - More code samples

---

Copyright: (c) 2026 Alexa Eden.

License: MIT License

Contact: [email protected]