cbrowser 7.4.19 → 7.9.0

package/examples/natural-language-tests/README.md

@@ -0,0 +1,77 @@
+# Natural Language Test Suites
+
+CBrowser supports writing browser tests in plain, human-readable text files. No code, no selectors, no framework boilerplate -- just describe what the test should do and CBrowser handles the rest.
+
+## Available Commands
+
+| Command | Description | Example |
+|---|---|---|
+| `# Test: <name>` | Start a new test case | `# Test: Login Flow` |
+| `go to <url>` | Navigate to a URL | `go to https://example.com` |
+| `click "<text>"` | Click an element by visible text | `click "Sign In"` |
+| `click the <description>` | Click an element by description | `click the hamburger menu icon` |
+| `fill "<field>" with "<value>"` | Fill a form field | `fill "Email" with "user@test.com"` |
+| `fill <field> with "<value>"` | Fill a form field (no quotes on field) | `fill Email with "user@test.com"` |
+| `type "<text>" in <field>` | Type into a specific field | `type "hello" in search box` |
+| `verify page contains "<text>"` | Assert text is visible on page | `verify page contains "Welcome"` |
+| `verify url contains "<path>"` | Assert current URL includes path | `verify url contains "/dashboard"` |
+| `take screenshot` | Capture the current page state | `take screenshot` |
+| `scroll down` | Scroll down the page | `scroll down` |
+| `scroll up` | Scroll up the page | `scroll up` |
+| `scroll down N times` | Scroll down multiple times | `scroll down 3 times` |
+| `wait <N> seconds` | Pause execution | `wait 2 seconds` |
+| `@viewport mobile` | Set viewport to mobile size | `@viewport mobile` |
+| `@viewport tablet` | Set viewport to tablet size | `@viewport tablet` |
+| `@viewport desktop` | Set viewport to desktop size | `@viewport desktop` |
+
+## Running Tests
+
+Run a test suite file:
+
+```bash
+npx cbrowser test-suite path/to/suite.txt
+```
+
+### Flags
+
+| Flag | Description |
+|---|---|
+| `--dry-run` | Parse and validate the test file without executing any browser actions. Useful for checking syntax. |
+| `--fuzzy-match` | Use fuzzy matching for click targets and text verification. Handles minor text differences gracefully. |
+| `--step-through` | Pause after each step and wait for Enter to continue. Great for debugging. |
+| `--verbose` | Print detailed logs for each step including timing, selectors found, and actions taken. |
+| `--html` | Generate an HTML report with screenshots and pass/fail status for each step. |
+
+### Examples
+
+```bash
+# Validate syntax without running
+npx cbrowser test-suite auth-flow-suite.txt --dry-run
+
+# Run with detailed output
+npx cbrowser test-suite e-commerce-suite.txt --verbose
+
+# Step through interactively for debugging
+npx cbrowser test-suite auth-flow-suite.txt --step-through
+
+# Generate an HTML report
+npx cbrowser test-suite e-commerce-suite.txt --html --verbose
+```
+
+## Tips for Writing Robust Tests
+
+1. **Use visible text for clicks.** Prefer `click "Sign In"` over trying to describe elements by position. CBrowser matches against visible text content first.
+
+2. **Add waits after navigation.** Pages need time to load. A `wait 2 seconds` after `go to` or after clicks that trigger navigation prevents flaky failures.
+
+3. **Take screenshots at key moments.** Screenshots at critical checkpoints make debugging failures much easier. Place them after verifications.
+
+4. **Verify before acting.** Use `verify page contains` to confirm the page is in the expected state before clicking or filling forms. This catches navigation issues early.
+
+5. **Keep tests focused.** Each `# Test:` block should test one specific flow. Smaller tests are easier to debug and maintain.
+
+6. **Use `@viewport` for responsive testing.** Set the viewport at the start of a test to validate mobile or tablet layouts. The viewport persists for the entire test case.
+
+7. **Use `--fuzzy-match` for dynamic content.** If text on the page varies slightly between runs (timestamps, counts), fuzzy matching prevents false failures.
+
+8. **Use `--dry-run` to validate new tests.** Before running a new suite against a live site, dry-run it to catch typos and syntax issues.

