@capillarytech/cap-ui-dev-tools 2.0.0 → 2.1.0

package/CAPVISION_USAGE.md

@@ -316,6 +316,72 @@ const enhancer = new ReportEnhancer({
 await enhancer.enhanceAllReports();
 ```
 
+## 🎬 Visual Regression Mode (v1.1.0+)
+
+### Overview
+
+By default, CapVision only saves recordings for **failed tests** to conserve disk space. Visual Regression Mode changes this behavior to save recordings for **all tests** (pass or fail), enabling on-demand visual verification of the application.
+
+### Configuration
+
+Enable visual regression by setting `saveAllRecordings: true`:
+
+```javascript
+const capVisionHooks = createWDIOCapVisionHooks({
+  ENABLE_FEATURE: true,
+  saveAllRecordings: true,   // 👈 Save recordings for ALL tests
+  enabledClusters: ['crm-nightly-new'],
+  enabledModules: ['creatives'],
+  enabledTestTypes: ['sanity', 'regression']
+});
+```
+
+### Environment Variable Integration
+
+For on-demand usage, drive `saveAllRecordings` from an environment variable:
+
+```javascript
+const isVisualRegression = process.env.VISUAL_REGRESSION === 'true';
+
+const capVisionHooks = createWDIOCapVisionHooks({
+  ENABLE_FEATURE: process.env.ENABLE_RECORDING === 'true' || isVisualRegression,
+  saveAllRecordings: isVisualRegression,
+  enabledTestTypes: ['sanity', 'regression'],
+  // ... other config
+});
+```
+
+Then run with:
+
+```bash
+VISUAL_REGRESSION=true ENABLE_RECORDING=true npx wdio test/wdio.conf.ts --suite visual-regression
+```
+
+### Behavior Comparison
+
+| Scenario | `saveAllRecordings` | Passed Tests | Failed Tests |
+|---|---|---|---|
+| Default mode | `false` | ❌ Not saved | ✅ Saved |
+| Visual regression mode | `true` | ✅ Saved | ✅ Saved |
+
+### Console Logging
+
+When visual regression mode is active, you'll see:
+
+```
+🟡 CapVision visual regression mode active — all recordings will be saved regardless of test result
+🟡 Saving CapVision recording (visual regression mode): Testcase_my_test_flow
+```
+
+### Best Practices
+
+1. **Run on-demand only** — Visual regression creates recordings for every test, which uses more disk space
+2. **Use for regression suites** — Point the `visual-regression` suite to your regression test files
+3. **Review recordings in HTML reports** — Open `reports/html-reports/master-report.html` after the run
+4. **Clean up after review** — Old recordings are auto-cleared on the next `onPrepare` call
+
+---
+
 ## 🐛 Troubleshooting
 
 ### No Recordings Created
@@ -482,7 +548,7 @@ ISC License - Part of @capillarytech/cap-ui-dev-tools
 
 ---
 
-**Version**: 1.1.0+  
-**Module**: `@capillarytech/cap-ui-dev-tools/capvision`  
+**Version**: 2.1.0+
+**Module**: `@capillarytech/cap-ui-dev-tools/capvision`
 **Compatibility**: WebdriverIO 7.x, 8.x+
 

package/README.md

@@ -54,7 +54,14 @@ const path = require('path');
 
 module.exports = {
   mode: 'development',
-  
+    // ... your other webpack config
+
+    // NO need for a separate resolve.alias block for local development!
+    // The plugin handles it for you.
+    resolve: {
+      // ... any other aliases can stay here
+    },
+
   plugins: [
     new webpack.HotModuleReplacementPlugin(),
     
@@ -126,6 +133,7 @@ exports.config = {
 - ✅ **Console Recording** - Captures console logs with UI interactions
 - ✅ **Privacy First** - Auto-masks sensitive inputs
 - ✅ **Framework Agnostic Core** - Works with WebdriverIO, Playwright, Puppeteer
+- ✅ **Visual Regression Mode** _(v1.1.0)_ - Record ALL tests (pass/fail) for visual verification
 
 ### Full Documentation
 
@@ -206,6 +214,18 @@ See [CAPVISION_USAGE.md](./CAPVISION_USAGE.md#troubleshooting) for common issues
 
 ## 📝 Changelog
 
+### v1.1.0 (2026-02-07)
+- ✨ **NEW**: Visual Regression Mode — `saveAllRecordings` config option
+- ✅ Records ALL tests (pass and fail) when `saveAllRecordings: true`
+- ✅ On-demand visual regression suite support for module-level recording
+- ✅ Automatic mode detection via `VISUAL_REGRESSION` environment variable
+- ✅ Enhanced logging for visual regression mode status
+- 📚 Updated documentation with visual regression usage guide
+
+### v2.0.0 (2025-12-20)
+- ✅ Major version bump with package restructuring
+- ✅ Updated dependencies
+
 ### v1.1.0 (2025-11-12)
 - ✨ **NEW**: Added CapVision session recording module
 - ✅ Support for automatic test recording
@@ -272,5 +292,5 @@ ISC License
 
 **Made with ❤️ by Capillary Technologies**
 
-**Version**: 1.1.0  
-**Includes**: Webpack Hot-Reload Plugin + CapVision Session Recording
+**Version**: 2.1.0
+**Includes**: Webpack Hot-Reload Plugin + CapVision Session Recording + Visual Regression Mode

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capillarytech/cap-ui-dev-tools",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Development tools for Capillary UI projects including webpack hot-reload plugin and CapVision session recording",
   "main": "src/index.js",
   "exports": {

package/src/capvision-recorder/core/CapVisionRecorder.js

@@ -22,6 +22,7 @@ const os = require('os');
  * @property {boolean} [collectFonts] - Collect custom fonts
  * @property {boolean} [recordCrossOriginIframes] - Record cross-origin iframes
  * @property {boolean} [useTempFile] - Use temporary file storage instead of sessionStorage
+ * @property {boolean} [saveAllRecordings] - When true, save recordings for ALL tests (pass or fail). Used for visual regression mode (default: false)
  * @property {boolean} [recordConsole] - Enable console recording
  * @property {Object} [consoleRecordOptions] - Console recording options
  * @property {string[]} [consoleRecordOptions.level] - Console levels to record
@@ -40,12 +41,10 @@ const DEFAULT_CONFIG = {
   enabledClusters: [],
   enabledModules: [],
   enabledTestTypes: ['smoke', 'sanity', 'regression'],
-  
   capVisionScriptPath: path.join(__dirname, '../assets/capvision.min.js'),
   consoleRecordPluginPath: path.join(__dirname, '../assets/capvision-plugins/console-record.min.js'),
   consoleReplayPluginPath: path.join(__dirname, '../assets/capvision-plugins/console-replay.min.js'),
   recordingsOutputDir: path.join(process.cwd(), 'reports', 'recordings'),
-  
   sessionStorageKey: 'capvision_events',
   saveIntervalMs: 60000,
   checkoutIntervalMs: 30000,
@@ -56,7 +55,7 @@ const DEFAULT_CONFIG = {
   collectFonts: true,
   recordCrossOriginIframes: false,
   useTempFile: true,
-  
+  saveAllRecordings: false,
   recordConsole: true,
   consoleRecordOptions: {
     level: ['log', 'info', 'warn', 'error'],
@@ -172,7 +171,6 @@ class CapVisionRecorder {
     }
 
     const cluster = currentCluster || process.env.cluster;
-    
     if (!cluster) {
       return false;
     }
@@ -192,13 +190,11 @@ class CapVisionRecorder {
     }
 
     const module = currentModule || process.env.module;
-    
     if (!module) {
       return false;
     }
 
     const isEnabled = this.config.enabledModules.includes(module);
-    
     return isEnabled;
   }
 
@@ -212,13 +208,11 @@ class CapVisionRecorder {
     }
 
     const currentTestType = this.getCurrentTestType();
-    
     if (!currentTestType) {
       return false;
     }
 
     const isEnabled = this.config.enabledTestTypes.includes(currentTestType);
-    
     return isEnabled;
   }
 
@@ -234,21 +228,23 @@ class CapVisionRecorder {
       console.log('🟡 CapVision feature disabled (ENABLE_FEATURE=false)');
       return false;
     }
-    
+
     const clusterEnabled = this.isCapVisionEnabledForCluster(cluster);
     const moduleEnabled = this.isCapVisionEnabledForModule(module);
     const testTypeEnabled = this.isCapVisionEnabledForTestType();
-    
+
     const isEnabled = clusterEnabled && moduleEnabled && testTypeEnabled;
-    
+
     if (!isEnabled) {
       const disabledReasons = [];
       if (!clusterEnabled) disabledReasons.push('cluster');
       if (!moduleEnabled) disabledReasons.push('module');
       if (!testTypeEnabled) disabledReasons.push('test type');
       console.log(`🟡 CapVision recording disabled (${disabledReasons.join(', ')} disabled)`);
+    } else if (this.config.saveAllRecordings) {
+      console.log('🟡 CapVision visual regression mode active — all recordings will be saved regardless of test result');
     }
-    
+
     return isEnabled;
   }
 
@@ -292,7 +288,6 @@ class CapVisionRecorder {
       // Find existing recordings for this test
       const existingFiles = fs.readdirSync(recordingsDir);
       const testFilePattern = new RegExp(`^${sanitizedTestName}-(\\d+)\\.json$`);
-      
       let maxNumber = 0;
       existingFiles.forEach((file) => {
         const match = file.match(testFilePattern);
@@ -334,7 +329,6 @@ class CapVisionRecorder {
    */
   createTempFile() {
     const tempDir = path.join(os.tmpdir(), 'capvision-recordings');
-    
     if (!fs.existsSync(tempDir)) {
       fs.mkdirSync(tempDir, { recursive: true });
     }
@@ -440,7 +434,6 @@ class CapVisionRecorder {
       window.capVisionInitialized = false;
       window.capVisionLastCheckTime = Date.now();
       window.capVisionEvents = [];
-      
       // Inject CapVision script
       const injectScript = () => {
         return new Promise((resolve) => {
@@ -567,7 +560,6 @@ class CapVisionRecorder {
           window.rrwebRecorder = window.rrweb.record({
             emit: (event) => {
               window.capVisionEvents.push(event);
-              
               if (!config.useTempFile) {
                 saveEventsToStorage();
               }
@@ -650,7 +642,6 @@ class CapVisionRecorder {
           const events = await this.browserExecutor.execute(() => {
             return window.capVisionEvents || [];
           });
-          
           if (events && events.length > 0) {
             this.saveToTempFile(events);
           }
@@ -666,7 +657,7 @@ class CapVisionRecorder {
    * Stop CapVision recording and save events
    * @async
    * @param {string} [testName='test'] - Name of the test for filename
-   * @param {boolean} [testPassed=true] - Whether the test passed. If true, recording is not saved permanently but temp file is still deleted
+   * @param {boolean} [testPassed=true] - Whether the test passed. If true and saveAllRecordings is false, recording is not saved permanently but temp file is still deleted. When saveAllRecordings is true (visual regression mode), recordings are saved regardless of test result.
    * @returns {Promise<RecordingMetadata>} Recording metadata
    * @throws {Error} If browser executor not set
    */
@@ -695,7 +686,6 @@ class CapVisionRecorder {
           const finalEvents = await this.browserExecutor.execute(() => {
           return window.capVisionEvents || [];
         });
-        
         if (finalEvents && finalEvents.length > 0) {
           this.saveToTempFile(finalEvents);
         }
@@ -738,19 +728,23 @@ class CapVisionRecorder {
       };
     }, this.config);
 
-    // Save to permanent location only if test failed
+    // Save to permanent location based on mode:
+    // - Visual regression mode (saveAllRecordings=true): save ALL recordings regardless of test result
+    // - Normal mode: save only if test failed
+    const shouldSave = this.config.saveAllRecordings || !testPassed;
     let savedFilename = '';
     if (this.config.useTempFile && metadata.totalEvents > 0) {
       try {
         const events = this.readFromTempFile();
-        
+
         if (events && events.length > 0) {
-          if (!testPassed) {
-            // Only save permanently if test failed
+          if (shouldSave) {
+            const saveReason = this.config.saveAllRecordings ? 'visual regression mode' : 'test failed';
+            console.log(`🟡 Saving CapVision recording (${saveReason}): ${testName}`);
             savedFilename = this.saveEventsToFile(events, testName);
           }
         }
-        
+
         // Always delete temp file regardless of test result
         this.deleteTempFile();
       } catch (error) {
@@ -763,7 +757,6 @@ class CapVisionRecorder {
         }
       }
     }
-    
     return {
       timestamp: metadata.timestamp,
       totalEvents: metadata.totalEvents,