@capillarytech/cap-ui-dev-tools 1.0.0 → 1.3.0

package/CAPVISION_USAGE.md

@@ -0,0 +1,488 @@
+# CapVision Session Recording - Usage Guide
+
+Part of `@capillarytech/cap-ui-dev-tools` v1.1.0+
+
+## 📖 Overview
+
+The CapVision module provides automatic session recording for WebdriverIO tests. Record user interactions, console logs, and DOM changes during test execution, then replay them in your HTML reports.
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+npm install --save-dev @capillarytech/cap-ui-dev-tools
+```
+
+### Basic Usage (WebdriverIO)
+
+```javascript
+// wdio.conf.js
+const { createWDIOCapVisionHooks } = require('@capillarytech/cap-ui-dev-tools/capvision');
+
+const capVisionHooks = createWDIOCapVisionHooks({
+  recordingsOutputDir: './reports/recordings',
+  enabledClusters: ['staging', 'production']
+});
+
+exports.config = {
+  // ... your existing WebdriverIO config
+  
+  onPrepare: function(config, capabilities) {
+    capVisionHooks.onPrepare();
+  },
+  
+  beforeTest: async function(test, context) {
+    await capVisionHooks.beforeTest(test, context, browser);
+  },
+  
+  afterTest: async function(test, context, result) {
+    await capVisionHooks.afterTest(test, context, result);
+  },
+  
+  onComplete: async function(exitCode, config, capabilities, results) {
+    await capVisionHooks.onComplete();
+  }
+};
+```
+
+That's it! Your tests will now be automatically recorded.
+
+## 📦 Import Options
+
+### Option 1: From CapVision Sub-Module (Recommended)
+
+```javascript
+const { createWDIOCapVisionHooks } = require('@capillarytech/cap-ui-dev-tools/capvision');
+```
+
+### Option 2: From Main Package
+
+```javascript
+const { createWDIOCapVisionHooks } = require('@capillarytech/cap-ui-dev-tools');
+```
+
+### Option 3: Access Full CapVision Module
+
+```javascript
+const capVision = require('@capillarytech/cap-ui-dev-tools').capVisionRecorder;
+
+const {
+  CapVisionRecorder,
+  ReportEnhancer,
+  WebdriverIOCapVisionRecorder,
+  createWDIOCapVisionHooks
+} = capVision;
+```
+
+### Option 4: TypeScript/ESM
+
+```typescript
+import { createWDIOCapVisionHooks } from '@capillarytech/cap-ui-dev-tools/capvision';
+```
+
+## ⚙️ Configuration
+
+### Full Configuration Example
+
+```javascript
+const capVisionHooks = createWDIOCapVisionHooks({
+  // === Filtering Options ===
+  enabledClusters: ['crm-staging-new', 'crm-nightly-new'],
+  enabledModules: ['creatives', 'loyalty'],
+  enabledTestTypes: ['smoke', 'sanity', 'regression'],
+  
+  // === Storage ===
+  recordingsOutputDir: './reports/recordings',
+  useTempFile: true,  // Recommended for large tests
+  
+  // === Recording Options ===
+  saveIntervalMs: 60000,          // Auto-save every 60 seconds
+  checkoutIntervalMs: 30000,      // Snapshot every 30 seconds
+  recordCanvas: false,            // Don't record canvas (saves space)
+  maskAllInputs: true,            // Mask sensitive inputs
+  collectFonts: true,             // Capture custom fonts
+  recordCrossOriginIframes: false,
+  
+  // === Console Recording ===
+  recordConsole: true,
+  consoleRecordOptions: {
+    level: ['log', 'info', 'warn', 'error'],
+    lengthThreshold: 10000
+  }
+}, {
+  // === Report Enhancer Configuration ===
+  reportsDir: './reports/html-reports',
+  playerWidth: 800,
+  playerHeight: 460,
+  autoPlay: false
+});
+```
+
+### Environment-Based Configuration
+
+```javascript
+const isCI = process.env.CI === 'true';
+const cluster = process.env.CLUSTER || 'staging';
+
+const capVisionHooks = createWDIOCapVisionHooks({
+  enabledClusters: [cluster],
+  enabledTestTypes: isCI ? ['smoke'] : ['smoke', 'sanity'],
+  saveIntervalMs: isCI ? 120000 : 60000,
+  recordingsOutputDir: './reports/recordings'
+});
+```
+
+## 🎯 Usage Patterns
+
+### Pattern 1: Automatic Recording (Recommended)
+
+All tests recorded automatically:
+
+```javascript
+// wdio.conf.js
+const { createWDIOCapVisionHooks } = require('@capillarytech/cap-ui-dev-tools/capvision');
+const hooks = createWDIOCapVisionHooks({ /* config */ });
+
+exports.config = {
+  onPrepare: hooks.onPrepare,
+  beforeTest: hooks.beforeTest,
+  afterTest: hooks.afterTest,
+  onComplete: hooks.onComplete
+};
+```
+
+### Pattern 2: Manual Control
+
+Control when recording starts/stops:
+
+```javascript
+const { WebdriverIOCapVisionRecorder } = require('@capillarytech/cap-ui-dev-tools/capvision');
+
+describe('Test Suite', function() {
+  let recorder;
+  
+  before(function() {
+    recorder = new WebdriverIOCapVisionRecorder({
+      recordingsOutputDir: './recordings'
+    });
+    recorder.init(browser);
+  });
+  
+  it('Critical test', async function() {
+    // Start recording manually
+    await recorder.startRecording();
+    
+    // Perform test actions
+    await criticalPage.doSomething();
+    
+    // Stop and save
+    await recorder.stopRecordingAndSave('critical_test');
+  });
+});
+```
+
+### Pattern 3: Record Only Failures
+
+Save recordings only when tests fail:
+
+```javascript
+const { WebdriverIOCapVisionRecorder } = require('@capillarytech/cap-ui-dev-tools/capvision');
+const recorder = new WebdriverIOCapVisionRecorder();
+
+exports.config = {
+  beforeTest: async function(test, context) {
+    recorder.init(browser);
+    await recorder.startRecording();
+  },
+  
+  afterTest: async function(test, context, { passed }) {
+    if (!passed) {
+      // Only save if test failed
+      await recorder.stopRecordingAndSave(`FAILED_${test.title}`);
+    }
+  }
+};
+```
+
+### Pattern 4: With Page Refresh
+
+Handle page refreshes correctly:
+
+```javascript
+it('Test with navigation', async function() {
+  await homePage.open();
+  
+  // Navigate to another page
+  await browser.url('/other-page');
+  
+  // Re-activate recording after navigation
+  await recorder.ensureCapVisionIsActive();
+  
+  await otherPage.doSomething();
+});
+```
+
+## 📊 Viewing Recordings
+
+### In HTML Reports (Automatic)
+
+If you have HTML reports, recordings are automatically embedded with a player:
+
+```bash
+npm test
+# Open reports/html-reports/index.html
+# Recordings will appear inline with test results
+```
+
+### Standalone Viewer
+
+Create a simple HTML file to view recordings:
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <link rel="stylesheet" href="node_modules/@capillarytech/cap-ui-dev-tools/src/capvision-recorder/assets/capvision-player.css">
+</head>
+<body>
+  <div id="player"></div>
+  <script src="node_modules/@capillarytech/cap-ui-dev-tools/src/capvision-recorder/assets/capvision-player.min.js"></script>
+  <script>
+    fetch('./reports/recordings/your-test-1.json')
+      .then(res => res.json())
+      .then(data => {
+        new rrwebPlayer({ // Note: rrwebPlayer is the underlying library class name
+          target: document.getElementById('player'),
+          props: {
+            events: data.events,
+            width: 800,
+            height: 600
+          }
+        });
+      });
+  </script>
+</body>
+</html>
+```
+
+## 🔧 Advanced Usage
+
+### Custom Browser Executor
+
+For non-WebdriverIO frameworks (Playwright, Puppeteer):
+
+```javascript
+const { CapVisionRecorder } = require('@capillarytech/cap-ui-dev-tools/capvision');
+
+// Create custom executor for Playwright
+class PlaywrightExecutor {
+  constructor(page) {
+    this.page = page;
+  }
+  
+  async execute(script, ...args) {
+    return this.page.evaluate(script, ...args);
+  }
+  
+  async pause(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+
+// Use with recorder
+const recorder = new CapVisionRecorder({
+  recordingsOutputDir: './recordings'
+});
+
+recorder.setBrowserExecutor(new PlaywrightExecutor(page));
+await recorder.startRecording();
+// ... test execution
+await recorder.stopRecordingAndSave('test_name');
+```
+
+### Report Enhancement Only
+
+If you have existing recordings and just want to enhance reports:
+
+```javascript
+const { ReportEnhancer } = require('@capillarytech/cap-ui-dev-tools/capvision');
+
+const enhancer = new ReportEnhancer({
+  recordingsDir: './reports/recordings',
+  reportsDir: './reports/html-reports'
+});
+
+await enhancer.enhanceAllReports();
+```
+
+## 🐛 Troubleshooting
+
+### No Recordings Created
+
+**Check:**
+1. Is recording enabled for your cluster/module/test type?
+2. Is the output directory writable?
+3. Check console logs for errors
+
+```javascript
+// Add debug logging
+const recorder = hooks.getRecorder();
+console.log('Recording enabled?', recorder.isCapVisionEnabled());
+console.log('Cluster:', process.env.CLUSTER);
+console.log('Module:', process.env.MODULE);
+```
+
+### Recording Stops After Page Refresh
+
+**Solution:** Always call `ensureCapVisionIsActive()` after page navigation:
+
+```javascript
+await browser.refresh();
+await recorder.ensureCapVisionIsActive(); // Essential!
+```
+
+### Large File Sizes
+
+**Solutions:**
+1. Reduce checkout interval: `checkoutIntervalMs: 15000`
+2. Don't record canvas: `recordCanvas: false`
+3. Record only critical tests: Use selective filtering
+
+### Recordings Not in HTML Report
+
+**Check:**
+1. Are recordings in the correct directory?
+2. Is `onComplete` hook being called?
+3. Do recording filenames match test names?
+
+## 📚 API Reference
+
+### createWDIOCapVisionHooks(recorderConfig, enhancerConfig)
+
+Creates WebdriverIO hooks for automatic recording.
+
+**Returns:** Object with `onPrepare`, `beforeTest`, `afterTest`, `onComplete`, `getRecorder` methods
+
+### CapVisionRecorder
+
+Core recorder class (framework-agnostic).
+
+**Methods:**
+- `setBrowserExecutor(executor)` - Set custom browser executor
+- `startRecording()` - Start recording session
+- `stopRecordingAndSave(testName, testPassed)` - Stop and save recording (only saves if testPassed=false)
+- `ensureCapVisionIsActive()` - Re-initialize after page refresh
+- `isCapVisionEnabled()` - Check if recording is enabled
+- `clearRecordingsFolder()` - Clear old recordings
+
+### WebdriverIOCapVisionRecorder
+
+WebdriverIO-specific wrapper.
+
+**Methods:**
+- `init(browser)` - Initialize with browser instance
+- `getRecorder()` - Get underlying recorder
+- `getEnhancer()` - Get report enhancer
+- All methods from CapVisionRecorder
+
+### ReportEnhancer
+
+Enhances HTML reports with CapVision player.
+
+**Methods:**
+- `enhanceReport(reportPath)` - Enhance single report
+- `enhanceAllReports()` - Enhance all reports in directory
+
+## 📦 Package Usage Summary
+
+```javascript
+// All available imports from @capillarytech/cap-ui-dev-tools
+
+// 1. Webpack Plugin (existing)
+const LibraryWatcherPlugin = require('@capillarytech/cap-ui-dev-tools');
+// or
+const LibraryWatcherPlugin = require('@capillarytech/cap-ui-dev-tools/webpack');
+
+// 2. CapVision Recorder (new)
+const { createWDIOCapVisionHooks } = require('@capillarytech/cap-ui-dev-tools/capvision');
+// or
+const { createWDIOCapVisionHooks } = require('@capillarytech/cap-ui-dev-tools');
+
+// 3. Full CapVision Module
+const capVision = require('@capillarytech/cap-ui-dev-tools').capVisionRecorder;
+```
+
+## 🎓 Examples
+
+### Example 1: Basic Capillary Project
+
+```javascript
+// wdio.conf.js
+const { createWDIOCapVisionHooks } = require('@capillarytech/cap-ui-dev-tools/capvision');
+
+const capVisionHooks = createWDIOCapVisionHooks({
+  enabledClusters: ['crm-staging-new'],
+  enabledModules: ['creatives'],
+  recordingsOutputDir: './reports/recordings'
+});
+
+exports.config = {
+  onPrepare: capVisionHooks.onPrepare,
+  beforeTest: (test, context) => capVisionHooks.beforeTest(test, context, browser),
+  afterTest: capVisionHooks.afterTest,
+  onComplete: capVisionHooks.onComplete
+};
+```
+
+### Example 2: CI/CD Integration
+
+```javascript
+const isCI = process.env.CI === 'true';
+
+const capVisionHooks = createWDIOCapVisionHooks({
+  enabledClusters: process.env.CLUSTER ? [process.env.CLUSTER] : [],
+  enabledTestTypes: isCI ? ['smoke'] : ['smoke', 'sanity', 'regression'],
+  recordingsOutputDir: './reports/recordings',
+  saveIntervalMs: isCI ? 120000 : 60000
+});
+```
+
+### Example 3: With Page Objects
+
+```javascript
+// pages/BasePage.js
+class BasePage {
+  constructor(recorder) {
+    this.recorder = recorder;
+  }
+  
+  async navigateTo(url) {
+    await browser.url(url);
+    await this.recorder.ensureCapVisionIsActive();
+  }
+  
+  async refresh() {
+    await browser.refresh();
+    await this.recorder.ensureCapVisionIsActive();
+  }
+}
+
+module.exports = BasePage;
+```
+
+## 📄 License
+
+ISC License - Part of @capillarytech/cap-ui-dev-tools
+
+## 🆘 Support
+
+- **Issues**: [GitHub Issues](https://github.com/cap-ui-dev-tools/cap-ui-dev-tools/issues)
+- **Internal**: Contact Cap Automation Team
+
+---
+
+**Version**: 1.1.0+  
+**Module**: `@capillarytech/cap-ui-dev-tools/capvision`  
+**Compatibility**: WebdriverIO 7.x, 8.x+
+