cbrowser 18.62.0 → 18.63.1

package/docs/Tools-Testing-Quality.md

@@ -1,257 +0,0 @@
-> **This documentation is no longer maintained here.**
->
-> For the latest version, please visit: **[Testing & Quality Tools](https://cbrowser.ai/docs/Tools-Testing-Quality)**
-
----
-
-# 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

@@ -1,182 +0,0 @@
-> **This documentation is no longer maintained here.**
->
-> For the latest version, please visit: **[Utility Tools](https://cbrowser.ai/docs/Tools-Utilities)**
-
----
-
-# 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

@@ -1,278 +0,0 @@
-> **This documentation is no longer maintained here.**
->
-> For the latest version, please visit: **[Visual & Performance Tools](https://cbrowser.ai/docs/Tools-Visual-Performance)**
-
----
-
-# 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*