cbrowser 7.4.18 → 7.9.0

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.

package/examples/workflows/persona-comparison-report.md

@@ -0,0 +1,153 @@
+# Multi-Persona Comparison Report
+
+Run the same user journey through multiple personas to uncover usability gaps across different user types. Generate a comparative report showing where each persona succeeds, struggles, or fails entirely.
+
+## Prerequisites
+
+- Node.js 18+
+- CBrowser installed: `npm install -g cbrowser`
+- Target application at `https://shop.example.com`
+
+## Step 1: Establish a Visual Baseline
+
+Capture the current state of the application before running persona tests.
+
+```bash
+npx cbrowser visual-baseline "https://shop.example.com" --name pre-persona-test
+```
+
+This gives you a reference point to pair persona findings with specific UI elements.
+
+## Step 2: Define the Journey
+
+Choose a complete user journey that exercises core functionality. The comparison will run each persona through the identical goal.
+
+```bash
+npx cbrowser compare-personas \
+  --personas power-user,first-timer,elderly-user,mobile-user \
+  --start "https://shop.example.com" \
+  --goal "Complete purchase" \
+  --html
+```
+
+## Sample Report Output
+
+```
+Persona Comparison Report
+Journey: "Complete purchase"
+Start URL: https://shop.example.com
+Generated: 2026-02-03T11:00:00Z
+
+=== Summary Table ===
+
+Metric              power-user   first-timer  elderly-user  mobile-user
+-----------------------------------------------------------------------
+Completed:          Yes          Yes          No            Yes
+Time to complete:   1m 04s       3m 47s       --            2m 22s
+Total clicks:       8            14           21 (stuck)    11
+Errors hit:         0            2            4             1
+Friction points:    1            5            8             3
+Accessibility:      No issues    1 issue      6 issues      2 issues
+Satisfaction est.:  High         Medium       Low           Medium
+
+=== Detailed Breakdown by Persona ===
+
+--- power-user ---
+  Path: Home > Search "headphones" > Product page > Add to cart > Checkout > Confirm
+  Friction: Checkout form requires re-entering saved address (minor annoyance)
+  Notes: Used keyboard shortcuts, skipped optional fields, completed efficiently
+
+--- first-timer ---
+  Path: Home > Browse categories > Subcategory > Product page > Add to cart > Cart
+       > Confused by "Guest checkout" vs "Sign up" > Signed up > Checkout > Confirm
+  Friction:
+    - Could not find search bar immediately (hidden behind icon)
+    - "Guest checkout" label unclear, hesitated for 18s
+    - Password requirements not shown until after submission
+    - Shipping options lack delivery date estimates
+    - Coupon field prominent but no coupon available (felt like missing a deal)
+  Errors:
+    - Password rejected twice before requirements appeared
+    - Zip code validation rejected valid format "K1A 0B1"
+
+--- elderly-user ---
+  Path: Home > Struggled with navigation > Found products > Product page
+       > Add to cart > Cart > STUCK at checkout
+  Friction:
+    - Navigation dropdown menus close too quickly (requires precise mouse movement)
+    - Product text size 13px, hard to read without zooming
+    - "Add to Cart" button low contrast (light gray on white)
+    - Cart icon badge too small to notice (12px)
+    - Form fields lack visible borders (only bottom underline)
+    - Checkout timeout (60s) expired during address entry
+    - No option to increase text size
+    - Error messages disappear after 3 seconds
+  BLOCKED: Session timed out during checkout, no recovery path offered
+  Result: COULD NOT COMPLETE PURCHASE
+
+--- mobile-user ---
+  Path: Home > Hamburger menu > Products > Product page > Add to cart > Checkout > Confirm
+  Friction:
+    - Hamburger menu icon small (32x32, below 44px minimum)
+    - Product image gallery swipe conflicts with page scroll
+    - Keyboard covers checkout form fields on iOS
+  Errors:
+    - Tapped "Remove" instead of "Update quantity" (buttons too close)
+
+=== Cross-Persona Issue Heatmap ===
+
+Issue                          power  first  elderly  mobile
+-------------------------------------------------------------
+Small touch/click targets       -      -      HIGH     MED
+Text readability                -      -      HIGH     LOW
+Navigation complexity           -      MED    HIGH     LOW
+Form usability                  -      MED    HIGH     MED
+Error handling                  -      HIGH   HIGH     LOW
+Session/timeout                 -      -      HIGH     -
+Discoverability                 -      HIGH   MED      LOW
+
+=== Top Recommendations (Priority Order) ===
+
+1. CRITICAL: Add session timeout warning with option to extend (blocks elderly-user)
+2. HIGH: Increase minimum touch target size to 44x44px across all interactive elements
+3. HIGH: Show password requirements before first submission attempt
+4. HIGH: Increase base font size to 16px minimum, add text resize controls
+5. MEDIUM: Make search bar visible by default, not hidden behind an icon
+6. MEDIUM: Add visible borders to all form fields
+7. LOW: Add estimated delivery dates to shipping options
+```
+
+## Step 3: Generate Shareable HTML Report
+
+The `--html` flag produces a standalone HTML file with interactive filtering.
+
+```bash
+# Report saved to .cbrowser/reports/persona-comparison-<timestamp>.html
+open .cbrowser/reports/persona-comparison-*.html
+```
+
+The HTML report includes expandable sections for each persona, clickable screenshots at each step, and a filterable issue table.
+
+## Step 4: Retest After Fixes
+
+After addressing the findings, rerun the comparison to measure improvement.
+
+```bash
+# Run the same comparison after implementing fixes
+npx cbrowser compare-personas \
+  --personas power-user,first-timer,elderly-user,mobile-user \
+  --start "https://shop.example.com" \
+  --goal "Complete purchase" \
+  --html
+
+# Compare visual changes against the pre-fix baseline
+npx cbrowser visual-regression "https://shop.example.com" --baseline pre-persona-test
+```
+
+## Next Steps
+
+- Address critical and high-priority issues first, then retest the blocked persona (elderly-user).
+- Add more personas as needed: `keyboard-only-user`, `screen-reader-user`, `low-bandwidth-user`.
+- Run persona comparisons on other key journeys: account creation, returns, support contact.
+- Track improvement over time by archiving reports from each sprint.
+- Set a CI gate: all personas must complete the journey before merging to main.