@vizzly-testing/cli 0.35.3-beta.3 → 0.36.0

package/dist/screenshot-server/core.js

@@ -4,6 +4,8 @@
  * No I/O, no side effects - just data transformations.
  */
 
+import { getScreenshotOptionsPayload } from '../utils/screenshot-options.js';
+
 // ============================================================================
 // Request Validation
 // ============================================================================
@@ -149,9 +151,11 @@ export function buildServerStoppedMessage() {
  * @returns {{ name: string, image: string, properties?: Object }}
  */
 export function extractScreenshotData(body) {
-  return {
+  let screenshotData = {
     name: body.name,
     image: body.image,
     properties: body.properties
   };
+  Object.assign(screenshotData, getScreenshotOptionsPayload(body));
+  return screenshotData;
 }

package/dist/sdk/index.js

@@ -19,7 +19,7 @@ import { createUploader } from '../uploader/index.js';
 import { loadConfig } from '../utils/config-loader.js';
 import { resolveImageBuffer } from '../utils/file-helpers.js';
 import * as output from '../utils/output.js';
-import { normalizeScreenshotOptions } from '../utils/screenshot-options.js';
+import { getScreenshotOptionsPayload, normalizeScreenshotOptions } from '../utils/screenshot-options.js';
 
 /**
  * Create a new Vizzly instance with custom configuration
@@ -294,12 +294,6 @@ export class VizzlySDK extends EventEmitter {
     // Resolve Buffer or file path using shared utility
     let buffer = resolveImageBuffer(imageBuffer, 'screenshot');
     let normalizedOptions = normalizeScreenshotOptions(options);
-    for (let warning of normalizedOptions.warnings) {
-      output.warn(warning.message, {
-        code: warning.code,
-        option: warning.option
-      });
-    }
 
     // Generate or use provided build ID
     let buildId = normalizedOptions.buildId || this.currentBuildId || 'default';
@@ -314,10 +308,7 @@ export class VizzlySDK extends EventEmitter {
       type: 'base64',
       properties: normalizedOptions.properties
     };
-    if (normalizedOptions.warnings.length > 0) {
-      screenshotData.warnings = normalizedOptions.warnings;
-    }
-
+    Object.assign(screenshotData, getScreenshotOptionsPayload(normalizedOptions));
     // POST to the local screenshot server
     let serverUrl = `http://localhost:${this.config.server?.port || 3000}`;
     let fetchFn = this.services.fetch || fetch;

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

@@ -1,234 +1,160 @@
 import { Buffer } from 'node:buffer';
-import { existsSync, readFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { uploadScreenshot as defaultUploadScreenshot } from '../../api/index.js';
 import { detectImageInputType } from '../../utils/image-input-detector.js';
 import * as output from '../../utils/output.js';
+import { normalizeScreenshotOptions } from '../../utils/screenshot-options.js';
 
 /**
- * API Handler - Non-blocking screenshot upload
+ * Create a cloud screenshot handler for one run.
  *
- * Flow:
- * ┌─────────────────────────────────────────────────────────────┐
- * │ Test Suite                                                  │
- * │   ↓ vizzlyScreenshot()                                      │
- * │   ↓ HTTP POST to localhost                                 │
- * │   ↓                                                         │
- * │ Screenshot Server                                           │
- * │   ↓ handleScreenshot()                                      │
- * │   ├─→ Convert base64 to Buffer                             │
- * │   ├─→ Fire upload promise (NO AWAIT) ─────┐                │
- * │   └─→ Return 200 immediately              │                │
- * │                                             │                │
- * │ Test continues (NO BLOCKING) ✓             │                │
- * │                                             ↓                │
- * │                                   Background Upload         │
- * │                                   (to Vizzly API)           │
- * │                                             ↓                │
- * │                                   Promise resolves/rejects  │
- * │                                                             │
- * │ Build Finalization                                          │
- * │   ↓ flush()                                                 │
- * │   └─→ await Promise.allSettled(uploadPromises)             │
- * │        ↓                                                    │
- * │      All uploads complete ✓                                │
- * └─────────────────────────────────────────────────────────────┘
- */
-
-/**
- * Create an API handler for screenshot uploads.
- * @param {Object} client - API client with request method
- * @param {Object} options - Optional dependencies for testing
- * @param {Function} options.uploadScreenshot - Upload function (defaults to API uploadScreenshot)
+ * Captures queue uploads without waiting for the API. Each capture keeps its
+ * outcome so a rejection cannot disable later uploads or disappear after flush.
+ * Flush pending uploads before cleanup, which clears the run's records.
+ *
+ * @param {Object} client - API client used to upload screenshots.
+ * @param {Object} [options] - Upload dependencies.
+ * @param {typeof defaultUploadScreenshot} [options.uploadScreenshot] - Uploader.
+ * @returns {Object} Capture, count, flush, and cleanup methods for this run.
  */
-export const createApiHandler = (client, {
+export let createApiHandler = (client, {
   uploadScreenshot = defaultUploadScreenshot
 } = {}) => {
-  let vizzlyDisabled = false;
-  let screenshotCount = 0;
+  let captures = [];
   let uploadPromises = [];
-  const handleScreenshot = async (buildId, name, image, properties = {}, type, warnings = []) => {
-    let handlerStart = Date.now();
-    output.debug('upload', `${name} received`, {
-      buildId: buildId?.slice(0, 8)
-    });
-    if (vizzlyDisabled) {
-      output.debug('upload', `${name} (disabled)`);
-      return {
-        statusCode: 200,
-        body: {
-          success: true,
-          disabled: true,
-          count: ++screenshotCount,
-          message: `Vizzly disabled - ${screenshotCount} screenshots captured but not uploaded`
-        }
-      };
-    }
-
-    // buildId is optional - API will handle it appropriately
+  function recordFailure(capture, error) {
+    capture.status = 'failed';
+    capture.error = error.message;
+    output.warn(`Screenshot "${capture.name}" failed to upload: ${error.message}`);
+  }
 
-    if (!client) {
-      return {
-        statusCode: 500,
-        body: {
-          error: 'API client not available'
-        }
-      };
+  /**
+   * Upload one capture and record its outcome, including SHA reuse.
+   * API failures are recorded and logged rather than rejecting the background
+   * promise, so flush can collect every outcome and later uploads can continue.
+   */
+  async function upload(capture, buildId, imageBuffer, properties, screenshotOptions) {
+    try {
+      let result = await uploadScreenshot(client, buildId, capture.name, imageBuffer, properties ?? {}, false, screenshotOptions);
+      capture.status = result.skipped ? 'reused' : 'uploaded';
+    } catch (error) {
+      recordFailure(capture, error);
     }
+  }
 
-    // Support both base64 encoded images and file paths
-    // Use explicit type from client if provided (fast path), otherwise detect (slow path)
-    // Only accept valid type values to prevent invalid types from bypassing detection
+  /**
+   * Read a capture and queue its cloud upload. Local input failures are included
+   * in the run's failed count; HTTP 200 means queued, not uploaded successfully.
+   *
+   * @param {string} buildId - Cloud build receiving the screenshot.
+   * @param {string} name - Stable screenshot name used for baseline matching.
+   * @param {string} image - Base64 image data or a file path.
+   * @param {Object} [properties={}] - Screenshot metadata.
+   * @param {string} [type] - Base64 or file-path hint; otherwise detected.
+   * @param {Object[]} [warnings=[]] - Warnings already collected by the router.
+   * @param {Object} [screenshotOptions={}] - Capture and comparison options.
+   * @returns {Promise<{statusCode: number, body: Object}>} Local HTTP response.
+   */
+  async function handleScreenshot(buildId, name, image, properties = {}, type, warnings = [], screenshotOptions = {}) {
+    let normalizedOptions = normalizeScreenshotOptions({
+      ...screenshotOptions,
+      properties
+    });
+    properties = normalizedOptions.properties;
+    screenshotOptions = {
+      ...screenshotOptions,
+      threshold: normalizedOptions.threshold,
+      minClusterSize: normalizedOptions.minClusterSize,
+      fullPage: normalizedOptions.fullPage,
+      captureMode: normalizedOptions.captureMode,
+      deviceScaleFactor: normalizedOptions.deviceScaleFactor,
+      selector: normalizedOptions.selector
+    };
+    warnings = warnings || [];
+    let capture = {
+      name,
+      status: 'pending'
+    };
+    captures.push(capture);
+    let inputType = ['base64', 'file-path'].includes(type) ? type : detectImageInputType(image);
     let imageBuffer;
-    let validTypes = ['base64', 'file-path'];
-    const inputType = type && validTypes.includes(type) ? type : 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);
-      } catch (error) {
-        return {
-          statusCode: 500,
-          body: {
-            error: `Failed to read screenshot file: ${error.message}`,
-            filePath
-          }
-        };
-      }
-    } else if (inputType === 'base64') {
-      // It's base64 encoded
-      try {
+    try {
+      if (!client) throw new Error('API client not available');
+      if (inputType === 'file-path') {
+        let filePath = resolve(image.replace('file://', ''));
+        try {
+          imageBuffer = readFileSync(filePath);
+        } catch (error) {
+          throw new Error(error.code === 'ENOENT' ? `Screenshot file not found: ${filePath}` : `Failed to read screenshot file: ${error.message}`);
+        }
+      } else if (inputType === 'base64') {
         imageBuffer = Buffer.from(image, 'base64');
-      } catch (error) {
-        return {
-          statusCode: 400,
-          body: {
-            error: `Invalid base64 image data: ${error.message}`
-          }
-        };
+      } else {
+        throw new Error('Invalid image input: must be a file path or base64 encoded image data');
       }
-    } else {
-      // Unknown input type
+    } catch (error) {
+      recordFailure(capture, error);
       return {
-        statusCode: 400,
+        statusCode: client ? 400 : 500,
         body: {
-          error: 'Invalid image input: must be a file path or base64 encoded image data',
-          receivedType: typeof image
+          success: false,
+          name,
+          error: error.message
         }
       };
     }
-    screenshotCount++;
-    let uploadStart = Date.now();
-
-    // Fire upload in background - DON'T AWAIT!
-    let uploadPromise = uploadScreenshot(client, buildId, name, imageBuffer, properties ?? {}).then(result => {
-      let duration = Date.now() - uploadStart;
-      if (!result.skipped) {
-        output.debug('upload', `${name} completed`, {
-          ms: duration
-        });
-      } else {
-        output.debug('upload', `${name} skipped (dedup)`, {
-          ms: duration
-        });
-      }
-      return {
-        success: true,
-        name,
-        result,
-        duration
-      };
-    }).catch(uploadError => {
-      let duration = Date.now() - uploadStart;
-      output.debug('upload', `${name} failed`, {
-        error: uploadError.message,
-        ms: duration
-      });
-      vizzlyDisabled = true;
-      output.warn('Vizzly disabled due to upload error - continuing tests without visual testing');
-      return {
-        success: false,
-        name,
-        error: uploadError,
-        duration
-      };
-    });
-
-    // Collect promise for later flushing
-    uploadPromises.push(uploadPromise);
-
-    // Return immediately - test continues without waiting!
-    let handlerMs = Date.now() - handlerStart;
-    output.debug('upload', `${name} handler returning`, {
-      ms: handlerMs
-    });
+    uploadPromises.push(upload(capture, buildId, imageBuffer, properties, screenshotOptions));
     return {
       statusCode: 200,
       body: {
         success: true,
+        queued: true,
         name,
-        count: screenshotCount,
+        count: captures.length,
         warnings
       }
     };
-  };
-  const getScreenshotCount = () => screenshotCount;
+  }
 
   /**
-   * Wait for all background uploads to complete
-   * Call this before build finalization to ensure all uploads finish
+   * Wait for pending uploads, including captures queued while waiting.
+   * Results cover the whole run and remain available across repeated flushes.
+   * Uploaded and reused counts are separate; failed includes local input errors.
+   *
+   * @returns {Promise<Object>} Uploaded, reused, failed, and total counts, plus
+   * failed captures as `failures: [{ name, error }]`.
    */
-  const flush = async () => {
-    if (uploadPromises.length === 0) {
-      return {
-        uploaded: 0,
-        failed: 0,
-        total: 0
-      };
-    }
-    output.debug('upload', `flushing ${uploadPromises.length} uploads`);
-    const results = await Promise.allSettled(uploadPromises);
-    let uploaded = 0;
-    let failed = 0;
-    results.forEach(result => {
-      if (result.status === 'fulfilled' && result.value.success) {
-        uploaded++;
-      } else {
-        failed++;
-      }
-    });
-    output.debug('upload', 'flush complete', {
-      uploaded,
-      failed
-    });
-
-    // Clear promises array
-    uploadPromises = [];
+  async function flush() {
+    let count;
+    do {
+      count = uploadPromises.length;
+      await Promise.all(uploadPromises);
+    } while (count !== uploadPromises.length);
+    let uploaded = captures.filter(capture => capture.status === 'uploaded').length;
+    let reused = captures.filter(capture => capture.status === 'reused').length;
+    let failures = captures.filter(capture => capture.status === 'failed').map(({
+      name,
+      error
+    }) => ({
+      name,
+      error
+    }));
     return {
       uploaded,
-      failed,
-      total: results.length
+      reused,
+      failed: failures.length,
+      total: captures.length,
+      failures
     };
-  };
-  const cleanup = () => {
-    vizzlyDisabled = false;
-    screenshotCount = 0;
+  }
+  function cleanup() {
+    captures = [];
     uploadPromises = [];
-    // Silent cleanup
-  };
+  }
   return {
     handleScreenshot,
-    getScreenshotCount,
+    getScreenshotCount: () => captures.length,
     flush,
     cleanup
   };

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

@@ -8,37 +8,16 @@ import * as defaultOutput from '../../utils/output.js';
 import { safePath as defaultSafePath, sanitizeScreenshotName as defaultSanitizeScreenshotName, validateScreenshotProperties as defaultValidateScreenshotProperties } from '../../utils/security.js';
 
 /**
- * Unwrap double-nested properties if needed
- * Client SDK wraps options in properties field, so we may get { properties: { properties: {...} } }
+ * Build the flat internal comparison shape. Width and height always come from
+ * the captured image. The untouched user bag remains available in metadata.
  */
-export const unwrapProperties = properties => {
-  if (!properties) return {};
-  if (properties.properties && typeof properties.properties === 'object') {
-    // Merge top-level properties with nested properties
-    let unwrapped = {
-      ...properties,
-      ...properties.properties
-    };
-    // Remove the nested properties field to avoid confusion
-    delete unwrapped.properties;
-    return unwrapped;
-  }
-  return properties;
-};
-
-/**
- * Extract properties to top-level format matching cloud API
- * Normalizes viewport to viewport_width/height, ensures browser is set
- */
-export const extractProperties = validatedProperties => {
+export const extractProperties = (validatedProperties, imageDimensions = {}) => {
   if (!validatedProperties) return {};
   return {
     ...validatedProperties,
-    // Normalize viewport to top-level viewport_width/height (cloud format)
-    viewport_width: validatedProperties.viewport?.width ?? validatedProperties.viewport_width ?? null,
-    viewport_height: validatedProperties.viewport?.height ?? validatedProperties.viewport_height ?? null,
+    viewport_width: imageDimensions.width ?? null,
+    viewport_height: imageDimensions.height ?? null,
     browser: validatedProperties.browser ?? null,
-    // Preserve nested structure in metadata for backward compatibility
     metadata: validatedProperties
   };
 };
@@ -305,7 +284,7 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
       output.debug('tdd', `baseline: ${baseline.buildName}`);
     }
   };
-  const handleScreenshot = async (_buildId, name, image, properties = {}, type, warnings = []) => {
+  const handleScreenshot = async (_buildId, name, image, properties = {}, type, warnings = [], screenshotOptions = {}) => {
     let handlerStart = Date.now();
     output.debug('tdd', `${name} received`);
 
@@ -324,13 +303,10 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
       };
     }
 
-    // Unwrap double-nested properties if needed (client SDK wraps options in properties field)
-    let unwrappedProperties = unwrapProperties(properties);
-
-    // Validate and sanitize properties
+    // Validate user metadata without unwrapping nested keys.
     let validatedProperties;
     try {
-      validatedProperties = validateScreenshotProperties(unwrappedProperties);
+      validatedProperties = validateScreenshotProperties(properties);
     } catch (error) {
       return {
         statusCode: 400,
@@ -342,9 +318,6 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
       };
     }
 
-    // Extract ALL properties to top-level (matching cloud API behavior)
-    const extractedProperties = extractProperties(validatedProperties);
-
     // Support both base64 encoded images and file paths
     // Vitest browser mode returns file paths, so we need to handle both
     // Use explicit type from client if provided (fast path), otherwise detect (slow path)
@@ -401,25 +374,17 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
         }
       };
     }
-
-    // Auto-detect image dimensions if viewport not provided
-    if (!extractedProperties.viewport_width || !extractedProperties.viewport_height) {
-      try {
-        const dimensions = getDimensionsSync(imageBuffer);
-        if (!extractedProperties.viewport_width) {
-          extractedProperties.viewport_width = dimensions.width;
-        }
-        if (!extractedProperties.viewport_height) {
-          extractedProperties.viewport_height = dimensions.height;
-        }
-      } catch {
-        // Dimensions will use defaults
-      }
+    let imageDimensions = {};
+    try {
+      imageDimensions = getDimensionsSync(imageBuffer);
+    } catch {
+      // Invalid images are handled by the comparison service.
     }
+    let extractedProperties = extractProperties(validatedProperties, imageDimensions);
 
     // 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, extractedProperties);
+    const comparison = await tddService.compareScreenshot(sanitizedName, imageBuffer, extractedProperties, screenshotOptions);
 
     // Comparison tracked by tdd.js event handler
 

package/dist/server/routers/screenshot.js

@@ -4,11 +4,15 @@
  */
 
 import * as output from '../../utils/output.js';
+import { normalizeScreenshotOptions } from '../../utils/screenshot-options.js';
 import { parseJsonBody } from '../middleware/json-parser.js';
 import { sendError, sendJson } from '../middleware/response.js';
 
 /**
- * Create screenshot router
+ * Route local capture and flush requests to the active cloud or TDD handler.
+ * A cloud flush returns HTTP 200 with cumulative results; its success field is
+ * false when any capture failed, even if that failure appeared in an earlier flush.
+ *
  * @param {Object} context - Router context
  * @param {Object} context.screenshotHandler - Screenshot handler
  * @param {string|null} context.defaultBuildId - Default build ID
@@ -33,7 +37,13 @@ export function createScreenshotRouter({
           properties,
           image,
           type,
-          warnings
+          warnings,
+          threshold,
+          minClusterSize,
+          fullPage,
+          captureMode,
+          deviceScaleFactor,
+          selector
         } = body;
         if (!name || !image) {
           sendError(res, 400, 'name and image are required');
@@ -42,7 +52,23 @@ export function createScreenshotRouter({
 
         // Use buildId from request body, or fall back to server's buildId
         const effectiveBuildId = buildId || defaultBuildId;
-        const result = await screenshotHandler.handleScreenshot(effectiveBuildId, name, image, properties, type, warnings);
+        const normalizedOptions = normalizeScreenshotOptions({
+          properties,
+          threshold,
+          minClusterSize,
+          fullPage,
+          captureMode,
+          deviceScaleFactor,
+          selector
+        });
+        const result = await screenshotHandler.handleScreenshot(effectiveBuildId, name, image, normalizedOptions.properties, type, warnings || [], {
+          threshold: normalizedOptions.threshold,
+          minClusterSize: normalizedOptions.minClusterSize,
+          fullPage: normalizedOptions.fullPage,
+          captureMode: normalizedOptions.captureMode,
+          deviceScaleFactor: normalizedOptions.deviceScaleFactor,
+          selector: normalizedOptions.selector
+        });
         sendJson(res, result.statusCode, result.body);
         return true;
       } catch (error) {
@@ -61,7 +87,7 @@ export function createScreenshotRouter({
         if (screenshotHandler.flush) {
           let stats = await screenshotHandler.flush();
           sendJson(res, 200, {
-            success: true,
+            success: stats.failed === 0,
             ...stats
           });
         } else if (screenshotHandler.getResults) {

package/dist/tdd/tdd-service.js

@@ -752,7 +752,7 @@ export class TddService {
   /**
    * Compare a screenshot against baseline
    */
-  async compareScreenshot(name, imageBuffer, properties = {}) {
+  async compareScreenshot(name, imageBuffer, properties = {}, screenshotOptions = {}) {
     // Destructure dependencies
     let {
       output,
@@ -850,8 +850,8 @@ export class TddService {
     }
 
     // Baseline exists - compare
-    let effectiveThreshold = typeof validatedProperties.threshold === 'number' && validatedProperties.threshold >= 0 ? validatedProperties.threshold : this.threshold;
-    let effectiveMinClusterSize = Number.isInteger(validatedProperties.minClusterSize) && validatedProperties.minClusterSize >= 1 ? validatedProperties.minClusterSize : this.minClusterSize;
+    let effectiveThreshold = typeof screenshotOptions.threshold === 'number' && screenshotOptions.threshold >= 0 ? screenshotOptions.threshold : this.threshold;
+    let effectiveMinClusterSize = Number.isInteger(screenshotOptions.minClusterSize) && screenshotOptions.minClusterSize >= 1 ? screenshotOptions.minClusterSize : this.minClusterSize;
     try {
       let honeydiffResult = await compareImages(baselineImagePath, currentImagePath, diffImagePath, {
         threshold: effectiveThreshold,

package/dist/test-runner/core.js

@@ -133,6 +133,8 @@ export function buildDisabledRunResult() {
  * @param {boolean} options.testSuccess - Whether tests passed
  * @param {number} options.screenshotCount - Number of screenshots
  * @param {Object|null} options.tddResults - TDD results (comparisons, etc.)
+ * @param {Object|null} [options.uploadStats] - Cumulative cloud upload outcomes,
+ * exposed as `uploads` independently of test and local comparison results.
  * @returns {Object} Final result object
  */
 export function buildRunResult({
@@ -140,7 +142,8 @@ export function buildRunResult({
   buildUrl,
   testSuccess,
   screenshotCount,
-  tddResults
+  tddResults,
+  uploadStats
 }) {
   return {
     buildId,
@@ -148,6 +151,9 @@ export function buildRunResult({
     testsPassed: testSuccess ? 1 : 0,
     testsFailed: testSuccess ? 0 : 1,
     screenshotsCaptured: screenshotCount,
+    ...(uploadStats ? {
+      uploads: uploadStats
+    } : {}),
     comparisons: tddResults?.comparisons || null,
     failed: (tddResults?.failed || 0) > 0
   };