cbrowser 17.6.1 → 18.1.0

package/docs/Tools-Session-State.md

@@ -0,0 +1,272 @@
+# Session & State Tools
+
+**Stay logged in. Handle Cloudflare. Test sites that fight back.**
+
+These 14 tools manage browser sessions, handle state persistence, and (for Enterprise) bypass bot detection on sites you're authorized to test. Stop re-authenticating between test runs.
+
+---
+
+## When to Use These Tools
+
+- **You're testing authenticated flows** and tired of logging in every time
+- **Your tests run against Cloudflare-protected sites** you own
+- **Browser crashes are disrupting your automation** and you need recovery
+- **You need clean state** between test scenarios
+
+---
+
+## Session Management Tools
+
+### `save_session`
+
+**What it does**: Save the current browser session — cookies, localStorage, sessionStorage, and URL — for later restoration.
+
+**Why you'd use it**: Authenticate once, save the session, reuse it across multiple test runs.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | Yes | Name for this session |
+| `url` | string | No | Navigate to this URL before saving (if not already there) |
+
+**Example**:
+```json
+{
+  "name": "github-logged-in"
+}
+```
+
+**Note**: Session files include cookies with expiration dates. Sessions may need to be recreated when cookies expire.
+
+---
+
+### `load_session`
+
+**What it does**: Restore a previously saved session, including cookies and storage.
+
+**Why you'd use it**: Start tests already logged in, without going through authentication flow.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | Yes | Session name to load |
+| `navigateToUrl` | boolean | No | Navigate to the saved URL after loading. Default: true |
+
+**Example**:
+```json
+{
+  "name": "github-logged-in"
+}
+```
+
+---
+
+### `list_sessions`
+
+**What it does**: List all saved sessions with metadata (creation date, domain, expiration).
+
+**Why you'd use it**: See what sessions are available and whether they're still valid.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `detailed` | boolean | No | Include full metadata. Default: false |
+
+---
+
+### `delete_session`
+
+**What it does**: Delete a saved session by name.
+
+**Why you'd use it**: Clean up old or expired sessions.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | Yes | Session to delete |
+
+---
+
+## Browser State Tools
+
+### `reset_browser`
+
+**What it does**: Reset the browser to a clean state — clears all cookies, storage, and cache.
+
+**Why you'd use it**: Ensure test isolation by starting from a blank slate.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `preserveSession` | string | No | Session name to preserve during reset |
+
+---
+
+### `browser_health`
+
+**What it does**: Check if the browser is healthy and responsive.
+
+**Why you'd use it**: Diagnose issues when automation stops responding.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| *none* | | | |
+
+**Returns**:
+- Browser status (healthy/unhealthy)
+- Memory usage
+- Open pages count
+- Last activity timestamp
+- Any error conditions
+
+---
+
+### `browser_recover`
+
+**What it does**: Attempt to recover from a browser crash or unresponsive state by restarting.
+
+**Why you'd use it**: Automatic recovery when things go wrong.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `preserveState` | boolean | No | Try to restore tabs after restart. Default: true |
+
+**Note**: v11.9.0 added exponential backoff for crash recovery.
+
+---
+
+## Stealth Mode Tools 🔒 Enterprise
+
+> **All stealth tools require CBrowser Enterprise.**
+> Stealth mode is constitutional — it only works on domains you've explicitly authorized with signed attestation.
+> This prevents misuse while enabling legitimate testing of your own properties.
+
+### `stealth_enable` 🔒 Enterprise
+
+**What it does**: Enable stealth mode to bypass bot detection on authorized domains.
+
+**Why you'd use it**: Test your own sites that use aggressive bot protection.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `authorized_domains` | array | Yes | Domains you're authorized to test |
+| `signed_by` | string | Yes | Your email confirming authorization |
+| `proxy_server` | string | No | Proxy server URL |
+| `proxy_username` | string | No | Proxy authentication |
+| `proxy_password` | string | No | Proxy authentication |
+
+**Example**:
+```json
+{
+  "authorized_domains": ["example.com", "staging.example.com"],
+  "signed_by": "yourname@example.com"
+}
+```
+
+**Constitutional Requirement**: Stealth only works on the specific domains you've authorized. Attempts to use it elsewhere fail with a security error.
+
+---
+
+### `stealth_disable` 🔒 Enterprise
+
+**What it does**: Disable stealth mode, returning to standard browser fingerprint.
+
+**Why you'd use it**: When you're done testing protected sites.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| *none* | | | |
+
+---
+
+### `stealth_status` 🔒 Enterprise
+
+**What it does**: Check current stealth configuration and status.
+
+**Why you'd use it**: Verify stealth is configured correctly before testing.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| *none* | | | |
+
+**Returns**: Enabled status, authorized domains, proxy configuration (masked), enterprise version.
+
+---
+
+### `stealth_check` 🔒 Enterprise
+
+**What it does**: Check if a specific action is allowed on a URL under current stealth configuration.
+
+**Why you'd use it**: Verify authorization before attempting an action that might fail.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `action` | string | Yes | Action to check (e.g., "navigate", "fill") |
+| `url` | string | Yes | URL where action would occur |
+
+---
+
+### `stealth_diagnose` 🔒 Enterprise
+
+**What it does**: Analyze what bot detection methods a site uses.
+
+**Why you'd use it**: Understand what you're up against before enabling stealth.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `url` | string | Yes | URL to analyze |
+
+**Returns**: Detection methods found (fingerprinting, IP reputation, WAF type, JavaScript challenges).
+
+---
+
+## Cloudflare Tools 🔒 Enterprise
+
+### `cloudflare_detect` 🔒 Enterprise
+
+**What it does**: Detect if a page is showing a Cloudflare challenge or block.
+
+**Why you'd use it**: Know if you need to handle Cloudflare before proceeding.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `url` | string | Yes | URL to check |
+
+**Returns**: Challenge type (JS challenge, Turnstile, block), detection confidence.
+
+---
+
+### `cloudflare_wait` 🔒 Enterprise
+
+**What it does**: Wait for a Cloudflare challenge to complete naturally.
+
+**Why you'd use it**: Let stealth mode handle the challenge while you wait.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `url` | string | Yes | URL with Cloudflare challenge |
+| `timeout` | number | No | Max wait time in seconds. Default: 30 |
+
+**Returns**: Success/failure, final page state, time taken.
+
+---
+
+## Why Stealth Requires Authorization
+
+CBrowser's stealth mode is designed for legitimate testing:
+
+1. **You specify exactly which domains** you're authorized to test
+2. **You sign with your email** creating an audit trail
+3. **Attempts on unauthorized domains fail** immediately
+4. **Enterprise license is required** ensuring accountability
+
+This prevents misuse while enabling:
+- Testing your own bot-protected sites
+- QA on staging environments with production security
+- Security assessments of your own properties
+
+---
+
+## Related Documentation
+
+- [Constitutional Safety](/docs/Constitutional-Safety/) — How CBrowser classifies and limits actions
+- [Tools Overview](/docs/Tools-Overview/) — All tools by category
+
+---
+
+*Last updated: v17.6.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*