cbrowser 17.6.0 → 18.0.0

package/docs/Tools-Testing-Quality.md

@@ -0,0 +1,251 @@
+# Testing & Quality Tools
+
+**Write tests in plain English. Let AI fix them when they break.**
+
+These 7 tools transform how you write, maintain, and debug tests. Natural language test suites, automatic repair of broken selectors, flaky test detection, and coverage mapping — all without writing a single line of test code.
+
+---
+
+## When to Use These Tools
+
+- **You hate writing test scripts** but need test coverage
+- **Your tests break constantly** when the UI changes
+- **You have flaky tests** that randomly pass and fail
+- **You don't know what's untested** and want a coverage map
+- **You want autonomous bug finding** without writing test cases
+
+---
+
+## Tools
+
+### `nl_test_inline`
+
+**What it does**: Run tests written in plain English, passed directly as text.
+
+**Why you'd use it**: Quick validation without creating test files. Great for ad-hoc testing and CI pipelines.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `tests` | string | Yes | Natural language test steps, one per line |
+| `stopOnFailure` | boolean | No | Stop at first failure. Default: false |
+| `screenshots` | boolean | No | Capture screenshot after each step. Default: false |
+
+**Example**:
+```json
+{
+  "tests": "go to https://example.com\nclick the login button\nfill email with test@example.com\nfill password with secret123\nclick submit\nverify the page contains Welcome",
+  "screenshots": true
+}
+```
+
+### Test Syntax
+
+| Instruction | Examples |
+|-------------|----------|
+| **Navigate** | `go to https://...`, `navigate to https://...`, `open https://...` |
+| **Click** | `click the login button`, `click Submit`, `press Enter` |
+| **Fill** | `type "value" in email field`, `fill username with "john"` |
+| **Wait** | `wait 2 seconds`, `wait for "Loading" to disappear` |
+| **Assert** | `verify page contains "Welcome"`, `verify url contains "/home"` |
+| **Screenshot** | `take screenshot` |
+
+---
+
+### `nl_test_file`
+
+**What it does**: Run a test suite from a file. Supports multiple test blocks and better organization.
+
+**Why you'd use it**: Maintain test suites as simple text files that anyone can read and edit.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `path` | string | Yes | Path to the test file |
+| `filter` | string | No | Run only tests matching this pattern |
+| `dryRun` | boolean | No | Parse tests without executing. Default: false |
+
+**Example**:
+```json
+{
+  "path": "/tests/checkout-flow.txt",
+  "filter": "payment"
+}
+```
+
+### Test File Format
+
+```txt
+# Test: Login Flow
+go to https://example.com
+click the login button
+fill email with user@example.com
+fill password with password123
+click submit
+verify url contains /dashboard
+
+# Test: Failed Login
+go to https://example.com/login
+fill email with wrong@example.com
+fill password with badpassword
+click submit
+verify page contains "Invalid credentials"
+```
+
+---
+
+### `generate_tests`
+
+**What it does**: Analyze a page and automatically generate test scenarios covering its functionality.
+
+**Why you'd use it**: Bootstrap test coverage for a new page or discover tests you didn't think to write.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `url` | string | Yes | Page to analyze |
+| `depth` | string | No | Test depth: `smoke`, `standard`, `comprehensive`. Default: `standard` |
+| `focus` | string | No | Focus area: `forms`, `navigation`, `errors`, `all` |
+
+**Example**:
+```json
+{
+  "url": "https://example.com/checkout",
+  "depth": "comprehensive",
+  "focus": "forms"
+}
+```
+
+**Returns**: Generated test file content with scenarios for happy paths, edge cases, and error conditions.
+
+---
+
+### `repair_test`
+
+**What it does**: Automatically fix a broken test by analyzing what changed and updating selectors/assertions.
+
+**Why you'd use it**: When a test fails due to UI changes, repair it instead of rewriting it.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `testPath` | string | Yes | Path to the broken test file |
+| `errorContext` | string | No | Error message or failure details |
+| `autoApply` | boolean | No | Apply fixes automatically. Default: false |
+| `verify` | boolean | No | Run repaired test to verify fix. Default: true |
+
+**Example**:
+```json
+{
+  "testPath": "/tests/checkout.txt",
+  "errorContext": "Element 'Submit Order' not found",
+  "autoApply": true
+}
+```
+
+**Returns**: Proposed fixes, what changed, and (if verified) confirmation the repaired test passes.
+
+---
+
+### `detect_flaky_tests`
+
+**What it does**: Run tests multiple times to identify which ones are unreliable.
+
+**Why you'd use it**: Find tests that randomly fail so you can fix them or quarantine them.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `testPath` | string | Yes | Test file to check |
+| `runs` | number | No | Number of runs. Default: 5 |
+| `threshold` | number | No | Failure percentage to mark as flaky. Default: 20 |
+
+**Example**:
+```json
+{
+  "testPath": "/tests/full-suite.txt",
+  "runs": 10,
+  "threshold": 10
+}
+```
+
+**Returns**: List of flaky tests with failure rates, timing variance, and suggested fixes.
+
+---
+
+### `coverage_map`
+
+**What it does**: Generate a test coverage map showing which pages and features are tested.
+
+**Why you'd use it**: Find gaps in test coverage before they become bugs in production.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `siteUrl` | string | Yes | Base URL of the site |
+| `testsPath` | string | Yes | Path to test files (supports glob patterns) |
+| `depth` | number | No | Crawl depth for discovering pages. Default: 3 |
+
+**Example**:
+```json
+{
+  "siteUrl": "https://example.com",
+  "testsPath": "/tests/**/*.txt",
+  "depth": 3
+}
+```
+
+**Returns**: Coverage matrix showing each page, what tests cover it, and what's untested.
+
+---
+
+### `hunt_bugs`
+
+**What it does**: Autonomously explore a site looking for bugs, errors, and accessibility issues — without being told what to test.
+
+**Why you'd use it**: Discover issues you didn't know existed. Great for exploratory testing and security reconnaissance.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `url` | string | Yes | Starting URL |
+| `scope` | string | No | Bug types: `all`, `functional`, `visual`, `accessibility`, `security` |
+| `depth` | number | No | Exploration depth. Default: 3 |
+| `maxPages` | number | No | Maximum pages to visit. Default: 20 |
+
+**Example**:
+```json
+{
+  "url": "https://example.com",
+  "scope": "all",
+  "depth": 4,
+  "maxPages": 50
+}
+```
+
+**Returns**: List of discovered issues with severity, reproduction steps, and screenshots.
+
+### What `hunt_bugs` Looks For
+
+- **Functional**: Broken links, form errors, JavaScript exceptions, failed network requests
+- **Visual**: Layout breaks, overlapping elements, missing images, rendering issues
+- **Accessibility**: Missing alt text, low contrast, keyboard traps, ARIA violations
+- **Security**: Exposed credentials, insecure forms, missing HTTPS, data in URLs
+
+---
+
+## Natural Language Test Advantages
+
+| Traditional Tests | CBrowser NL Tests |
+|-------------------|-------------------|
+| `await page.click('#btn-submit-order-v3')` | `click the Submit Order button` |
+| Breaks when ID changes | Finds button by intent |
+| Requires developer to write | Anyone can write |
+| Hard to read for non-devs | Self-documenting |
+| Manual repair on failure | Auto-repair available |
+
+---
+
+## Related Documentation
+
+- [Natural Language Tests](/docs/Natural-Language-Tests/) — Deep dive on NL test syntax
+- [AI Test Repair](/docs/AI-Test-Repair/) — How repair works
+- [Flaky Test Detection](/docs/Flaky-Test-Detection/) — Dealing with unreliable tests
+- [Test Coverage Map](/docs/Test-Coverage-Map/) — Understanding coverage
+
+---
+
+*Last updated: v17.6.0*

