@vizzly-testing/cli 0.35.3-beta.4 → 0.37.0

package/dist/sdk/index.js

@@ -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';
@@ -315,10 +309,6 @@ export class VizzlySDK extends EventEmitter {
       properties: normalizedOptions.properties
     };
     Object.assign(screenshotData, getScreenshotOptionsPayload(normalizedOptions));
-    if (normalizedOptions.warnings.length > 0) {
-      screenshotData.warnings = normalizedOptions.warnings;
-    }
-
     // 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,5 +1,5 @@
 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';
@@ -7,49 +7,56 @@ 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 = [], screenshotOptions = {}) => {
-    let handlerStart = Date.now();
+  function recordFailure(capture, error) {
+    capture.status = 'failed';
+    capture.error = error.message;
+    output.warn(`Screenshot "${capture.name}" failed to upload: ${error.message}`);
+  }
+
+  /**
+   * 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);
+    }
+  }
+
+  /**
+   * 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
@@ -64,187 +71,90 @@ export const createApiHandler = (client, {
       deviceScaleFactor: normalizedOptions.deviceScaleFactor,
       selector: normalizedOptions.selector
     };
-    warnings = [...(warnings || []), ...normalizedOptions.warnings];
-    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
-
-    if (!client) {
-      return {
-        statusCode: 500,
-        body: {
-          error: 'API client not available'
-        }
-      };
-    }
-
-    // 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
+    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 ?? {}, false, screenshotOptions).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

@@ -5,41 +5,19 @@ import { getDimensionsSync as defaultGetDimensionsSync } from '@vizzly-testing/h
 import { TddService as DefaultTddService } from '../../tdd/tdd-service.js';
 import { detectImageInputType as defaultDetectImageInputType } from '../../utils/image-input-detector.js';
 import * as defaultOutput from '../../utils/output.js';
-import { normalizeScreenshotOptions } from '../../utils/screenshot-options.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
   };
 };
@@ -325,18 +303,10 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
       };
     }
 
-    // Preserve the old nested wrapper for older clients, then filter user
-    // properties before local comparison/report serialization.
-    let unwrappedProperties = unwrapProperties(properties);
-    let normalizedProperties = normalizeScreenshotOptions({
-      properties: unwrappedProperties
-    });
-    warnings = [...(warnings || []), ...normalizedProperties.warnings];
-
-    // Validate and sanitize properties
+    // Validate user metadata without unwrapping nested keys.
     let validatedProperties;
     try {
-      validatedProperties = validateScreenshotProperties(normalizedProperties.properties);
+      validatedProperties = validateScreenshotProperties(properties);
     } catch (error) {
       return {
         statusCode: 400,
@@ -348,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)
@@ -407,21 +374,13 @@ 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)

package/dist/server/routers/screenshot.js

@@ -9,7 +9,10 @@ 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
@@ -58,7 +61,7 @@ export function createScreenshotRouter({
           deviceScaleFactor,
           selector
         });
-        const result = await screenshotHandler.handleScreenshot(effectiveBuildId, name, image, normalizedOptions.properties, type, [...(warnings || []), ...normalizedOptions.warnings], {
+        const result = await screenshotHandler.handleScreenshot(effectiveBuildId, name, image, normalizedOptions.properties, type, warnings || [], {
           threshold: normalizedOptions.threshold,
           minClusterSize: normalizedOptions.minClusterSize,
           fullPage: normalizedOptions.fullPage,
@@ -84,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/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
   };

package/dist/test-runner/operations.js

@@ -102,7 +102,10 @@ export async function fetchBuildUrl({
 }
 
 /**
- * Finalize a build
+ * Flush captures before saving the build's final status.
+ * Cloud builds fail when tests or uploads fail. Finalization errors are reported
+ * without replacing the test result; collected upload counts are still returned.
+ *
  * @param {Object} options - Options
  * @param {string} options.buildId - Build ID
  * @param {boolean} options.tdd - Whether in TDD mode
@@ -115,6 +118,8 @@ export async function fetchBuildUrl({
  * @param {Function} options.deps.finalizeApiBuild - API finalize function
  * @param {Object} options.deps.output - Output utilities
  * @param {Function} [options.deps.onFinalizeFailed] - Callback for finalize failure
+ * @returns {Promise<Object|null|undefined>} Cumulative cloud upload results when
+ * available; no upload results for local TDD or a run without a build.
  */
 export async function finalizeBuild({
   buildId,
@@ -134,6 +139,7 @@ export async function finalizeBuild({
   if (!buildId) {
     return;
   }
+  let uploadStats = null;
   try {
     if (tdd) {
       // TDD mode: use server handler to finalize (local-only)
@@ -146,16 +152,18 @@ export async function finalizeBuild({
     } else {
       // API mode: flush uploads first, then finalize build
       if (serverManager.server?.finishBuild) {
-        await serverManager.server.finishBuild(buildId);
+        uploadStats = await serverManager.server.finishBuild(buildId);
       }
 
       // Then update build status via API
       let clientOptions = buildClientOptions(config);
       if (clientOptions) {
         let client = createApiClient(clientOptions);
-        await finalizeApiBuild(client, buildId, success, executionTime);
+        let uploadsFailed = uploadStats?.failed > 0;
+        let buildSucceeded = success && !uploadsFailed;
+        await finalizeApiBuild(client, buildId, buildSucceeded, executionTime, uploadsFailed ? `${uploadStats.failed} screenshot(s) failed to upload. Visual testing is incomplete.` : undefined);
         output.debug('build', 'finalized via api', {
-          success
+          success: buildSucceeded
         });
       } else {
         output.warn(`No API service available to finalize build ${buildId}`);
@@ -172,6 +180,7 @@ export async function finalizeBuild({
       });
     }
   }
+  return uploadStats;
 }
 
 // ============================================================================
@@ -261,7 +270,10 @@ async function executeDisabledTestRun({
  * @param {Object} options.runOptions - Run options (testCommand, tdd, etc.)
  * @param {Object} options.config - Configuration object
  * @param {Object} options.deps - Dependencies
- * @returns {Promise<Object>} Run result
+ * @returns {Promise<Object>} Test result with cumulative cloud upload results
+ * when available. Upload failures alone do not reject the run.
+ * @throws {Error} Test execution failure, with upload results attached when
+ * available so callers can report both without losing the test exit code.
  */
 export async function runTests({
   runOptions,
@@ -315,6 +327,7 @@ export async function runTests({
   let screenshotCount = 0;
   let testSuccess = false;
   let testError = null;
+  let uploadStats = null;
   let setBaseline;
   try {
     buildId = await createBuild({
@@ -425,7 +438,7 @@ export async function runTests({
     let executionTime = Date.now() - startTime;
     if (buildId) {
       try {
-        await finalizeBuild({
+        uploadStats = await finalizeBuild({
           buildId,
           tdd,
           success: testSuccess,
@@ -467,6 +480,7 @@ export async function runTests({
     if (!runOptions.json) {
       output.error('Test run failed:', testError);
     }
+    if (uploadStats) testError.uploads = uploadStats;
     throw testError;
   }
   return buildRunResult({
@@ -474,7 +488,8 @@ export async function runTests({
     buildUrl,
     testSuccess,
     screenshotCount,
-    tddResults
+    tddResults,
+    uploadStats
   });
 }