package/examples/natural-language-tests/auth-flow-suite.txt

@@ -0,0 +1,47 @@
+# Test: Login with Valid Credentials
+
+go to https://app.example.com/login
+verify page contains "Sign In"
+take screenshot
+fill "Email" with "user@example.com"
+fill "Password" with "SecurePass123!"
+click "Sign In"
+wait 3 seconds
+verify page contains "Dashboard"
+verify url contains "/dashboard"
+take screenshot
+
+# Test: Login with Invalid Credentials
+
+go to https://app.example.com/login
+verify page contains "Sign In"
+fill "Email" with "user@example.com"
+fill "Password" with "WrongPassword"
+click "Sign In"
+wait 2 seconds
+verify page contains "Invalid email or password"
+take screenshot
+verify url contains "/login"
+
+fill "Email" with "nonexistent@example.com"
+fill "Password" with "AnyPassword1"
+click "Sign In"
+wait 2 seconds
+verify page contains "Invalid email or password"
+take screenshot
+
+# Test: Password Reset Flow
+
+go to https://app.example.com/login
+verify page contains "Sign In"
+click "Forgot password?"
+wait 2 seconds
+verify page contains "Reset Password"
+verify url contains "/reset-password"
+take screenshot
+fill "Email" with "user@example.com"
+click "Send Reset Link"
+wait 3 seconds
+verify page contains "Check your email"
+verify page contains "reset link"
+take screenshot

package/examples/natural-language-tests/e-commerce-suite.txt

@@ -0,0 +1,96 @@
+# Test: Guest Checkout Flow
+
+go to https://shop.example.com
+verify page contains "Welcome"
+click "Shop All"
+wait 2 seconds
+scroll down 3 times
+click "Classic Cotton T-Shirt"
+verify page contains "Add to Cart"
+take screenshot
+click "Add to Cart"
+verify page contains "Added to cart"
+click "Cart"
+verify page contains "Classic Cotton T-Shirt"
+click "Proceed to Checkout"
+verify page contains "Checkout"
+click "Continue as Guest"
+fill "Email" with "guest@example.com"
+fill "First Name" with "Jordan"
+fill "Last Name" with "Lee"
+fill "Address" with "742 Evergreen Terrace"
+fill "City" with "Springfield"
+fill "Zip Code" with "62704"
+click "Continue to Shipping"
+verify page contains "Shipping Method"
+click "Standard Shipping"
+click "Continue to Payment"
+verify page contains "Payment"
+take screenshot
+fill "Card Number" with "4111111111111111"
+fill "Expiration" with "12/28"
+fill "CVV" with "123"
+click "Place Order"
+wait 3 seconds
+verify page contains "Order Confirmed"
+verify page contains "Thank you"
+take screenshot
+
+# Test: Search and Filter Products
+
+go to https://shop.example.com
+fill "Search" with "running shoes"
+click "Search"
+wait 2 seconds
+verify page contains "running shoes"
+take screenshot
+click "Price: Low to High"
+wait 1 seconds
+click "Size"
+click "10"
+click "Color"
+click "Black"
+click "Apply Filters"
+wait 2 seconds
+verify page contains "results"
+scroll down 2 times
+take screenshot
+click the first product in the results
+verify page contains "Add to Cart"
+verify page contains "running"
+verify url contains "/product/"
+take screenshot
+
+# Test: Mobile Responsive Checkout
+
+@viewport mobile
+go to https://shop.example.com
+verify page contains "Welcome"
+take screenshot
+click the hamburger menu icon
+wait 1 seconds
+click "Shop All"
+wait 2 seconds
+scroll down 2 times
+click the first product card
+verify page contains "Add to Cart"
+click "Add to Cart"
+verify page contains "Added to cart"
+take screenshot
+click the cart icon
+verify page contains "Cart"
+click "Checkout"
+verify page contains "Checkout"
+fill "Email" with "mobile@example.com"
+fill "First Name" with "Alex"
+fill "Last Name" with "Rivera"
+fill "Address" with "100 Main Street"
+fill "City" with "Portland"
+fill "Zip Code" with "97201"
+scroll down
+click "Continue to Shipping"
+wait 2 seconds
+click "Standard Shipping"
+click "Continue to Payment"
+take screenshot
+verify page contains "Payment"