package/docs/Tools-Utilities.md

@@ -0,0 +1,176 @@
+# Utility Tools
+
+**Diagnostics, health checks, and infrastructure.**
+
+These 6 tools handle diagnostics, self-healing statistics, agent-readiness audits, and API key management (Enterprise). The tools that keep everything else running smoothly.
+
+---
+
+## Tools
+
+### `status`
+
+**What it does**: Get comprehensive CBrowser environment diagnostics.
+
+**Why you'd use it**: Debug configuration issues, verify installation, check capabilities.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| *none* | | | |
+
+**Returns**:
+- CBrowser version
+- Browser backend (Chromium/Firefox/WebKit)
+- Data directory location
+- Enterprise availability
+- Authentication status
+- Recent activity summary
+
+---
+
+### `heal_stats`
+
+**What it does**: Get statistics on the self-healing selector cache — how many selectors have been healed, hit rate, storage usage.
+
+**Why you'd use it**: Understand how well self-healing is working and whether the cache needs maintenance.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `detailed` | boolean | No | Include per-domain breakdown. Default: false |
+
+**Returns**:
+- Total healed selectors
+- Cache hit rate
+- Most frequently healed selectors
+- Cache age and size
+
+---
+
+### `agent_ready_audit`
+
+**What it does**: Audit a website for AI-agent friendliness. Scores how easily an autonomous AI could navigate and interact with the site.
+
+**Why you'd use it**: Know if your site is ready for the AI agent future. Sites that score well are also easier for humans to use.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `url` | string | Yes | URL to audit |
+| `depth` | number | No | Pages to crawl. Default: 5 |
+
+**Example**:
+```json
+{
+  "url": "https://example.com",
+  "depth": 10
+}
+```
+
+**Returns**:
+- Overall score (0-100)
+- Grade (A-F)
+- Category scores:
+  - Semantic HTML quality
+  - ARIA completeness
+  - Consistent navigation
+  - Clear form labels
+  - Predictable interactive elements
+  - Error message clarity
+- Specific recommendations
+
+### Scoring
+
+| Grade | Score | Meaning |
+|-------|-------|---------|
+| A | 90-100 | Excellent agent compatibility |
+| B | 80-89 | Good, minor improvements possible |
+| C | 70-79 | Acceptable, some friction for agents |
+| D | 60-69 | Poor, significant navigation challenges |
+| F | <60 | Hostile to automated interaction |
+
+---
+
+## API Key Management 🔒 Enterprise
+
+> **All API key tools require CBrowser Enterprise.**
+> API keys enable autonomous cognitive journeys that make AI decisions without human orchestration.
+
+### `set_api_key` 🔒 Enterprise
+
+**What it does**: Store an Anthropic API key in encrypted session memory for autonomous journey execution.
+
+**Why you'd use it**: Enable `cognitive_journey_autonomous` and other features that require AI decision-making.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `api_key` | string | Yes | Your Anthropic API key (starts with `sk-ant-`) |
+
+**Security**: Keys are stored in memory only, not persisted to disk. They're cleared when the session ends.
+
+---
+
+### `clear_api_key` 🔒 Enterprise
+
+**What it does**: Remove the stored API key from session memory.
+
+**Why you'd use it**: Clear credentials when you're done or before switching accounts.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| *none* | | | |
+
+---
+
+### `api_key_status` 🔒 Enterprise
+
+**What it does**: Check if an API key is currently stored without revealing the key itself.
+
+**Why you'd use it**: Verify setup before running autonomous operations.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| *none* | | | |
+
+**Returns**:
+- Key stored: yes/no
+- Key prefix (first 8 chars, masked)
+- When stored (timestamp)
+
+---
+
+### `get_api_key_prompt` 🔒 Enterprise
+
+**What it does**: Get instructions for obtaining an Anthropic API key.
+
+**Why you'd use it**: Help users who need to set up API access.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| *none* | | | |
+
+**Returns**: Step-by-step instructions for creating an Anthropic account and generating an API key.
+
+---
+
+## Demo vs Enterprise
+
+| Tool | Demo | Enterprise |
+|------|------|------------|
+| `status` | ✅ | ✅ |
+| `heal_stats` | ✅ | ✅ |
+| `agent_ready_audit` | ✅ | ✅ |
+| `set_api_key` | ❌ | ✅ |
+| `clear_api_key` | ❌ | ✅ |
+| `api_key_status` | ❌ | ✅ |
+| `get_api_key_prompt` | ❌ | ✅ |
+
+---
+
+## Related Documentation
+
+- [Tools Overview](/docs/Tools-Overview/) — All tools by category
+- [MCP Server](/docs/MCP-Server/) — Running CBrowser locally
+- [Remote MCP Server](/docs/Remote-MCP-Server/) — Cloud deployment
+
+---
+
+*Last updated: v17.6.0*

