@vizzly-testing/cli 0.20.0 → 0.20.1-beta.0

package/dist/tdd/services/comparison-service.js

@@ -0,0 +1,230 @@
+/**
+ * Comparison Service
+ *
+ * Wraps honeydiff for image comparison and builds comparison result objects.
+ */
+
+import { compare } from '@vizzly-testing/honeydiff';
+import { calculateHotspotCoverage } from '../core/hotspot-coverage.js';
+import { generateComparisonId } from '../core/signature.js';
+
+/**
+ * Compare two images using honeydiff
+ *
+ * @param {string} baselinePath - Path to baseline image
+ * @param {string} currentPath - Path to current image
+ * @param {string} diffPath - Path to save diff image
+ * @param {Object} options - Comparison options
+ * @param {number} options.threshold - CIEDE2000 Delta E threshold (default: 2.0)
+ * @param {number} options.minClusterSize - Minimum cluster size (default: 2)
+ * @returns {Promise<Object>} Honeydiff result
+ * @throws {Error} When honeydiff binary fails (e.g., corrupt images, dimension mismatch)
+ */
+export async function compareImages(baselinePath, currentPath, diffPath, options = {}) {
+  let {
+    threshold = 2.0,
+    minClusterSize = 2
+  } = options;
+  return compare(baselinePath, currentPath, {
+    threshold,
+    antialiasing: true,
+    diffPath,
+    overwrite: true,
+    includeClusters: true,
+    minClusterSize
+  });
+}
+
+/**
+ * Build a comparison result object for a passing comparison (no diff)
+ *
+ * @param {Object} params
+ * @param {string} params.name - Screenshot name
+ * @param {string} params.signature - Screenshot signature
+ * @param {string} params.baselinePath - Path to baseline image
+ * @param {string} params.currentPath - Path to current image
+ * @param {Object} params.properties - Screenshot properties
+ * @param {number} params.threshold - Effective threshold used
+ * @param {number} params.minClusterSize - Effective minClusterSize used
+ * @param {Object} params.honeydiffResult - Result from honeydiff (optional, for metrics)
+ * @returns {Object} Comparison result
+ */
+export function buildPassedComparison(params) {
+  let {
+    name,
+    signature,
+    baselinePath,
+    currentPath,
+    properties,
+    threshold,
+    minClusterSize,
+    honeydiffResult
+  } = params;
+  return {
+    id: generateComparisonId(signature),
+    name,
+    status: 'passed',
+    baseline: baselinePath,
+    current: currentPath,
+    diff: null,
+    properties,
+    signature,
+    threshold,
+    minClusterSize,
+    totalPixels: honeydiffResult?.totalPixels,
+    aaPixelsIgnored: honeydiffResult?.aaPixelsIgnored,
+    aaPercentage: honeydiffResult?.aaPercentage
+  };
+}
+
+/**
+ * Build a comparison result object for a new baseline
+ *
+ * @param {Object} params
+ * @param {string} params.name - Screenshot name
+ * @param {string} params.signature - Screenshot signature
+ * @param {string} params.baselinePath - Path to baseline image
+ * @param {string} params.currentPath - Path to current image
+ * @param {Object} params.properties - Screenshot properties
+ * @returns {Object} Comparison result
+ */
+export function buildNewComparison(params) {
+  let {
+    name,
+    signature,
+    baselinePath,
+    currentPath,
+    properties
+  } = params;
+  return {
+    id: generateComparisonId(signature),
+    name,
+    status: 'new',
+    baseline: baselinePath,
+    current: currentPath,
+    diff: null,
+    properties,
+    signature
+  };
+}
+
+/**
+ * Build a comparison result object for a failed comparison (with diff)
+ *
+ * @param {Object} params
+ * @param {string} params.name - Screenshot name
+ * @param {string} params.signature - Screenshot signature
+ * @param {string} params.baselinePath - Path to baseline image
+ * @param {string} params.currentPath - Path to current image
+ * @param {string} params.diffPath - Path to diff image
+ * @param {Object} params.properties - Screenshot properties
+ * @param {number} params.threshold - Effective threshold used
+ * @param {number} params.minClusterSize - Effective minClusterSize used
+ * @param {Object} params.honeydiffResult - Result from honeydiff
+ * @param {Object} params.hotspotAnalysis - Hotspot data for this screenshot (optional)
+ * @returns {Object} Comparison result
+ */
+export function buildFailedComparison(params) {
+  let {
+    name,
+    signature,
+    baselinePath,
+    currentPath,
+    diffPath,
+    properties,
+    threshold,
+    minClusterSize,
+    honeydiffResult,
+    hotspotAnalysis
+  } = params;
+
+  // Calculate hotspot coverage if we have hotspot data
+  let hotspotCoverage = null;
+  let isHotspotFiltered = false;
+  if (hotspotAnalysis && honeydiffResult.diffClusters?.length > 0) {
+    hotspotCoverage = calculateHotspotCoverage(honeydiffResult.diffClusters, hotspotAnalysis);
+
+    // Check if diff should be filtered as hotspot noise
+    // Using shouldFilterAsHotspot helper but also checking confidence_score
+    // (cloud uses confidence_score >= 70 which is >0.7 when normalized)
+    let isHighConfidence = hotspotAnalysis.confidence === 'high' || hotspotAnalysis.confidence_score !== undefined && hotspotAnalysis.confidence_score >= 70;
+    if (isHighConfidence && hotspotCoverage.coverage >= 0.8) {
+      isHotspotFiltered = true;
+    }
+  }
+  return {
+    id: generateComparisonId(signature),
+    name,
+    status: isHotspotFiltered ? 'passed' : 'failed',
+    baseline: baselinePath,
+    current: currentPath,
+    diff: diffPath,
+    properties,
+    signature,
+    threshold,
+    minClusterSize,
+    diffPercentage: honeydiffResult.diffPercentage,
+    diffCount: honeydiffResult.diffPixels,
+    reason: isHotspotFiltered ? 'hotspot-filtered' : 'pixel-diff',
+    totalPixels: honeydiffResult.totalPixels,
+    aaPixelsIgnored: honeydiffResult.aaPixelsIgnored,
+    aaPercentage: honeydiffResult.aaPercentage,
+    boundingBox: honeydiffResult.boundingBox,
+    heightDiff: honeydiffResult.heightDiff,
+    intensityStats: honeydiffResult.intensityStats,
+    diffClusters: honeydiffResult.diffClusters,
+    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
+  };
+}
+
+/**
+ * Build a comparison result object for an error
+ *
+ * @param {Object} params
+ * @param {string} params.name - Screenshot name
+ * @param {string} params.signature - Screenshot signature
+ * @param {string} params.baselinePath - Path to baseline image
+ * @param {string} params.currentPath - Path to current image
+ * @param {Object} params.properties - Screenshot properties
+ * @param {string} params.errorMessage - Error message
+ * @returns {Object} Comparison result
+ */
+export function buildErrorComparison(params) {
+  let {
+    name,
+    signature,
+    baselinePath,
+    currentPath,
+    properties,
+    errorMessage
+  } = params;
+  return {
+    id: generateComparisonId(signature),
+    name,
+    status: 'error',
+    baseline: baselinePath,
+    current: currentPath,
+    diff: null,
+    properties,
+    signature,
+    error: errorMessage
+  };
+}
+
+/**
+ * Check if an error is a dimension mismatch from honeydiff
+ *
+ * @param {Error} error
+ * @returns {boolean}
+ */
+export function isDimensionMismatchError(error) {
+  return error.message?.includes("Image dimensions don't match") ?? false;
+}