package/examples/personas/accessibility-tester.json

@@ -0,0 +1,53 @@
+{
+  "name": "accessibility-tester",
+  "description": "User with visual impairments who relies on screen magnification and keyboard navigation",
+  "demographics": {
+    "age_range": "40-65",
+    "tech_level": "intermediate",
+    "device": "desktop"
+  },
+  "behaviors": {
+    "methodical": true,
+    "checks_edge_cases": true,
+    "documents_issues": false,
+    "follows_test_plans": false,
+    "uses_keyboard_navigation": true,
+    "avoids_mouse": true,
+    "uses_screen_magnification": true,
+    "prefers_high_contrast": true
+  },
+  "humanBehavior": {
+    "timing": {
+      "reactionTime": { "min": 800, "max": 2000 },
+      "clickDelay": { "min": 400, "max": 900 },
+      "typeSpeed": { "min": 120, "max": 250 },
+      "readingSpeed": 150,
+      "scrollPauseTime": { "min": 800, "max": 2000 }
+    },
+    "errors": {
+      "misClickRate": 0.15,
+      "doubleClickAccidental": 0.08,
+      "typoRate": 0.10,
+      "backtrackRate": 0.25
+    },
+    "mouse": {
+      "curvature": 0.6,
+      "jitter": 12,
+      "overshoot": 0.20,
+      "speed": "slow"
+    },
+    "attention": {
+      "pattern": "focused",
+      "scrollBehavior": "incremental",
+      "focusAreas": ["text", "cta"],
+      "distractionRate": 0.15
+    }
+  },
+  "context": {
+    "viewport": [1920, 1080],
+    "zoom": 200,
+    "assistiveTech": ["screen-magnifier", "keyboard-only"],
+    "preferredNavigation": "keyboard",
+    "colorScheme": "high-contrast"
+  }
+}

package/examples/workflows/accessibility-audit.md