package/docs/Tools-Visual-Performance.md

@@ -0,0 +1,272 @@
+# Visual & Performance Tools
+
+**Catch regressions before your users see them.**
+
+These 10 tools detect visual changes, performance degradation, cross-browser rendering differences, and responsive layout breakage. Stop finding out about broken deploys from customer complaints.
+
+---
+
+## When to Use These Tools
+
+- **You're deploying to staging** and want to verify nothing visual broke
+- **Performance matters** and you need to catch slowdowns before production
+- **Your site looks different in Safari** and you need to know exactly what's wrong
+- **Mobile layouts keep breaking** and you want automated viewport testing
+- **You want chaos engineering** to test resilience under failure conditions
+
+---
+
+## Tools
+
+### `visual_baseline`
+
+**What it does**: Capture a visual baseline (screenshot + metadata) for a URL to compare against later.
+
+**Why you'd use it**: Establish what "correct" looks like so you can detect when it changes.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `url` | string | Yes | URL to capture |
+| `name` | string | Yes | Name for this baseline |
+| `viewport` | object | No | Width/height. Default: 1280x720 |
+| `fullPage` | boolean | No | Capture entire page. Default: false |
+
+**Example**:
+```json
+{
+  "url": "https://example.com",
+  "name": "homepage-desktop",
+  "viewport": { "width": 1920, "height": 1080 },
+  "fullPage": true
+}
+```
+
+---
+
+### `visual_regression`
+
+**What it does**: Compare current page state against a saved baseline using AI visual analysis.
+
+**Why you'd use it**: Detect meaningful visual changes while ignoring irrelevant differences (timestamps, ads, dynamic content).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `url` | string | Yes | URL to test |
+| `baseline` | string | Yes | Baseline name to compare against |
+| `threshold` | number | No | Difference tolerance (0-100). Default: 5 |
+
+**Example**:
+```json
+{
+  "url": "https://staging.example.com",
+  "baseline": "homepage-desktop"
+}
+```
+
+**Returns**: Pass/fail, difference percentage, annotated diff image, list of changed regions.
+
+---
+
+### `ab_comparison`
+
+**What it does**: Compare two different URLs visually — staging vs production, old design vs new design.
+
+**Why you'd use it**: Side-by-side comparison when you don't have a saved baseline, or when comparing different implementations.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `urlA` | string | Yes | First URL (e.g., production) |
+| `urlB` | string | Yes | Second URL (e.g., staging) |
+| `labelA` | string | No | Label for first URL. Default: "A" |
+| `labelB` | string | No | Label for second URL. Default: "B" |
+| `viewport` | object | No | Viewport dimensions |
+
+**Example**:
+```json
+{
+  "urlA": "https://example.com/pricing",
+  "urlB": "https://staging.example.com/pricing",
+  "labelA": "Production",
+  "labelB": "Staging"
+}
+```
+
+**Returns**: Side-by-side comparison, diff overlay, list of differences.
+
+---
+
+### `perf_baseline`
+
+**What it does**: Capture performance baseline (Core Web Vitals, load times, resource counts) for a URL.
+
+**Why you'd use it**: Know what your current performance is so you can detect regressions.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `url` | string | Yes | URL to measure |
+| `name` | string | Yes | Baseline name |
+| `runs` | number | No | Number of measurements to average. Default: 3 |
+
+**Example**:
+```json
+{
+  "url": "https://example.com",
+  "name": "homepage-perf",
+  "runs": 5
+}
+```
+
+**Returns**: LCP, FCP, TTFB, CLS, total load time, resource breakdown, with "good/needs-improvement/poor" ratings.
+
+---
+
+### `perf_regression`
+
+**What it does**: Compare current performance against a baseline with configurable sensitivity.
+
+**Why you'd use it**: Catch performance regressions before they ship.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `url` | string | Yes | URL to test |
+| `baseline` | string | Yes | Baseline name |
+| `profile` | string | No | Sensitivity: `strict`, `normal`, `lenient`. Default: `normal` |
+| `thresholdLcp` | number | No | LCP regression threshold %. Default: 20 |
+| `thresholdFcp` | number | No | FCP regression threshold %. Default: 20 |
+
+**Example**:
+```json
+{
+  "url": "https://staging.example.com",
+  "baseline": "homepage-perf",
+  "profile": "strict"
+}
+```
+
+**Returns**: Pass/fail, metric comparisons, which thresholds were exceeded.
+
+---
+
+### `list_baselines`
+
+**What it does**: List all saved visual and performance baselines.
+
+**Why you'd use it**: See what baselines exist before running regression tests.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `type` | string | No | Filter: `visual`, `performance`, `all`. Default: `all` |
+
+---
+
+### `cross_browser_test`
+
+**What it does**: Render a page in Chromium, Firefox, and WebKit and compare the results.
+
+**Why you'd use it**: Find browser-specific rendering bugs.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `url` | string | Yes | URL to test |
+| `browsers` | array | No | Browsers to test. Default: `["chromium", "firefox", "webkit"]` |
+| `viewport` | object | No | Viewport dimensions |
+
+**Example**:
+```json
+{
+  "url": "https://example.com/complex-layout",
+  "browsers": ["chromium", "webkit"]
+}
+```
+
+**Returns**: Screenshots from each browser, diff analysis, list of rendering differences.
+
+---
+
+### `cross_browser_diff`
+
+**What it does**: Quick comparison of key metrics (layout, fonts, colors) across browsers without full screenshots.
+
+**Why you'd use it**: Faster browser comparison when you just need to know if there are issues.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `url` | string | Yes | URL to compare |
+| `browsers` | array | No | Browsers to test |
+
+---
+
+### `responsive_test`
+
+**What it does**: Test page rendering across different viewport sizes (mobile, tablet, desktop).
+
+**Why you'd use it**: Catch responsive layout breakage.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `url` | string | Yes | URL to test |
+| `viewports` | array | No | Viewport presets or custom sizes. Default: `["mobile", "tablet", "desktop"]` |
+
+**Example**:
+```json
+{
+  "url": "https://example.com",
+  "viewports": ["mobile", "tablet", "desktop-lg"]
+}
+```
+
+### Viewport Presets
+
+| Preset | Dimensions |
+|--------|------------|
+| `mobile` | 375x667 |
+| `tablet` | 768x1024 |
+| `desktop` | 1280x720 |
+| `desktop-lg` | 1920x1080 |
+
+**Returns**: Screenshots at each viewport, flagged layout issues, overflow problems.
+
+---
+
+### `chaos_test`
+
+**What it does**: Inject failures to test site resilience — offline mode, network latency, blocked resources.
+
+**Why you'd use it**: Ensure your site degrades gracefully under adverse conditions.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `url` | string | Yes | URL to test |
+| `chaos` | string | Yes | Type: `offline`, `slow-network`, `block-scripts`, `block-images`, `block-fonts` |
+| `duration` | number | No | How long to apply chaos (seconds). Default: 10 |
+
+**Example**:
+```json
+{
+  "url": "https://example.com/checkout",
+  "chaos": "slow-network"
+}
+```
+
+**Returns**: How the page behaves under stress, errors encountered, recovery behavior.
+
+---
+
+## Sensitivity Profiles for Performance
+
+| Profile | LCP | FCP | TTFB | Use Case |
+|---------|-----|-----|------|----------|
+| `strict` | 10% | 10% | 15% | Pre-production, critical paths |
+| `normal` | 20% | 20% | 25% | Regular CI/CD |
+| `lenient` | 35% | 35% | 40% | Early development, high variance |
+
+---
+
+## Related Documentation
+
+- [Performance Regression](/docs/Performance-Regression/) — Deep dive on perf testing
+- [Tools Overview](/docs/Tools-Overview/) — All tools by category
+
+---
+
+*Last updated: v17.6.0*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cbrowser",
-  "version": "17.6.0",
+  "version": "18.0.0",
   "type": "module",
   "description": "Cognitive browser automation that thinks like your users—and helps AI agents navigate too. Simulate real user cognition with abandonment detection, constitutional safety, chaos engineering, and UX friction discovery. Sites that pass CBrowser's cognitive tests are easier for both humans and AI agents to navigate.",
   "main": "dist/index.js",