cbrowser 7.4.19 → 7.9.0

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.

package/examples/workflows/visual-regression-ci.md

@@ -0,0 +1,123 @@
+# Visual Regression Testing for CI
+
+Catch unintended visual changes before they reach production. Capture baseline screenshots, run comparisons across browsers and viewports, and surface pixel-level diffs.
+
+## Prerequisites
+
+- Node.js 18+
+- CBrowser installed: `npm install -g cbrowser`
+- Target application deployed at `https://app.example.com`
+
+## Step 1: Capture a Baseline
+
+Take reference screenshots of your production pages to compare future changes against.
+
+```bash
+# Capture baseline screenshots of key pages
+npx cbrowser visual-baseline "https://app.example.com" --name production
+
+# Optionally target specific pages
+npx cbrowser visual-baseline "https://app.example.com/dashboard" --name production-dashboard
+npx cbrowser visual-baseline "https://app.example.com/settings" --name production-settings
+```
+
+This stores timestamped screenshots in `.cbrowser/baselines/production/`.
+
+## Step 2: Run Visual Regression
+
+After deploying a new build to staging, compare against the baseline.
+
+```bash
+npx cbrowser visual-regression "https://staging.example.com" --baseline production
+```
+
+## Expected Diff Output
+
+```
+Visual Regression Report: staging vs production
+Generated: 2026-02-03T14:30:00Z
+
+Page: /
+  Similarity: 99.7%  [PASS]
+  Diff pixels: 342 of 2,073,600
+
+Page: /dashboard
+  Similarity: 94.2%  [FAIL - below 98% threshold]
+  Diff pixels: 120,432 of 2,073,600
+  Changes detected:
+    - Header region: navigation bar height changed (+4px)
+    - Sidebar: new icon added to menu
+    - Chart area: color palette shifted
+
+Page: /settings
+  Similarity: 100.0%  [PASS]
+  Diff pixels: 0 of 2,073,600
+
+Summary: 2 passed, 1 failed
+Diff images saved to: .cbrowser/diffs/staging-vs-production/
+```
+
+## Step 3: Cross-Browser Testing
+
+Verify rendering consistency across browser engines.
+
+```bash
+npx cbrowser cross-browser "https://app.example.com"
+```
+
+```
+Cross-Browser Report: https://app.example.com
+Browsers: Chromium 122, Firefox 123, WebKit 17.4
+
+  Chromium vs Firefox:  99.1% similar  [PASS]
+  Chromium vs WebKit:   97.3% similar  [WARN - minor differences]
+    - Font rendering: anti-aliasing differs in body text
+    - Box shadow: 1px offset on card components
+  Firefox vs WebKit:    97.8% similar  [WARN]
+
+All browsers functionally equivalent. Minor rendering differences noted.
+```
+
+## Step 4: Responsive Viewport Testing
+
+Check layouts across common device widths.
+
+```bash
+npx cbrowser responsive "https://app.example.com"
+```
+
+```
+Responsive Report: https://app.example.com
+Viewports: 375px (mobile), 768px (tablet), 1024px (laptop), 1440px (desktop)
+
+  375px  (mobile):   Layout OK, no horizontal overflow
+  768px  (tablet):   Layout OK, sidebar collapses correctly
+  1024px (laptop):   Layout OK, all columns visible
+  1440px (desktop):  Layout OK, max-width container centered
+
+  Issues found:
+    - 375px: "Export" button text truncated to "Exp..."
+    - 768px: Table rows require horizontal scroll (expected)
+
+Responsive score: 9.2/10
+```
+
+## CI Integration
+
+Add to your pipeline (GitHub Actions example):
+
+```yaml
+- name: Visual Regression
+  run: |
+    npx cbrowser visual-baseline "$PROD_URL" --name production
+    npx cbrowser visual-regression "$STAGING_URL" --baseline production --ci
+    npx cbrowser cross-browser "$STAGING_URL" --ci
+    npx cbrowser responsive "$STAGING_URL" --ci
+```
+
+## Next Steps
+
+- Set custom thresholds: `--threshold 95` to allow more tolerance.
+- Exclude dynamic regions: `--ignore-regions ".timestamp,.ad-banner"`.
+- Generate HTML reports: add `--html` to produce a shareable diff viewer.
+- Schedule nightly baseline updates after each production deploy.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cbrowser",
-  "version": "7.4.19",
+  "version": "7.9.0",
   "description": "AI-powered browser automation with constitutional safety, AI visual regression, persona testing, and natural language test suites. Modular architecture for visual, testing, analysis, and performance modules.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",