vibecheck-ai 2.0.2 → 5.0.0

package/bin/runners/lib/replay/index.js

@@ -0,0 +1,263 @@
+/**
+ * Replay Module
+ * 
+ * Provides a unified API for recording and replaying user interactions
+ * with the ability to verify behavior and detect regressions.
+ */
+
+const path = require('path');
+const fs = require('fs').promises;
+const debug = require('debug')('vibecheck:replay');
+
+// Core components
+const CapsuleManager = require('./capsule-manager');
+const ReplayRecorder = require('./recorder');
+const ReplayPlayer = require('./player');
+
+/**
+ * Main Replay API
+ */
+class ReplayEngine {
+  constructor(options = {}) {
+    this.options = {
+      basePath: process.cwd(),
+      ...options
+    };
+    
+    this.manager = new CapsuleManager(this.options.basePath);
+    this.recorder = null;
+    this.player = null;
+  }
+
+  /**
+   * Initialize the replay system
+   */
+  async init() {
+    await this.manager.init();
+    debug('Replay engine initialized');
+    return this;
+  }
+
+  /**
+   * Start a new recording session
+   */
+  startRecording(options = {}) {
+    if (this.recorder) {
+      throw new Error('Recording already in progress');
+    }
+    
+    this.recorder = new ReplayRecorder({
+      ...options,
+      basePath: this.options.basePath
+    });
+    
+    this.recorder.start();
+    debug('Started new recording session');
+    
+    return this.recorder;
+  }
+
+  /**
+   * Stop the current recording and save as a capsule
+   */
+  async stopRecording(saveOptions = {}) {
+    if (!this.recorder) {
+      throw new Error('No active recording to stop');
+    }
+    
+    const result = this.recorder.stop();
+    const { id, path: capsulePath } = await this.recorder.save(this.options.basePath);
+    
+    debug(`Recording saved as capsule: ${id} (${capsulePath})`);
+    
+    this.recorder = null;
+    
+    return {
+      id,
+      path: capsulePath,
+      metadata: result.metadata
+    };
+  }
+
+  /**
+   * List available replay capsules
+   */
+  async listCapsules() {
+    return this.manager.listCapsules();
+  }
+
+  /**
+   * Get a replay capsule by ID or path
+   */
+  async getCapsule(idOrPath) {
+    return this.manager.loadCapsule(idOrPath);
+  }
+
+  /**
+   * Delete a replay capsule
+   */
+  async deleteCapsule(idOrPath) {
+    return this.manager.deleteCapsule(idOrPath);
+  }
+
+  /**
+   * Export a capsule to a portable format
+   */
+  async exportCapsule(idOrPath, outputPath) {
+    return this.manager.exportCapsule(idOrPath, outputPath);
+  }
+
+  /**
+   * Import a capsule from a file
+   */
+  async importCapsule(filePath) {
+    return this.manager.importCapsule(filePath);
+  }
+
+  /**
+   * Create a new replay player for a capsule
+   */
+  createPlayer(options = {}) {
+    if (this.player) {
+      throw new Error('A player is already active');
+    }
+    
+    this.player = new ReplayPlayer({
+      ...this.options,
+      ...options
+    });
+    
+    return this.player;
+  }
+
+  /**
+   * Play a replay capsule
+   */
+  async playCapsule(capsule, options = {}) {
+    const player = this.createPlayer(options);
+    await player.loadCapsule(capsule);
+    
+    if (options.browser) {
+      await player.setupPlaywright(options.browser);
+    }
+    
+    return player.play();
+  }
+
+  /**
+   * Create a Playwright recorder
+   */
+  createPlaywrightRecorder(page, options = {}) {
+    return ReplayRecorder.fromPlaywright(page, {
+      ...this.options,
+      ...options
+    });
+  }
+
+  /**
+   * Clean up resources
+   */
+  async cleanup() {
+    if (this.player) {
+      await this.player.close().catch(console.error);
+      this.player = null;
+    }
+    
+    if (this.recorder) {
+      this.recorder.stop();
+      this.recorder = null;
+    }
+  }
+}
+
+// Export everything
+module.exports = {
+  // Main API
+  ReplayEngine,
+  
+  // Core components
+  CapsuleManager,
+  ReplayRecorder,
+  ReplayPlayer,
+  
+  // Factory function for quick setup
+  createReplayEngine: async (options = {}) => {
+    const engine = new ReplayEngine(options);
+    await engine.init();
+    return engine;
+  },
+  
+  // Utility functions
+  utils: {
+    /**
+     * Generate a human-readable report from replay results
+     */
+    generateReport: (results) => {
+      const { metadata, stats } = results;
+      const { name, description, duration, steps } = metadata;
+      const { passed, failed, skipped } = stats;
+      
+      return {
+        title: `Replay Report: ${name}`,
+        summary: {
+          description,
+          duration: `${(duration / 1000).toFixed(2)}s`,
+          totalSteps: steps,
+          passed,
+          failed,
+          skipped,
+          success: failed === 0
+        },
+        timestamp: new Date().toISOString(),
+        details: results.steps ? results.steps.map(step => ({
+          id: step.id,
+          type: step.type,
+          status: step.error ? 'failed' : 'passed',
+          duration: step.duration ? `${step.duration.toFixed(2)}ms` : 'N/A',
+          error: step.error ? step.error.message : null
+        })) : []
+      };
+    },
+    
+    /**
+     * Compare two replay results to detect regressions
+     */
+    compareResults: (baseline, current) => {
+      const regressions = [];
+      
+      // Check step counts
+      if (baseline.stats.totalSteps !== current.stats.totalSteps) {
+        regressions.push({
+          type: 'step_count_mismatch',
+          message: `Different number of steps: ${baseline.stats.totalSteps} vs ${current.stats.totalSteps}`
+        });
+      }
+      
+      // Check for new failures
+      if (current.stats.failed > baseline.stats.failed) {
+        regressions.push({
+          type: 'new_failures',
+          message: `New failures: ${current.stats.failed - baseline.stats.failed} more than baseline`
+        });
+      }
+      
+      // Check for performance regressions (if timing data is available)
+      if (baseline.metadata.duration && current.metadata.duration) {
+        const threshold = baseline.metadata.duration * 1.5; // 50% slower
+        if (current.metadata.duration > threshold) {
+          regressions.push({
+            type: 'performance_regression',
+            message: `Performance regression: ${(current.metadata.duration / 1000).toFixed(2)}s vs baseline ${(baseline.metadata.duration / 1000).toFixed(2)}s`
+          });
+        }
+      }
+      
+      return {
+        hasRegressions: regressions.length > 0,
+        regressions,
+        baseline: baseline.stats,
+        current: current.stats
+      };
+    }
+  }
+};