@@ -0,0 +1,151 @@
+# Accessibility Audit with Bug Hunting and Persona Testing
+
+Find accessibility issues, get actionable fix recommendations, and validate usability across different user personas with assistive technology needs.
+
+## Prerequisites
+
+- Node.js 18+
+- CBrowser installed: `npm install -g cbrowser`
+- Target application at `https://app.example.com`
+
+## Step 1: Hunt for Accessibility Bugs
+
+Scan pages for WCAG violations, usability issues, and assistive technology problems.
+
+```bash
+npx cbrowser hunt "https://app.example.com"
+```
+
+### Sample Bug Report Output
+
+```
+Bug Hunt Report: https://app.example.com
+Scan completed: 2026-02-03T10:15:00Z
+Pages scanned: 5
+
+=== Critical (3 issues) ===
+
+BUG-001: Missing form labels
+  Page: /signup
+  Element: <input type="email" placeholder="Email">
+  WCAG: 1.3.1 (Info and Relationships), 4.1.2 (Name, Role, Value)
+  Impact: Screen readers cannot identify the purpose of this field
+  Recommendation: Add <label for="email">Email address</label> or aria-label
+
+BUG-002: Insufficient color contrast
+  Page: /dashboard
+  Element: .status-text (gray #999 on white #FFF)
+  WCAG: 1.4.3 (Contrast Minimum)
+  Impact: Text unreadable for users with low vision
+  Contrast ratio: 2.85:1 (minimum required: 4.5:1)
+  Recommendation: Darken text to at least #767676 for 4.54:1 ratio
+
+BUG-003: No skip navigation link
+  Page: / (all pages)
+  WCAG: 2.4.1 (Bypass Blocks)
+  Impact: Keyboard users must tab through 24 nav items on every page
+  Recommendation: Add a visually hidden "Skip to main content" link as the first focusable element
+
+=== Moderate (5 issues) ===
+
+BUG-004: Images missing alt text (3 instances on /products)
+BUG-005: Focus order breaks in modal dialogs (/settings)
+BUG-006: Timeout with no warning on /checkout (30s session)
+BUG-007: Error messages not announced to screen readers (/signup)
+BUG-008: Touch targets below 44x44px on mobile nav
+
+Summary: 3 critical, 5 moderate, 4 informational
+```
+
+## Step 2: Persona-Based Testing
+
+Test the application from the perspective of users with different needs.
+
+```bash
+# Test as a screen reader user
+npx cbrowser test-persona "https://app.example.com" --persona screen-reader-user \
+  --goal "Sign up for an account and navigate to the dashboard"
+
+# Test as an elderly user
+npx cbrowser test-persona "https://app.example.com" --persona elderly-user \
+  --goal "Find a product and add it to the cart"
+```
+
+### Sample Persona Output (Screen Reader User)
+
+```
+Persona Test: screen-reader-user
+Goal: Sign up for an account and navigate to the dashboard
+
+Step 1: Landing page
+  - Page title announced: "Welcome to App" [OK]
+  - Landmark regions found: header, nav, main, footer [OK]
+  - Heading hierarchy: h1 > h2 > h3 [OK]
+
+Step 2: Navigate to signup
+  - Found "Sign Up" link via navigation landmark [OK]
+  - Link purpose clear from text alone [OK]
+
+Step 3: Complete signup form
+  - Email field: NO LABEL ANNOUNCED [FAIL]
+  - Password field: label "Password" announced [OK]
+  - Submit button: "Create Account" announced [OK]
+  - Form errors: NOT announced on submission [FAIL]
+
+Step 4: Dashboard
+  - Page title changed: announced [OK]
+  - Dynamic content region: no live region set [FAIL]
+
+Result: PARTIAL SUCCESS (6/9 checks passed)
+Blockers: 3 issues would prevent independent task completion
+```
+
+## Step 3: Compare Personas
+
+Run the same journey across multiple personas to surface patterns.
+
+```bash
+npx cbrowser compare-personas \
+  --personas elderly-user,power-user \
+  --start "https://app.example.com" \
+  --goal "Complete signup"
+```
+
+```
+Persona Comparison: "Complete signup"
+
+                    elderly-user         power-user
+Completed:          Yes (with difficulty) Yes
+Time to complete:   4m 12s               0m 48s
+Errors encountered: 3                    0
+Friction points:    5                    1
+  - Small text        [x]               [ ]
+  - Unclear errors    [x]               [ ]
+  - Tiny click targets [x]              [ ]
+  - Complex password   [x]              [x]
+  - No text resize     [x]              [ ]
+
+Top recommendation: Increase base font size and touch targets
+```
+
+## Combining Audits
+
+Run a full accessibility workflow in one pass:
+
+```bash
+# Full audit pipeline
+npx cbrowser hunt "https://app.example.com" --output a11y-report.json
+npx cbrowser compare-personas \
+  --personas screen-reader-user,elderly-user,power-user \
+  --start "https://app.example.com" \
+  --goal "Complete signup" \
+  --html
+```
+
+## Next Steps
+
+- Fix critical issues first: missing labels and contrast failures block the most users.
+- Rerun `hunt` after fixes to verify remediation.
+- Add persona tests to CI to prevent regressions.
+- Expand to additional personas: `keyboard-only-user`, `cognitive-disability-user`, `low-vision-user`.
+- Generate compliance reports with `--format wcag21-aa` for stakeholder review.

package/examples/workflows/chaos-resilience-testing.md

