@vizzly-testing/cli 0.35.3-beta.3 → 0.36.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
   });
 }
 

package/dist/types/client.d.ts

@@ -33,6 +33,8 @@ export function autoDiscoverTddServer(
  */
 export interface ScreenshotResult {
   success: boolean;
+  /** Cloud capture accepted locally; upload completion is reported by flush. */
+  queued?: boolean;
   status?:
     | 'passed'
     | 'failed'
@@ -67,16 +69,17 @@ export interface ScreenshotResult {
  * @example
  * // With properties and comparison settings
  * await vizzlyScreenshot('checkout-form', screenshot, {
- *   properties: { browser: 'chrome', viewport: { width: 1920, height: 1080 } },
+ *   properties: { browser: 'chrome', theme: 'dark', locale: 'en-US' },
  *   threshold: 5,
  *   minClusterSize: 10,
  *   fullPage: true,
  *   requestTimeout: 5000
  * });
  *
- * `properties` is the user metadata bag. Comparison options are normalized
- * into the server metadata payload, while `requestTimeout` stays on the
- * client request and `buildId` only routes the screenshot to a build.
+ * `properties` is the user metadata bag and every key is preserved. Vizzly
+ * reads width and height from the captured image. Comparison options are sent
+ * separately, while `requestTimeout` stays on the client request and `buildId`
+ * only routes the screenshot to a build.
  */
 export function vizzlyScreenshot(
   name: string,
@@ -94,11 +97,15 @@ export function vizzlyScreenshot(
 ): Promise<ScreenshotResult | null>;
 
 /**
- * Flush result summary returned by vizzlyFlush
+ * Results returned by vizzlyFlush. Cloud counts cover the whole run, including
+ * earlier flushes; success is false if any capture failed. Uploaded and reused
+ * counts are separate. TDD mode reports local comparison results instead.
  */
 export interface FlushResult {
   success: boolean;
   uploaded?: number;
+  reused?: number;
+  failures?: Array<{ name: string; error: string }>;
   flushed?: boolean;
   total?: number;
   passed?: number;

package/dist/types/index.d.ts

@@ -401,7 +401,11 @@ export interface TddService {
   compareScreenshot(
     name: string,
     imageBuffer: Buffer,
-    properties?: Record<string, unknown>
+    properties?: Record<string, unknown>,
+    screenshotOptions?: Pick<
+      ScreenshotOptions,
+      'threshold' | 'minClusterSize' | 'fullPage'
+    >
   ): Promise<ComparisonResult>;
 
   getResults(): TddResults;

package/dist/uploader/core.js

@@ -200,12 +200,13 @@ export function buildFileMetadata(filePath, buffer) {
  * @returns {Object} Screenshot format for SHA check
  */
 export function fileToScreenshotFormat(file) {
+  let browser = extractBrowserFromFilename(file.filename);
   return {
     sha256: file.sha256,
     name: file.filename.replace(/\.png$/, ''),
-    browser: extractBrowserFromFilename(file.filename) || 'chrome',
-    viewport_width: 1920,
-    viewport_height: 1080
+    properties: browser ? {
+      browser
+    } : {}
   };
 }
 

package/dist/utils/screenshot-options.js

@@ -1,35 +1,10 @@
-/**
- * Screenshot option names that are part of the SDK/config contract, not the
- * user's arbitrary metadata bag.
- */
-export let RESERVED_PROPERTY_OPTIONS = Object.freeze({
-  threshold: {
-    message: 'Move "threshold" out of properties; properties is only for user metadata.'
-  },
-  minClusterSize: {
-    message: 'Move "minClusterSize" out of properties; properties is only for user metadata.'
-  },
-  fullPage: {
-    message: 'Move "fullPage" out of properties; properties is only for user metadata.'
-  },
-  buildId: {
-    message: 'Move "buildId" out of properties; properties is only for user metadata.'
-  },
-  requestTimeout: {
-    message: 'Move "requestTimeout" out of properties; properties is only for user metadata.'
-  }
-});
-function createReservedPropertyWarning(option) {
-  return {
-    code: 'reserved-property-option',
-    option,
-    message: RESERVED_PROPERTY_OPTIONS[option].message
-  };
+export let SCREENSHOT_OPTION_NAMES = Object.freeze(['threshold', 'minClusterSize', 'fullPage', 'captureMode', 'deviceScaleFactor', 'selector']);
+export function getScreenshotOptionsPayload(options = {}) {
+  return Object.fromEntries(SCREENSHOT_OPTION_NAMES.filter(option => options[option] !== undefined).map(option => [option, options[option]]));
 }
 
 /**
- * Normalize screenshot SDK options into the properties payload consumed by the
- * local TDD server and cloud-compatible comparison path.
+ * Keep user properties separate from the Vizzly options sent beside them.
  */
 export function normalizeScreenshotOptions(options = {}) {
   let {
@@ -38,40 +13,24 @@ export function normalizeScreenshotOptions(options = {}) {
     requestTimeout,
     threshold,
     minClusterSize,
-    fullPage
+    fullPage,
+    captureMode,
+    deviceScaleFactor,
+    selector
   } = options;
-  let warnings = [];
-  let normalizedProperties = {};
-  for (let [key, value] of Object.entries(properties || {})) {
-    if (RESERVED_PROPERTY_OPTIONS[key]) {
-      warnings.push(createReservedPropertyWarning(key));
-      if (key === 'threshold' && threshold === undefined) threshold = value;
-      if (key === 'minClusterSize' && minClusterSize === undefined) {
-        minClusterSize = value;
-      }
-      if (key === 'fullPage' && fullPage === undefined) fullPage = value;
-      if (key === 'buildId' && buildId === undefined) buildId = value;
-      if (key === 'requestTimeout' && requestTimeout === undefined) {
-        requestTimeout = value;
-      }
-      continue;
-    }
-    normalizedProperties[key] = value;
-  }
-  if (threshold !== undefined) {
-    normalizedProperties.threshold = threshold;
-  }
-  if (minClusterSize !== undefined) {
-    normalizedProperties.minClusterSize = minClusterSize;
-  }
-  if (fullPage !== undefined) {
-    normalizedProperties.fullPage = fullPage;
-  }
+  let sourceProperties = properties && typeof properties === 'object' && !Array.isArray(properties) ? properties : {};
   return {
     buildId,
     requestTimeout,
-    properties: normalizedProperties,
-    warnings
+    threshold,
+    minClusterSize,
+    fullPage,
+    captureMode,
+    deviceScaleFactor,
+    selector,
+    properties: {
+      ...sourceProperties
+    }
   };
 }
 export function createScreenshotProperties(options = {}) {

package/dist/utils/security.js

@@ -166,55 +166,40 @@ export function safePath(workingDir, ...pathSegments) {
 }
 
 /**
- * Validates screenshot properties object for safe values
- * @param {Object} properties - Properties to validate
- * @returns {Object} Validated properties object
+ * Validate user metadata without interpreting names as Vizzly options or
+ * rewriting values. Rendering code must escape strings for its output context.
+ * Reject unsafe object keys and values that cannot be represented as JSON.
+ *
+ * @param {Object} [properties={}] - User screenshot metadata.
+ * @returns {Object} A copy preserving the supplied JSON values.
+ * @throws {Error} Metadata contains unsafe keys, cycles, or non-JSON values.
  */
 export function validateScreenshotProperties(properties = {}) {
-  if (properties === null || typeof properties !== 'object') {
+  if (!properties || typeof properties !== 'object' || Array.isArray(properties)) {
     return {};
   }
-  const validated = {};
-
-  // Validate common properties with safe constraints
-  if (properties.browser && typeof properties.browser === 'string') {
-    try {
-      // Extract browser name without version (e.g., "Chrome/139.0.7258.138" -> "Chrome")
-      const browserName = properties.browser.split('/')[0];
-      validated.browser = sanitizeScreenshotName(browserName, 50);
-    } catch (error) {
-      // Skip invalid browser names, don't include them
-      output.warn(`Invalid browser name '${properties.browser}': ${error.message}`);
-    }
-  }
-  if (properties.viewport && typeof properties.viewport === 'object') {
-    const viewport = {};
-    if (typeof properties.viewport.width === 'number' && properties.viewport.width > 0 && properties.viewport.width <= 10000) {
-      viewport.width = Math.floor(properties.viewport.width);
-    }
-    if (typeof properties.viewport.height === 'number' && properties.viewport.height > 0 && properties.viewport.height <= 10000) {
-      viewport.height = Math.floor(properties.viewport.height);
+  let ancestors = new Set();
+  function copy(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean') {
+      return value;
     }
-    if (Object.keys(viewport).length > 0) {
-      validated.viewport = viewport;
+    if (typeof value === 'number' && Number.isFinite(value)) return value;
+    if (typeof value !== 'object' || ancestors.has(value)) {
+      throw new Error('Screenshot properties must contain JSON values');
     }
-  }
-
-  // Allow other safe string properties but sanitize them
-  for (const [key, value] of Object.entries(properties)) {
-    if (key === 'browser' || key === 'viewport') continue; // Already handled
-
-    if (typeof key === 'string' && key.length <= 50 && /^[a-zA-Z0-9_-]+$/.test(key)) {
-      if (typeof value === 'string' && value.length <= 200) {
-        // Preserve safe URL/query characters like '&' in metadata values.
-        // Rendering layers should escape for HTML instead of mutating payload data here.
-        validated[key] = value.replace(/[<>"']/g, '');
-      } else if (typeof value === 'number' && !Number.isNaN(value) && Number.isFinite(value)) {
-        validated[key] = value;
-      } else if (typeof value === 'boolean') {
-        validated[key] = value;
+    ancestors.add(value);
+    let result;
+    if (Array.isArray(value)) {
+      result = value.map(copy);
+    } else {
+      let entries = Object.entries(value);
+      if (entries.some(([key]) => ['__proto__', 'constructor', 'prototype'].includes(key))) {
+        throw new Error('Screenshot properties contain an unsafe key');
       }
+      result = Object.fromEntries(entries.map(([key, item]) => [key, copy(item)]));
     }
+    ancestors.delete(value);
+    return result;
   }
-  return validated;
+  return copy(properties);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.35.3-beta.3",
+  "version": "0.36.0",
   "description": "Visual regression testing from your terminal",
   "keywords": [
     "llm-context",