@vizzly-testing/cli 0.12.0 → 0.13.0

package/dist/server/handlers/api-handler.js

@@ -1,5 +1,8 @@
 import { Buffer } from 'buffer';
+import { existsSync, readFileSync } from 'fs';
+import { resolve } from 'path';
 import { createServiceLogger } from '../../utils/logger-factory.js';
+import { detectImageInputType } from '../../utils/image-input-detector.js';
 const logger = createServiceLogger('API-HANDLER');
 
 /**
@@ -60,7 +63,56 @@ export const createApiHandler = apiService => {
         }
       };
     }
-    const imageBuffer = Buffer.from(image, 'base64');
+
+    // Support both base64 encoded images and file paths
+    let imageBuffer;
+    const inputType = detectImageInputType(image);
+    if (inputType === 'file-path') {
+      // It's a file path - resolve and read the file
+      const filePath = resolve(image.replace('file://', ''));
+      if (!existsSync(filePath)) {
+        return {
+          statusCode: 400,
+          body: {
+            error: `Screenshot file not found: ${filePath}`,
+            originalPath: image
+          }
+        };
+      }
+      try {
+        imageBuffer = readFileSync(filePath);
+        logger.debug(`Loaded screenshot from file: ${filePath}`);
+      } catch (error) {
+        return {
+          statusCode: 500,
+          body: {
+            error: `Failed to read screenshot file: ${error.message}`,
+            filePath
+          }
+        };
+      }
+    } else if (inputType === 'base64') {
+      // It's base64 encoded
+      try {
+        imageBuffer = Buffer.from(image, 'base64');
+      } catch (error) {
+        return {
+          statusCode: 400,
+          body: {
+            error: `Invalid base64 image data: ${error.message}`
+          }
+        };
+      }
+    } else {
+      // Unknown input type
+      return {
+        statusCode: 400,
+        body: {
+          error: 'Invalid image input: must be a file path or base64 encoded image data',
+          receivedType: typeof image
+        }
+      };
+    }
     screenshotCount++;
 
     // Fire upload in background - DON'T AWAIT!

package/dist/server/handlers/tdd-handler.js

@@ -1,10 +1,134 @@
 import { Buffer } from 'buffer';
 import { writeFileSync, readFileSync, existsSync } from 'fs';
-import { join } from 'path';
+import { join, resolve } from 'path';
 import { createServiceLogger } from '../../utils/logger-factory.js';
 import { TddService } from '../../services/tdd-service.js';
 import { sanitizeScreenshotName, validateScreenshotProperties } from '../../utils/security.js';
+import { detectImageInputType } from '../../utils/image-input-detector.js';
 const logger = createServiceLogger('TDD-HANDLER');
+
+/**
+ * Detect PNG dimensions by reading the IHDR chunk header
+ * PNG spec (ISO/IEC 15948:2004) guarantees width/height at bytes 16-23
+ * @param {Buffer} buffer - PNG image buffer
+ * @returns {{ width: number, height: number } | null} Dimensions or null if not a valid PNG
+ */
+const detectPNGDimensions = buffer => {
+  // Full PNG signature (8 bytes): 89 50 4E 47 0D 0A 1A 0A
+  const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+
+  // Need at least 24 bytes (8 signature + 4 length + 4 type + 8 width/height)
+  if (!buffer || buffer.length < 24) {
+    return null;
+  }
+
+  // Validate full 8-byte PNG signature
+  for (let i = 0; i < PNG_SIGNATURE.length; i++) {
+    if (buffer[i] !== PNG_SIGNATURE[i]) {
+      return null;
+    }
+  }
+
+  // Validate IHDR chunk type at bytes 12-15 (should be 'IHDR')
+  // 0x49484452 = 'IHDR' in ASCII
+  if (buffer[12] !== 0x49 || buffer[13] !== 0x48 || buffer[14] !== 0x44 || buffer[15] !== 0x52) {
+    return null;
+  }
+
+  // Read width and height from IHDR chunk (guaranteed positions per PNG spec)
+  const width = buffer.readUInt32BE(16); // Bytes 16-19
+  const height = buffer.readUInt32BE(20); // Bytes 20-23
+
+  // Sanity check: dimensions should be positive and reasonable
+  if (width <= 0 || height <= 0 || width > 65535 || height > 65535) {
+    return null;
+  }
+  return {
+    width,
+    height
+  };
+};
+
+/**
+ * Group comparisons by screenshot name with variant structure
+ * Matches cloud product's grouping logic from comparison.js
+ */
+const groupComparisons = comparisons => {
+  const groups = new Map();
+
+  // Group by screenshot name
+  for (const comp of comparisons) {
+    if (!groups.has(comp.name)) {
+      groups.set(comp.name, {
+        name: comp.name,
+        comparisons: [],
+        browsers: new Set(),
+        viewports: new Set(),
+        devices: new Set(),
+        totalVariants: 0
+      });
+    }
+    const group = groups.get(comp.name);
+    group.comparisons.push(comp);
+    group.totalVariants++;
+
+    // Track unique browsers, viewports, devices
+    if (comp.properties?.browser) {
+      group.browsers.add(comp.properties.browser);
+    }
+    if (comp.properties?.viewport_width && comp.properties?.viewport_height) {
+      group.viewports.add(`${comp.properties.viewport_width}x${comp.properties.viewport_height}`);
+    }
+    if (comp.properties?.device) {
+      group.devices.add(comp.properties.device);
+    }
+  }
+
+  // Convert to final structure
+  return Array.from(groups.values()).map(group => {
+    const browsers = Array.from(group.browsers);
+    const viewports = Array.from(group.viewports);
+    const devices = Array.from(group.devices);
+
+    // Build variants structure (browser -> viewport -> comparisons)
+    const variants = {};
+    group.comparisons.forEach(comp => {
+      const browser = comp.properties?.browser || null;
+      const viewport = comp.properties?.viewport_width && comp.properties?.viewport_height ? `${comp.properties.viewport_width}x${comp.properties.viewport_height}` : null;
+      if (!variants[browser]) variants[browser] = {};
+      if (!variants[browser][viewport]) variants[browser][viewport] = [];
+      variants[browser][viewport].push(comp);
+    });
+
+    // Determine grouping strategy
+    let groupingStrategy = 'flat';
+    if (browsers.length > 1) groupingStrategy = 'browser';else if (viewports.length > 1) groupingStrategy = 'viewport';
+
+    // Sort comparisons by viewport area (largest first)
+    group.comparisons.sort((a, b) => {
+      const aArea = (a.properties?.viewport_width || 0) * (a.properties?.viewport_height || 0);
+      const bArea = (b.properties?.viewport_width || 0) * (b.properties?.viewport_height || 0);
+      if (bArea !== aArea) return bArea - aArea;
+      return (b.properties?.viewport_width || 0) - (a.properties?.viewport_width || 0);
+    });
+    return {
+      ...group,
+      browsers,
+      viewports,
+      devices: Array.from(devices),
+      variants,
+      groupingStrategy
+    };
+  }).sort((a, b) => {
+    // Sort groups: multi-variant first (by variant count), then singles alphabetically
+    if (a.totalVariants > 1 && b.totalVariants === 1) return -1;
+    if (a.totalVariants === 1 && b.totalVariants > 1) return 1;
+    if (a.totalVariants > 1 && b.totalVariants > 1) {
+      return b.totalVariants - a.totalVariants;
+    }
+    return a.name.localeCompare(b.name);
+  });
+};
 export const createTddHandler = (config, workingDir, baselineBuild, baselineComparison, setBaseline = false) => {
   const tddService = new TddService(config, workingDir, setBaseline);
   const reportPath = join(workingDir, '.vizzly', 'report-data.json');
@@ -14,8 +138,12 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
         return {
           timestamp: Date.now(),
           comparisons: [],
+          // Internal flat list for easy updates
+          groups: [],
+          // Grouped structure for UI
           summary: {
             total: 0,
+            groups: 0,
             passed: 0,
             failed: 0,
             errors: 0
@@ -29,8 +157,10 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
       return {
         timestamp: Date.now(),
         comparisons: [],
+        groups: [],
         summary: {
           total: 0,
+          groups: 0,
           passed: 0,
           failed: 0,
           errors: 0
@@ -42,26 +172,36 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
     try {
       const reportData = readReportData();
 
-      // Find existing comparison with same name and replace it, or add new one
-      const existingIndex = reportData.comparisons.findIndex(c => c.name === newComparison.name);
+      // Ensure comparisons array exists (backward compatibility)
+      if (!reportData.comparisons) {
+        reportData.comparisons = [];
+      }
+
+      // Find existing comparison by unique ID
+      // This ensures we update the correct variant even with same name
+      const existingIndex = reportData.comparisons.findIndex(c => c.id === newComparison.id);
       if (existingIndex >= 0) {
         reportData.comparisons[existingIndex] = newComparison;
-        logger.debug(`Updated comparison for ${newComparison.name}`);
+        logger.debug(`Updated comparison for ${newComparison.name} (${newComparison.properties?.viewport_width}x${newComparison.properties?.viewport_height})`);
       } else {
         reportData.comparisons.push(newComparison);
-        logger.debug(`Added new comparison for ${newComparison.name}`);
+        logger.debug(`Added new comparison for ${newComparison.name} (${newComparison.properties?.viewport_width}x${newComparison.properties?.viewport_height})`);
       }
 
+      // Generate grouped structure from flat comparisons
+      reportData.groups = groupComparisons(reportData.comparisons);
+
       // Update summary
       reportData.timestamp = Date.now();
       reportData.summary = {
         total: reportData.comparisons.length,
-        passed: reportData.comparisons.filter(c => c.status === 'passed' || c.status === 'baseline-created').length,
+        groups: reportData.groups.length,
+        passed: reportData.comparisons.filter(c => c.status === 'passed' || c.status === 'baseline-created' || c.status === 'new').length,
         failed: reportData.comparisons.filter(c => c.status === 'failed').length,
         errors: reportData.comparisons.filter(c => c.status === 'error').length
       };
       writeFileSync(reportPath, JSON.stringify(reportData, null, 2));
-      logger.debug('Report data saved to report-data.json');
+      logger.debug('Report data saved with grouped structure');
     } catch (error) {
       logger.error('Failed to update comparison:', error);
     }
@@ -111,10 +251,24 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
       };
     }
 
+    // Unwrap double-nested properties if needed (client SDK wraps options in properties field)
+    // This happens when test helper passes { properties: {...}, threshold: 0.1 }
+    // and client SDK wraps it as { properties: options }
+    let unwrappedProperties = properties;
+    if (properties.properties && typeof properties.properties === 'object') {
+      // Merge top-level properties with nested properties
+      unwrappedProperties = {
+        ...properties,
+        ...properties.properties
+      };
+      // Remove the nested properties field to avoid confusion
+      delete unwrappedProperties.properties;
+    }
+
     // Validate and sanitize properties
     let validatedProperties;
     try {
-      validatedProperties = validateScreenshotProperties(properties);
+      validatedProperties = validateScreenshotProperties(unwrappedProperties);
     } catch (error) {
       return {
         statusCode: 400,
@@ -125,14 +279,94 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
         }
       };
     }
-    const imageBuffer = Buffer.from(image, 'base64');
-    logger.debug(`Received screenshot: ${name}`);
-    logger.debug(`Image size: ${imageBuffer.length} bytes`);
-    logger.debug(`Properties: ${JSON.stringify(validatedProperties)}`);
+
+    // Extract viewport/browser to top-level properties (matching cloud API behavior)
+    // This ensures signature generation works correctly with: name|viewport_width|browser
+    const extractedProperties = {
+      viewport_width: validatedProperties.viewport?.width || null,
+      viewport_height: validatedProperties.viewport?.height || null,
+      browser: validatedProperties.browser || null,
+      device: validatedProperties.device || null,
+      url: validatedProperties.url || null,
+      selector: validatedProperties.selector || null,
+      threshold: validatedProperties.threshold,
+      // Preserve full nested structure in metadata for compatibility
+      metadata: validatedProperties
+    };
+
+    // Support both base64 encoded images and file paths
+    // Vitest browser mode returns file paths, so we need to handle both
+    let imageBuffer;
+    const inputType = detectImageInputType(image);
+    if (inputType === 'file-path') {
+      // It's a file path - resolve and read the file
+      const filePath = resolve(image.replace('file://', ''));
+      if (!existsSync(filePath)) {
+        return {
+          statusCode: 400,
+          body: {
+            error: `Screenshot file not found: ${filePath}`,
+            originalPath: image,
+            tddMode: true
+          }
+        };
+      }
+      try {
+        imageBuffer = readFileSync(filePath);
+        logger.debug(`Loaded screenshot from file: ${filePath}`);
+      } catch (error) {
+        return {
+          statusCode: 500,
+          body: {
+            error: `Failed to read screenshot file: ${error.message}`,
+            filePath,
+            tddMode: true
+          }
+        };
+      }
+    } else if (inputType === 'base64') {
+      // It's base64 encoded
+      try {
+        imageBuffer = Buffer.from(image, 'base64');
+      } catch (error) {
+        return {
+          statusCode: 400,
+          body: {
+            error: `Invalid base64 image data: ${error.message}`,
+            tddMode: true
+          }
+        };
+      }
+    } else {
+      // Unknown input type
+      return {
+        statusCode: 400,
+        body: {
+          error: 'Invalid image input: must be a file path or base64 encoded image data',
+          receivedType: typeof image,
+          tddMode: true
+        }
+      };
+    }
+
+    // Auto-detect image dimensions from PNG header if viewport not provided
+    // This matches cloud API behavior but without requiring Sharp
+    if (!extractedProperties.viewport_width || !extractedProperties.viewport_height) {
+      const dimensions = detectPNGDimensions(imageBuffer);
+      if (dimensions) {
+        if (!extractedProperties.viewport_width) {
+          extractedProperties.viewport_width = dimensions.width;
+        }
+        if (!extractedProperties.viewport_height) {
+          extractedProperties.viewport_height = dimensions.height;
+        }
+        logger.debug(`Auto-detected dimensions from PNG: ${dimensions.width}x${dimensions.height}`);
+      }
+    }
 
     // Use the sanitized name as-is (no modification with browser/viewport)
     // Baseline matching uses signature logic (name + viewport_width + browser)
-    const comparison = await tddService.compareScreenshot(sanitizedName, imageBuffer, validatedProperties);
+    const comparison = await tddService.compareScreenshot(sanitizedName, imageBuffer, extractedProperties);
     logger.debug(`Comparison result: ${comparison.status}`);
 
     // Convert absolute file paths to web-accessible URLs
@@ -149,6 +383,8 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
 
     // Record the comparison for the dashboard
     const newComparison = {
+      id: comparison.id,
+      // Include unique ID for variant identification
       name: comparison.name,
       originalName: name,
       status: comparison.status,
@@ -157,7 +393,10 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
       diff: convertPathToUrl(comparison.diff),
       diffPercentage: comparison.diffPercentage,
       threshold: comparison.threshold,
-      properties: validatedProperties,
+      properties: extractedProperties,
+      // Use extracted properties with top-level viewport_width/browser
+      signature: comparison.signature,
+      // Include signature for debugging
       timestamp: Date.now()
     };
 
@@ -223,16 +462,14 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
   const getResults = async () => {
     return await tddService.printResults();
   };
-  const acceptBaseline = async screenshotName => {
+  const acceptBaseline = async comparisonId => {
     try {
-      logger.debug(`Accepting baseline for screenshot: ${screenshotName}`);
-
       // Use TDD service to accept the baseline
-      const result = await tddService.acceptBaseline(screenshotName);
+      const result = await tddService.acceptBaseline(comparisonId);
 
       // Read current report data and update the comparison status
       const reportData = readReportData();
-      const comparison = reportData.comparisons.find(c => c.name === screenshotName);
+      const comparison = reportData.comparisons.find(c => c.id === comparisonId);
       if (comparison) {
         // Update the comparison to passed status
         const updatedComparison = {
@@ -242,14 +479,13 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
           diff: null
         };
         updateComparison(updatedComparison);
-        logger.debug('Comparison updated in report-data.json');
       } else {
-        logger.error(`Comparison not found in report data for: ${screenshotName}`);
+        logger.error(`Comparison not found in report data for ID: ${comparisonId}`);
       }
-      logger.info(`Baseline accepted for ${screenshotName}`);
+      logger.info(`Baseline accepted for comparison ${comparisonId}`);
       return result;
     } catch (error) {
-      logger.error(`Failed to accept baseline for ${screenshotName}:`, error);
+      logger.error(`Failed to accept baseline for ${comparisonId}:`, error);
       throw error;
     }
   };
@@ -262,7 +498,7 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
       // Accept all failed or new comparisons
       for (const comparison of reportData.comparisons) {
         if (comparison.status === 'failed' || comparison.status === 'new') {
-          await tddService.acceptBaseline(comparison.name);
+          await tddService.acceptBaseline(comparison.id);
 
           // Update the comparison to passed status
           updateComparison({
@@ -363,8 +599,10 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
       const freshReportData = {
         timestamp: Date.now(),
         comparisons: [],
+        groups: [],
         summary: {
           total: 0,
+          groups: 0,
           passed: 0,
           failed: 0,
           errors: 0

package/dist/server/http-server.js

@@ -233,21 +233,21 @@ export const createHttpServer = (port, screenshotHandler) => {
       }
       try {
         const {
-          name
+          id
         } = await parseRequestBody(req);
-        if (!name) {
+        if (!id) {
           res.statusCode = 400;
           res.end(JSON.stringify({
-            error: 'Screenshot name required'
+            error: 'Comparison ID required'
           }));
           return;
         }
-        await screenshotHandler.acceptBaseline(name);
+        await screenshotHandler.acceptBaseline(id);
         res.setHeader('Content-Type', 'application/json');
         res.statusCode = 200;
         res.end(JSON.stringify({
           success: true,
-          message: `Baseline accepted for ${name}`
+          message: `Baseline accepted for comparison ${id}`
         }));
       } catch (error) {
         logger.error('Error accepting baseline:', error);
@@ -368,19 +368,19 @@ export const createHttpServer = (port, screenshotHandler) => {
       try {
         const body = await parseRequestBody(req);
         const {
-          name
+          id
         } = body;
-        if (!name) {
+        if (!id) {
           res.statusCode = 400;
           res.end(JSON.stringify({
-            error: 'screenshot name is required'
+            error: 'comparison ID is required'
           }));
           return;
         }
 
         // Call the screenshot handler's accept baseline method if it exists
         if (screenshotHandler.acceptBaseline) {
-          const result = await screenshotHandler.acceptBaseline(name);
+          const result = await screenshotHandler.acceptBaseline(id);
           res.statusCode = 200;
           res.end(JSON.stringify({
             success: true,