@@ -0,0 +1,151 @@
+# Chaos Engineering for Web Applications
+
+Inject real-world failures into your web application and verify it degrades gracefully. Simulate network outages, slow responses, missing elements, and server errors to build confidence in your app's resilience.
+
+## Prerequisites
+
+- Node.js 18+
+- CBrowser installed: `npm install -g cbrowser`
+- Target application at `https://app.example.com`
+
+## Step 1: Run a Chaos Test
+
+CBrowser injects failures while monitoring how the application responds.
+
+```bash
+npx cbrowser chaos "https://app.example.com/dashboard"
+```
+
+This runs a default suite of chaos scenarios: network interruptions, slow API responses, DOM element removal, and error injection.
+
+## Step 2: Target Specific Chaos Scenarios
+
+Focus on individual failure modes for deeper analysis.
+
+```bash
+# Simulate network failures (offline, intermittent, packet loss)
+npx cbrowser chaos "https://app.example.com/dashboard" --scenario network-failure
+
+# Simulate slow API responses (2s, 5s, 10s, 30s delays)
+npx cbrowser chaos "https://app.example.com/dashboard" --scenario slow-responses
+
+# Remove critical DOM elements mid-session
+npx cbrowser chaos "https://app.example.com/dashboard" --scenario element-removal
+
+# Inject HTTP 500 errors on API calls
+npx cbrowser chaos "https://app.example.com/dashboard" --scenario server-errors
+```
+
+## Sample Chaos Test Output
+
+```
+Chaos Test Report: https://app.example.com/dashboard
+Generated: 2026-02-03T16:00:00Z
+Scenarios executed: 4
+
+=== Network Failure ===
+
+  Test: Complete offline (network disabled for 10s)
+    App behavior: Loading spinner appeared after 3s [OK]
+    Error message: "You're offline. Changes will sync when reconnected." [OK]
+    Data loss: None (localStorage cache used) [OK]
+    Recovery: Auto-reconnected and synced within 2s [OK]
+    Result: PASS
+
+  Test: Intermittent connectivity (50% packet loss for 15s)
+    App behavior: Partial data loaded, retry indicators shown [OK]
+    Error message: None shown to user [WARN - silent failure]
+    Data loss: 2 API calls dropped without retry [FAIL]
+    Recovery: Required manual page refresh [FAIL]
+    Result: FAIL
+    Recommendation: Implement automatic retry with exponential backoff
+
+=== Slow Responses ===
+
+  Test: API latency 5s
+    App behavior: Loading skeleton displayed [OK]
+    User feedback: Progress indicator visible [OK]
+    Timeout handling: No timeout applied [WARN]
+    Result: PASS
+
+  Test: API latency 30s
+    App behavior: Frozen UI, no loading indicator [FAIL]
+    User feedback: None for 30 seconds [FAIL]
+    Timeout handling: No timeout, user stuck [FAIL]
+    Result: FAIL
+    Recommendation: Set 10s timeout with retry option and loading state
+
+=== Element Removal ===
+
+  Test: Navigation bar removed
+    App behavior: No JavaScript errors [OK]
+    Fallback: Breadcrumb links still functional [OK]
+    Result: PASS
+
+  Test: Data table removed mid-render
+    App behavior: Uncaught TypeError in console [FAIL]
+    Fallback: Blank screen, no error boundary [FAIL]
+    Result: FAIL
+    Recommendation: Add React error boundaries around data components
+
+=== Server Errors (HTTP 500) ===
+
+  Test: Dashboard API returns 500
+    App behavior: "Something went wrong" message displayed [OK]
+    Retry option: "Try again" button present and functional [OK]
+    Logging: Error logged to monitoring service [OK]
+    Result: PASS
+
+  Test: Auth API returns 500
+    App behavior: Silent failure, dashboard shows stale data [FAIL]
+    User feedback: No indication of auth failure [FAIL]
+    Result: FAIL
+    Recommendation: Redirect to login with "Session expired" message
+
+Summary: 4 passed, 4 failed, 2 warnings
+Resilience score: 5.2/10
+```
+
+## Step 3: Chaos with Assertions
+
+Combine chaos injection with explicit assertions to create repeatable resilience tests.
+
+```bash
+npx cbrowser chaos "https://app.example.com/dashboard" \
+  --scenario network-failure \
+  --assert "error message is visible within 5 seconds" \
+  --assert "no data is lost after reconnection" \
+  --assert "no uncaught JavaScript errors in console"
+```
+
+```
+Chaos + Assertions: network-failure
+
+  [PASS] error message is visible within 5 seconds (shown at 3.1s)
+  [PASS] no data is lost after reconnection (all items verified)
+  [FAIL] no uncaught JavaScript errors in console
+    Found: TypeError: Cannot read properties of undefined (reading 'map')
+    Source: dashboard.js:142
+
+Results: 2 passed, 1 failed
+```
+
+## CI Integration
+
+Add resilience checks to your deployment pipeline:
+
+```yaml
+- name: Chaos Resilience Gate
+  run: |
+    npx cbrowser chaos "$STAGING_URL/dashboard" --scenario network-failure --ci
+    npx cbrowser chaos "$STAGING_URL/dashboard" --scenario slow-responses --ci
+    npx cbrowser chaos "$STAGING_URL/checkout" --scenario server-errors --ci
+```
+
+## Next Steps
+
+- Start with `network-failure` and `server-errors` scenarios, as these are the most common production issues.
+- Set a resilience score threshold in CI: `--min-score 7.0`.
+- Combine chaos tests with visual regression to catch UI breakage during failures.
+- Add custom scenarios for your domain: payment gateway timeouts, third-party script failures, CDN outages.
+- Run chaos tests against staging before every production deploy.

