@vizzly-testing/cli 0.15.1 → 0.16.1

package/dist/sdk/index.js

@@ -22,7 +22,7 @@ import { VizzlyError } from '../errors/vizzly-error.js';
 /**
  * Create a new Vizzly instance with custom configuration
  *
- * @param {import('../types').VizzlyConfig} [config] - Configuration options
+ * @param {Object} [config] - Configuration options
  * @returns {Promise<VizzlySDK>} Configured Vizzly SDK instance
  *
  * @example
@@ -147,7 +147,7 @@ export function createVizzly(config = {}, options = {}) {
  */
 export class VizzlySDK extends EventEmitter {
   /**
-   * @param {import('../types').VizzlyConfig} config - Configuration
+   * @param {Object} config - Configuration
    * @param {Object} services - Service instances
    */
   constructor(config, services) {
@@ -223,7 +223,7 @@ export class VizzlySDK extends EventEmitter {
    * Capture a screenshot
    * @param {string} name - Screenshot name
    * @param {Buffer|string} imageBuffer - Image data as a Buffer, or a file path to an image
-   * @param {import('../types').ScreenshotOptions} [options] - Options
+   * @param {Object} [options] - Options
    * @returns {Promise<void>}
    * @throws {VizzlyError} When server is not running
    * @throws {VizzlyError} When file path is provided but file doesn't exist
@@ -288,8 +288,8 @@ export class VizzlySDK extends EventEmitter {
 
   /**
    * Upload all captured screenshots
-   * @param {import('../types').UploadOptions} [options] - Upload options
-   * @returns {Promise<import('../types').UploadResult>} Upload result
+   * @param {Object} [options] - Upload options
+   * @returns {Promise<Object>} Upload result
    */
   async upload(options = {}) {
     if (!this.services?.uploader) {
@@ -332,7 +332,7 @@ export class VizzlySDK extends EventEmitter {
    * Run local comparison in TDD mode
    * @param {string} name - Screenshot name
    * @param {Buffer|string} imageBuffer - Current image as a Buffer, or a file path to an image
-   * @returns {Promise<import('../types').ComparisonResult>} Comparison result
+   * @returns {Promise<Object>} Comparison result
    * @throws {VizzlyError} When file path is provided but file doesn't exist
    * @throws {VizzlyError} When file cannot be read due to permissions or I/O errors
    */

package/dist/services/api-service.js

@@ -357,4 +357,46 @@ export class ApiService {
       }
     });
   }
+
+  /**
+   * Get hotspot analysis for a single screenshot
+   * @param {string} screenshotName - Screenshot name to get hotspots for
+   * @param {Object} options - Optional settings
+   * @param {number} [options.windowSize=20] - Number of historical builds to analyze
+   * @returns {Promise<Object>} Hotspot analysis data
+   */
+  async getScreenshotHotspots(screenshotName, options = {}) {
+    let {
+      windowSize = 20
+    } = options;
+    let queryParams = new URLSearchParams({
+      windowSize: String(windowSize)
+    });
+    let encodedName = encodeURIComponent(screenshotName);
+    return this.request(`/api/sdk/screenshots/${encodedName}/hotspots?${queryParams}`);
+  }
+
+  /**
+   * Batch get hotspot analysis for multiple screenshots
+   * More efficient than calling getScreenshotHotspots for each screenshot
+   * @param {string[]} screenshotNames - Array of screenshot names
+   * @param {Object} options - Optional settings
+   * @param {number} [options.windowSize=20] - Number of historical builds to analyze
+   * @returns {Promise<Object>} Hotspots keyed by screenshot name
+   */
+  async getBatchHotspots(screenshotNames, options = {}) {
+    let {
+      windowSize = 20
+    } = options;
+    return this.request('/api/sdk/screenshots/hotspots', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({
+        screenshot_names: screenshotNames,
+        windowSize
+      })
+    });
+  }
 }

package/dist/services/tdd-service.js

@@ -420,6 +420,9 @@ export class TddService {
       const metadataPath = join(this.baselinePath, 'metadata.json');
       writeFileSync(metadataPath, JSON.stringify(this.baselineData, null, 2));
 
+      // Download hotspot data for noise filtering
+      await this.downloadHotspots(buildDetails.screenshots);
+
       // Save baseline build metadata for MCP plugin
       const baselineMetadataPath = safePath(this.workingDir, '.vizzly', 'baseline-metadata.json');
       const buildMetadata = {
@@ -459,6 +462,152 @@ export class TddService {
     }
   }
 
+  /**
+   * Download hotspot data for screenshots from the cloud
+   * Hotspots identify regions that frequently change (timestamps, IDs, etc.)
+   * Used to filter out known dynamic content during comparisons
+   * @param {Array} screenshots - Array of screenshot objects with name property
+   */
+  async downloadHotspots(screenshots) {
+    // Only attempt if we have an API token
+    if (!this.config.apiKey) {
+      output.debug('tdd', 'Skipping hotspot download - no API token configured');
+      return;
+    }
+    try {
+      // Get unique screenshot names
+      let screenshotNames = [...new Set(screenshots.map(s => s.name))];
+      if (screenshotNames.length === 0) {
+        return;
+      }
+      output.info(`🔥 Fetching hotspot data for ${screenshotNames.length} screenshots...`);
+
+      // Use batch endpoint for efficiency
+      let response = await this.api.getBatchHotspots(screenshotNames);
+      if (!response.hotspots || Object.keys(response.hotspots).length === 0) {
+        output.debug('tdd', 'No hotspot data available from cloud');
+        return;
+      }
+
+      // Store hotspots in a separate file for easy access during comparisons
+      this.hotspotData = response.hotspots;
+      let hotspotsPath = safePath(this.workingDir, '.vizzly', 'hotspots.json');
+      writeFileSync(hotspotsPath, JSON.stringify({
+        downloadedAt: new Date().toISOString(),
+        summary: response.summary,
+        hotspots: response.hotspots
+      }, null, 2));
+      let hotspotCount = Object.keys(response.hotspots).length;
+      let totalRegions = Object.values(response.hotspots).reduce((sum, h) => sum + (h.regions?.length || 0), 0);
+      output.info(`✅ Downloaded hotspot data for ${hotspotCount} screenshots (${totalRegions} regions total)`);
+    } catch (error) {
+      // Don't fail baseline download if hotspot fetch fails
+      output.debug('tdd', `Hotspot download failed: ${error.message}`);
+      output.warn('⚠️  Could not fetch hotspot data - comparisons will run without noise filtering');
+    }
+  }
+
+  /**
+   * Load hotspot data from disk
+   * @returns {Object|null} Hotspot data keyed by screenshot name, or null if not available
+   */
+  loadHotspots() {
+    try {
+      let hotspotsPath = safePath(this.workingDir, '.vizzly', 'hotspots.json');
+      if (!existsSync(hotspotsPath)) {
+        return null;
+      }
+      let data = JSON.parse(readFileSync(hotspotsPath, 'utf8'));
+      return data.hotspots || null;
+    } catch (error) {
+      output.debug('tdd', `Failed to load hotspots: ${error.message}`);
+      return null;
+    }
+  }
+
+  /**
+   * Get hotspot analysis for a specific screenshot
+   * @param {string} screenshotName - Name of the screenshot
+   * @returns {Object|null} Hotspot analysis or null if not available
+   */
+  getHotspotForScreenshot(screenshotName) {
+    // Check memory cache first
+    if (this.hotspotData && this.hotspotData[screenshotName]) {
+      return this.hotspotData[screenshotName];
+    }
+
+    // Try loading from disk
+    if (!this.hotspotData) {
+      this.hotspotData = this.loadHotspots();
+    }
+    return this.hotspotData?.[screenshotName] || null;
+  }
+
+  /**
+   * Calculate what percentage of diff falls within hotspot regions
+   * Uses 1D Y-coordinate matching (same algorithm as cloud)
+   * @param {Array} diffClusters - Array of diff clusters from honeydiff
+   * @param {Object} hotspotAnalysis - Hotspot data with regions array
+   * @returns {Object} Coverage info { coverage, linesInHotspots, totalLines }
+   */
+  calculateHotspotCoverage(diffClusters, hotspotAnalysis) {
+    if (!diffClusters || diffClusters.length === 0) {
+      return {
+        coverage: 0,
+        linesInHotspots: 0,
+        totalLines: 0
+      };
+    }
+    if (!hotspotAnalysis || !hotspotAnalysis.regions || hotspotAnalysis.regions.length === 0) {
+      return {
+        coverage: 0,
+        linesInHotspots: 0,
+        totalLines: 0
+      };
+    }
+
+    // Extract Y-coordinates (diff lines) from clusters
+    // Each cluster has a boundingBox with y and height
+    let diffLines = [];
+    for (let cluster of diffClusters) {
+      if (cluster.boundingBox) {
+        let {
+          y,
+          height
+        } = cluster.boundingBox;
+        // Add all Y lines covered by this cluster
+        for (let line = y; line < y + height; line++) {
+          diffLines.push(line);
+        }
+      }
+    }
+    if (diffLines.length === 0) {
+      return {
+        coverage: 0,
+        linesInHotspots: 0,
+        totalLines: 0
+      };
+    }
+
+    // Remove duplicates and sort
+    diffLines = [...new Set(diffLines)].sort((a, b) => a - b);
+
+    // Check how many diff lines fall within hotspot regions
+    let linesInHotspots = 0;
+    for (let line of diffLines) {
+      let inHotspot = hotspotAnalysis.regions.some(region => line >= region.y1 && line <= region.y2);
+      if (inHotspot) {
+        linesInHotspots++;
+      }
+    }
+    let coverage = linesInHotspots / diffLines.length;
+    return {
+      coverage,
+      linesInHotspots,
+      totalLines: diffLines.length
+    };
+  }
+
   /**
    * Download baselines using OAuth authentication
    * Used when user is logged in via device flow but no API token is configured
@@ -784,17 +933,36 @@ export class TddService {
         this.comparisons.push(comparison);
         return comparison;
       } else {
-        // Images differ
+        // Images differ - check if differences are in known hotspot regions
+        let hotspotAnalysis = this.getHotspotForScreenshot(name);
+        let hotspotCoverage = null;
+        let isHotspotFiltered = false;
+        if (hotspotAnalysis && result.diffClusters && result.diffClusters.length > 0) {
+          hotspotCoverage = this.calculateHotspotCoverage(result.diffClusters, hotspotAnalysis);
+
+          // Consider it filtered if:
+          // 1. High confidence hotspot data (score >= 70)
+          // 2. 80%+ of the diff is within hotspot regions
+          let isHighConfidence = hotspotAnalysis.confidence === 'high' || hotspotAnalysis.confidence_score && hotspotAnalysis.confidence_score >= 70;
+          if (isHighConfidence && hotspotCoverage.coverage >= 0.8) {
+            isHotspotFiltered = true;
+          }
+        }
         let diffInfo = ` (${result.diffPercentage.toFixed(2)}% different, ${result.diffPixels} pixels)`;
 
         // Add cluster info to log if available
         if (result.diffClusters && result.diffClusters.length > 0) {
           diffInfo += `, ${result.diffClusters.length} region${result.diffClusters.length > 1 ? 's' : ''}`;
         }
+
+        // Add hotspot info if applicable
+        if (hotspotCoverage && hotspotCoverage.coverage > 0) {
+          diffInfo += `, ${Math.round(hotspotCoverage.coverage * 100)}% in hotspots`;
+        }
         const comparison = {
           id: generateComparisonId(signature),
           name: sanitizedName,
-          status: 'failed',
+          status: isHotspotFiltered ? 'passed' : 'failed',
           baseline: baselineImagePath,
           current: currentImagePath,
           diff: diffImagePath,
@@ -803,7 +971,7 @@ export class TddService {
           threshold: this.threshold,
           diffPercentage: result.diffPercentage,
           diffCount: result.diffPixels,
-          reason: 'pixel-diff',
+          reason: isHotspotFiltered ? 'hotspot-filtered' : 'pixel-diff',
           // Honeydiff metrics
           totalPixels: result.totalPixels,
           aaPixelsIgnored: result.aaPixelsIgnored,
@@ -811,10 +979,25 @@ export class TddService {
           boundingBox: result.boundingBox,
           heightDiff: result.heightDiff,
           intensityStats: result.intensityStats,
-          diffClusters: result.diffClusters
+          diffClusters: result.diffClusters,
+          // Hotspot analysis data
+          hotspotAnalysis: hotspotCoverage ? {
+            coverage: hotspotCoverage.coverage,
+            linesInHotspots: hotspotCoverage.linesInHotspots,
+            totalLines: hotspotCoverage.totalLines,
+            confidence: hotspotAnalysis?.confidence,
+            confidenceScore: hotspotAnalysis?.confidence_score,
+            regionCount: hotspotAnalysis?.regions?.length || 0,
+            isFiltered: isHotspotFiltered
+          } : null
         };
-        output.warn(`❌ ${colors.red('FAILED')} ${sanitizedName} - differences detected${diffInfo}`);
-        output.info(`    Diff saved to: ${diffImagePath}`);
+        if (isHotspotFiltered) {
+          output.info(`✅ ${colors.green('PASSED')} ${sanitizedName} - differences in known hotspots${diffInfo}`);
+          output.debug('tdd', `Hotspot filtered: ${Math.round(hotspotCoverage.coverage * 100)}% coverage, confidence: ${hotspotAnalysis.confidence}`);
+        } else {
+          output.warn(`❌ ${colors.red('FAILED')} ${sanitizedName} - differences detected${diffInfo}`);
+          output.info(`    Diff saved to: ${diffImagePath}`);
+        }
         this.comparisons.push(comparison);
         return comparison;
       }

package/dist/services/test-runner.js

@@ -94,14 +94,6 @@ export class TestRunner extends EventEmitter {
 
       // Start server with appropriate handler
       await this.serverManager.start(buildId, tdd, options.setBaseline);
-
-      // Forward server events
-      if (this.serverManager.server?.emitter) {
-        this.serverManager.server.emitter.on('screenshot-captured', screenshotInfo => {
-          screenshotCount++;
-          this.emit('screenshot-captured', screenshotInfo);
-        });
-      }
       const env = {
         ...process.env,
         VIZZLY_SERVER_URL: `http://localhost:${this.config.server.port}`,

package/dist/services/uploader.js

@@ -24,7 +24,7 @@ export function createUploader({
   userAgent,
   command,
   upload: uploadConfig = {}
-}, options = {}) {
+} = {}, options = {}) {
   let signal = options.signal || new AbortController().signal;
   const api = new ApiService({
     baseUrl: apiUrl,

package/dist/types/client.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Vizzly Client Type Definitions
+ * Lightweight client for test runners
+ * @module @vizzly-testing/cli/client
+ */
+
+/**
+ * Take a screenshot for visual regression testing
+ *
+ * @param name - Unique name for the screenshot
+ * @param imageBuffer - PNG image data as a Buffer, or a file path to an image
+ * @param options - Optional configuration
+ *
+ * @example
+ * // Basic usage with Buffer
+ * import { vizzlyScreenshot } from '@vizzly-testing/cli/client';
+ *
+ * const screenshot = await page.screenshot();
+ * await vizzlyScreenshot('homepage', screenshot);
+ *
+ * @example
+ * // Basic usage with file path
+ * await vizzlyScreenshot('homepage', './screenshots/homepage.png');
+ *
+ * @example
+ * // With properties and threshold
+ * await vizzlyScreenshot('checkout-form', screenshot, {
+ *   properties: { browser: 'chrome', viewport: '1920x1080' },
+ *   threshold: 5
+ * });
+ */
+export function vizzlyScreenshot(
+  name: string,
+  imageBuffer: Buffer | string,
+  options?: {
+    properties?: Record<string, unknown>;
+    threshold?: number;
+    fullPage?: boolean;
+  }
+): Promise<void>;
+
+/**
+ * Wait for all queued screenshots to be processed
+ *
+ * @example
+ * afterAll(async () => {
+ *   await vizzlyFlush();
+ * });
+ */
+export function vizzlyFlush(): Promise<void>;
+
+/**
+ * Check if the Vizzly client is initialized and ready
+ *
+ * @returns True if client is ready, false otherwise
+ */
+export function isVizzlyReady(): boolean;
+
+/**
+ * Configure the client with custom settings
+ *
+ * @param config - Configuration options
+ */
+export function configure(config?: {
+  serverUrl?: string;
+  enabled?: boolean;
+}): void;
+
+/**
+ * Enable or disable screenshot capture
+ *
+ * @param enabled - Whether to enable screenshots
+ */
+export function setEnabled(enabled: boolean): void;
+
+/**
+ * Get information about Vizzly client state
+ *
+ * @returns Client information
+ */
+export function getVizzlyInfo(): {
+  enabled: boolean;
+  serverUrl: string | null;
+  ready: boolean;
+  buildId: string | null;
+  tddMode: boolean;
+  disabled: boolean;
+};

package/dist/types/config.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Vizzly Config Type Definitions
+ * Configuration helpers
+ * @module @vizzly-testing/cli/config
+ */
+
+export { VizzlyConfig } from './index';
+
+/**
+ * Define Vizzly configuration with type hints
+ *
+ * Use this in your vizzly.config.js for better IDE support:
+ *
+ * @example
+ * import { defineConfig } from '@vizzly-testing/cli/config';
+ *
+ * export default defineConfig({
+ *   apiKey: process.env.VIZZLY_TOKEN,
+ *   server: {
+ *     port: 47392
+ *   },
+ *   comparison: {
+ *     threshold: 0.1
+ *   }
+ * });
+ */
+export function defineConfig(
+  config: import('./index').VizzlyConfig
+): import('./index').VizzlyConfig;