package/dist/tdd/services/hotspot-service.js

@@ -0,0 +1,71 @@
+/**
+ * Hotspot Service
+ *
+ * Functions for downloading and managing hotspot data from the cloud.
+ * Hotspots identify regions that frequently change due to dynamic content.
+ */
+
+import { saveHotspotMetadata } from '../metadata/hotspot-metadata.js';
+
+/**
+ * Download hotspots for screenshots from cloud API
+ *
+ * @param {Object} options
+ * @param {Object} options.api - ApiService instance
+ * @param {string} options.workingDir - Working directory
+ * @param {string[]} options.screenshotNames - Names of screenshots to get hotspots for
+ * @returns {Promise<{ success: boolean, count: number, regionCount: number, error?: string }>}
+ */
+export async function downloadHotspots(options) {
+  let {
+    api,
+    workingDir,
+    screenshotNames
+  } = options;
+  if (!screenshotNames || screenshotNames.length === 0) {
+    return {
+      success: true,
+      count: 0,
+      regionCount: 0
+    };
+  }
+  try {
+    let response = await api.getHotspots(screenshotNames);
+    if (!response || !response.hotspots) {
+      return {
+        success: false,
+        error: 'API returned no hotspot data'
+      };
+    }
+
+    // Save hotspots to disk
+    saveHotspotMetadata(workingDir, response.hotspots, response.summary);
+
+    // Calculate stats
+    let count = Object.keys(response.hotspots).length;
+    let regionCount = Object.values(response.hotspots).reduce((sum, h) => sum + (h.regions?.length || 0), 0);
+    return {
+      success: true,
+      count,
+      regionCount
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error.message
+    };
+  }
+}
+
+/**
+ * Extract screenshot names from a list of screenshots
+ *
+ * @param {Array} screenshots - Screenshots with name property
+ * @returns {string[]}
+ */
+export function extractScreenshotNames(screenshots) {
+  if (!screenshots || !Array.isArray(screenshots)) {
+    return [];
+  }
+  return screenshots.map(s => s.name).filter(Boolean);
+}