package/examples/workflows/e2e-login-checkout.md

@@ -0,0 +1,106 @@
+# End-to-End Login + Checkout Flow
+
+Automate a complete purchase journey from authentication through checkout using session persistence and natural language test assertions.
+
+## Prerequisites
+
+- Node.js 18+
+- CBrowser installed: `npm install -g cbrowser`
+- Target application running at `https://shop.example.com`
+
+## Step 1: Authenticate and Save Session
+
+Log in once and persist the authenticated session for reuse across tests.
+
+```bash
+# Navigate to the login page and authenticate
+npx cbrowser navigate "https://shop.example.com/login"
+
+# Fill credentials and submit (CBrowser uses AI to find form fields)
+npx cbrowser act "Enter username 'testuser@example.com' and password 'secure123', then click Sign In"
+
+# Save the authenticated session for later reuse
+npx cbrowser session save logged-in
+```
+
+## Step 2: Define the Test Suite
+
+Create a file called `checkout-flow.test.nl` with natural language test steps:
+
+```text
+suite: Checkout Flow
+session: logged-in
+
+test: Add item to cart
+  navigate to https://shop.example.com/products
+  click on the first "Add to Cart" button
+  assert the cart badge shows "1"
+
+test: Update cart quantity
+  navigate to https://shop.example.com/cart
+  change the quantity of the first item to 2
+  assert the subtotal updates to reflect 2 items
+
+test: Apply discount code
+  type "SAVE10" into the discount code field
+  click "Apply"
+  assert a discount line item appears showing 10% off
+
+test: Complete checkout
+  click "Proceed to Checkout"
+  assert the shipping address form is visible
+  select "Standard Shipping"
+  click "Place Order"
+  assert the page shows "Order Confirmed"
+  assert an order number is displayed
+```
+
+## Step 3: Run the Test Suite
+
+```bash
+npx cbrowser test-suite checkout-flow.test.nl
+```
+
+## Expected Output
+
+```
+CBrowser Test Suite: Checkout Flow
+Session: loaded "logged-in" (authenticated as testuser@example.com)
+
+  [PASS] Add item to cart (3.2s)
+    - Navigated to /products
+    - Clicked "Add to Cart" on "Wireless Headphones"
+    - Cart badge updated to "1"
+
+  [PASS] Update cart quantity (2.1s)
+    - Navigated to /cart
+    - Changed quantity from 1 to 2
+    - Subtotal updated: $49.98
+
+  [FAIL] Apply discount code (4.5s)
+    - Typed "SAVE10" into discount field
+    - Clicked "Apply"
+    - ASSERTION FAILED: Expected discount line item showing 10% off
+      Actual: Error message "Code expired" displayed
+
+  [PASS] Complete checkout (5.8s)
+    - Clicked "Proceed to Checkout"
+    - Shipping address form visible
+    - Selected "Standard Shipping"
+    - Clicked "Place Order"
+    - Order confirmed: #ORD-20260203-7842
+
+Results: 3 passed, 1 failed (15.6s)
+```
+
+## Tips
+
+- Sessions expire based on the target app's cookie lifetime. Re-run the save command if tests start failing on auth.
+- Add `--headed` to watch the browser execute each step: `npx cbrowser test-suite checkout-flow.test.nl --headed`
+- Combine with visual regression to catch UI changes during checkout.
+
+## Next Steps
+
+- Add edge-case tests: empty cart checkout, invalid payment, out-of-stock items.
+- Integrate into CI with `npx cbrowser test-suite checkout-flow.test.nl --ci --reporter json`.
+- Layer on persona testing to verify the flow works for different user types.