package/bin/runners/lib/replay/player.js

@@ -0,0 +1,348 @@
+/**
+ * Replay Player
+ * Replays recorded user interactions and verifies behavior
+ */
+
+const { EventEmitter } = require('events');
+const { performance } = require('perf_hooks');
+const fs = require('fs').promises;
+const path = require('path');
+const debug = require('debug')('vibecheck:replay:player');
+
+class ReplayPlayer extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    this.options = {
+      speed: 1.0,
+      headless: true,
+      viewport: { width: 1280, height: 800 },
+      waitForNetworkIdle: true,
+      networkIdleTimeout: 500,
+      waitForSelectorTimeout: 30000,
+      ...options
+    };
+    
+    this.state = 'idle';
+    this.currentStep = 0;
+    this.stats = {
+      totalSteps: 0,
+      passed: 0,
+      failed: 0,
+      skipped: 0,
+      startTime: null,
+      endTime: null,
+      duration: 0
+    };
+    
+    this.page = null;
+    this.capsule = null;
+  }
+
+  async loadCapsule(capsulePath) {
+    this.state = 'loading';
+    
+    try {
+      // Load from file if it's a path
+      if (typeof capsulePath === 'string') {
+        const data = await fs.readFile(capsulePath, 'utf8');
+        this.capsule = JSON.parse(data);
+      } 
+      // Or use the provided capsule object
+      else if (capsulePath.metadata && Array.isArray(capsulePath.steps)) {
+        this.capsule = capsulePath;
+      } 
+      // Or load from a directory containing metadata.json and steps.json
+      else if (typeof capsulePath === 'object' && capsulePath.path) {
+        const [metadata, steps] = await Promise.all([
+          fs.readFile(path.join(capsulePath.path, 'metadata.json'), 'utf8')
+            .then(JSON.parse),
+          fs.readFile(path.join(capsulePath.path, 'steps.json'), 'utf8')
+            .then(JSON.parse)
+        ]);
+        this.capsule = { metadata, steps };
+      } else {
+        throw new Error('Invalid capsule format');
+      }
+      
+      this.stats.totalSteps = this.capsule.steps.length;
+      this.state = 'loaded';
+      this.emit('loaded', { steps: this.stats.totalSteps });
+      
+      return this.capsule;
+    } catch (error) {
+      this.state = 'error';
+      this.emit('error', { error, phase: 'load' });
+      throw error;
+    }
+  }
+
+  async setupPlaywright(browser) {
+    if (this.page) return this.page;
+    
+    try {
+      const context = await browser.newContext({
+        viewport: this.capsule.metadata.viewport || this.options.viewport,
+        userAgent: this.capsule.metadata.userAgent,
+        ignoreHTTPSErrors: true
+      });
+      
+      this.page = await context.newPage();
+      
+      // Set up request/response tracking
+      this._setupNetworkMonitoring();
+      
+      return this.page;
+    } catch (error) {
+      this.state = 'error';
+      this.emit('error', { error, phase: 'setup' });
+      throw error;
+    }
+  }
+
+  _setupNetworkMonitoring() {
+    if (!this.page) return;
+    
+    this.pendingRequests = new Set();
+    
+    this.page.on('request', request => {
+      if (this.options.waitForNetworkIdle) {
+        this.pendingRequests.add(request);
+      }
+    });
+    
+    this.page.on('requestfinished', request => {
+      this.pendingRequests.delete(request);
+    });
+    
+    this.page.on('requestfailed', request => {
+      this.pendingRequests.delete(request);
+    });
+  }
+
+  async waitForNetworkIdle() {
+    if (!this.options.waitForNetworkIdle || !this.page) return;
+    
+    const start = performance.now();
+    let hasPending = false;
+    
+    do {
+      hasPending = this.pendingRequests.size > 0;
+      
+      if (hasPending) {
+        await new Promise(r => setTimeout(r, 50));
+      }
+      
+      if (performance.now() - start > this.options.networkIdleTimeout) {
+        debug(`Network idle timeout after ${this.options.networkIdleTimeout}ms`);
+        break;
+      }
+    } while (hasPending);
+  }
+
+  async play() {
+    if (this.state !== 'loaded') {
+      throw new Error('No capsule loaded. Call loadCapsule() first.');
+    }
+    
+    this.state = 'playing';
+    this.currentStep = 0;
+    this.stats.startTime = performance.now();
+    this.stats.passed = 0;
+    this.stats.failed = 0;
+    this.stats.skipped = 0;
+    
+    this.emit('start', { steps: this.stats.totalSteps });
+    
+    try {
+      for (const step of this.capsule.steps) {
+        this.currentStep++;
+        this.emit('stepStart', { step: this.currentStep, total: this.stats.totalSteps, type: step.type });
+        
+        try {
+          await this._executeStep(step);
+          this.stats.passed++;
+          this.emit('stepPass', { 
+            step: this.currentStep, 
+            type: step.type,
+            duration: performance.now() - (step.timestamp || 0)
+          });
+        } catch (error) {
+          this.stats.failed++;
+          this.emit('stepFail', { 
+            step: this.currentStep, 
+            type: step.type,
+            error,
+            duration: performance.now() - (step.timestamp || 0)
+          });
+          
+          if (this.options.stopOnFailure) {
+            throw error;
+          }
+        }
+        
+        // Apply speed factor to timing
+        if (this.currentStep < this.capsule.steps.length - 1) {
+          const nextStep = this.capsule.steps[this.currentStep];
+          const currentTime = step.timestamp || 0;
+          const nextTime = nextStep.timestamp || 0;
+          const delay = (nextTime - currentTime) / this.options.speed;
+          
+          if (delay > 0) {
+            await new Promise(resolve => setTimeout(resolve, delay));
+          }
+        }
+      }
+      
+      this.stats.endTime = performance.now();
+      this.stats.duration = this.stats.endTime - this.stats.startTime;
+      this.state = 'completed';
+      
+      const result = {
+        ...this.stats,
+        success: this.stats.failed === 0,
+        capsule: this.capsule.metadata
+      };
+      
+      this.emit('complete', result);
+      return result;
+    } catch (error) {
+      this.state = 'error';
+      this.emit('error', { 
+        error, 
+        step: this.currentStep,
+        phase: 'playback'
+      });
+      throw error;
+    }
+  }
+
+  async _executeStep(step) {
+    if (!this.page) {
+      throw new Error('No page available. Call setupPlaywright() first.');
+    }
+    
+    debug(`Executing step: ${step.type}`, { step });
+    
+    switch (step.type) {
+      case 'navigation':
+        await this.page.goto(step.url, { 
+          waitUntil: 'networkidle',
+          timeout: this.options.waitForSelectorTimeout
+        });
+        break;
+        
+      case 'click':
+        if (step.selector) {
+          await this.page.waitForSelector(step.selector, {
+            state: 'visible',
+            timeout: this.options.waitForSelectorTimeout
+          });
+          await this.page.click(step.selector, {
+            button: step.button,
+            clickCount: step.clickCount || 1,
+            delay: 50
+          });
+        } else if (step.x !== undefined && step.y !== undefined) {
+          await this.page.mouse.click(step.x, step.y, {
+            button: step.button,
+            clickCount: step.clickCount || 1,
+            delay: 50
+          });
+        } else {
+          throw new Error('Click step requires either selector or x,y coordinates');
+        }
+        break;
+        
+      case 'input':
+        if (!step.selector) {
+          throw new Error('Input step requires a selector');
+        }
+        
+        await this.page.waitForSelector(step.selector, {
+          state: 'visible',
+          timeout: this.options.waitForSelectorTimeout
+        });
+        
+        // Clear existing value first
+        await this.page.$eval(step.selector, el => {
+          if (el) el.value = '';
+        });
+        
+        // Type the new value
+        await this.page.type(step.selector, step.value || '', {
+          delay: 20 // Simulate realistic typing
+        });
+        break;
+        
+      case 'keypress':
+        if (step.key) {
+          await this.page.keyboard.press(step.key, {
+            delay: 20
+          });
+        }
+        break;
+        
+      case 'network_request':
+        // Just verify the request was made, no action needed
+        break;
+        
+      case 'network_response':
+        // Verify response status if expected
+        if (step.expectedStatus && step.status !== step.expectedStatus) {
+          throw new Error(`Expected status ${step.expectedStatus} but got ${step.status}`);
+        }
+        break;
+        
+      case 'custom_assert':
+        // Execute custom assertion
+        if (typeof step.assert === 'function') {
+          const result = await step.assert(this.page);
+          if (result === false) {
+            throw new Error('Custom assertion failed');
+          } else if (result && result.message) {
+            throw new Error(`Assertion failed: ${result.message}`);
+          }
+        }
+        break;
+        
+      default:
+        debug(`Skipping unsupported step type: ${step.type}`);
+        this.stats.skipped++;
+    }
+    
+    // Wait for network to be idle after each step
+    await this.waitForNetworkIdle();
+  }
+  
+  async takeScreenshot(options = {}) {
+    if (!this.page) return null;
+    
+    const defaultPath = path.join(
+      process.cwd(),
+      'screenshots',
+      `screenshot-${Date.now()}.png`
+    );
+    
+    const screenshotPath = options.path || defaultPath;
+    await fs.mkdir(path.dirname(screenshotPath), { recursive: true });
+    
+    await this.page.screenshot({
+      path: screenshotPath,
+      fullPage: options.fullPage !== false,
+      ...options
+    });
+    
+    return screenshotPath;
+  }
+  
+  async close() {
+    if (this.page) {
+      await this.page.close().catch(console.error);
+      this.page = null;
+    }
+    
+    this.state = 'idle';
+  }
+}
+
+module.exports = ReplayPlayer;