package/dist/tdd/services/result-service.js

@@ -0,0 +1,123 @@
+/**
+ * Result Service
+ *
+ * Aggregates comparison results and provides summary statistics.
+ */
+
+/**
+ * Calculate summary statistics from comparisons
+ *
+ * @param {Array} comparisons - Array of comparison results
+ * @returns {{ total: number, passed: number, failed: number, new: number, errors: number }}
+ */
+export function calculateSummary(comparisons) {
+  let passed = 0;
+  let failed = 0;
+  let newScreenshots = 0;
+  let errors = 0;
+  for (let c of comparisons) {
+    switch (c.status) {
+      case 'passed':
+        passed++;
+        break;
+      case 'failed':
+        failed++;
+        break;
+      case 'new':
+        newScreenshots++;
+        break;
+      case 'error':
+        errors++;
+        break;
+    }
+  }
+  return {
+    total: comparisons.length,
+    passed,
+    failed,
+    new: newScreenshots,
+    errors
+  };
+}
+
+/**
+ * Build complete results object
+ *
+ * @param {Array} comparisons - Array of comparison results
+ * @param {Object} baselineData - Baseline metadata
+ * @returns {Object} Results object with summary and comparisons
+ */
+export function buildResults(comparisons, baselineData) {
+  let summary = calculateSummary(comparisons);
+  return {
+    ...summary,
+    comparisons,
+    baseline: baselineData
+  };
+}
+
+/**
+ * Get failed comparisons from results
+ *
+ * @param {Array} comparisons - Array of comparison results
+ * @returns {Array} Failed comparisons
+ */
+export function getFailedComparisons(comparisons) {
+  return comparisons.filter(c => c.status === 'failed');
+}
+
+/**
+ * Get new comparisons from results
+ *
+ * @param {Array} comparisons - Array of comparison results
+ * @returns {Array} New comparisons
+ */
+export function getNewComparisons(comparisons) {
+  return comparisons.filter(c => c.status === 'new');
+}
+
+/**
+ * Get error comparisons from results
+ *
+ * @param {Array} comparisons - Array of comparison results
+ * @returns {Array} Error comparisons
+ */
+export function getErrorComparisons(comparisons) {
+  return comparisons.filter(c => c.status === 'error');
+}
+
+/**
+ * Check if results indicate overall success (no failures or errors)
+ *
+ * @param {Array} comparisons - Array of comparison results
+ * @returns {boolean}
+ */
+export function isSuccessful(comparisons) {
+  return !comparisons.some(c => c.status === 'failed' || c.status === 'error');
+}
+
+/**
+ * Find comparison by ID
+ *
+ * @param {Array} comparisons - Array of comparison results
+ * @param {string} id - Comparison ID
+ * @returns {Object|null}
+ */
+export function findComparisonById(comparisons, id) {
+  return comparisons.find(c => c.id === id) || null;
+}
+
+/**
+ * Find comparison by name and signature
+ *
+ * @param {Array} comparisons - Array of comparison results
+ * @param {string} name - Screenshot name
+ * @param {string} signature - Screenshot signature (optional)
+ * @returns {Object|null}
+ */
+export function findComparison(comparisons, name, signature = null) {
+  if (signature) {
+    return comparisons.find(c => c.signature === signature) || null;
+  }
+  return comparisons.find(c => c.name === name) || null;
+}