@vizzly-testing/cli 0.34.0 → 0.35.1

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 { createScreenshotProperties } from '../utils/screenshot-options.js';
+import { normalizeScreenshotOptions } from '../utils/screenshot-options.js';
 
 /**
  * Create a new Vizzly instance with custom configuration
@@ -293,9 +293,16 @@ 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 = options.buildId || this.currentBuildId || 'default';
+    let buildId = normalizedOptions.buildId || this.currentBuildId || 'default';
     this.currentBuildId = buildId;
 
     // Convert Buffer to base64 for JSON transport
@@ -305,8 +312,11 @@ export class VizzlySDK extends EventEmitter {
       name,
       image: imageBase64,
       type: 'base64',
-      properties: createScreenshotProperties(options)
+      properties: normalizedOptions.properties
     };
+    if (normalizedOptions.warnings.length > 0) {
+      screenshotData.warnings = normalizedOptions.warnings;
+    }
 
     // POST to the local screenshot server
     let serverUrl = `http://localhost:${this.config.server?.port || 3000}`;
@@ -362,12 +372,16 @@ export class VizzlySDK extends EventEmitter {
     let screenshotsDir = options.screenshotsDir || this.config?.upload?.screenshotsDir || './screenshots';
     let uploadOptions = {
       screenshotsDir,
-      buildName: options.buildName || this.config.buildName,
-      branch: options.branch || this.config.branch,
-      commit: options.commit || this.config.commit,
-      message: options.message || this.config.message,
-      environment: options.environment || this.config.environment || 'production',
-      threshold: options.threshold ?? this.config.threshold,
+      buildName: options.buildName || this.config.build?.name,
+      branch: options.branch || this.config.build?.branch,
+      commit: options.commit || this.config.build?.commit,
+      message: options.message || this.config.build?.message,
+      environment: options.environment || this.config.build?.environment || 'production',
+      threshold: options.threshold ?? this.config.comparison?.threshold,
+      minClusterSize: options.minClusterSize ?? this.config.comparison?.minClusterSize,
+      metadata: options.metadata || {},
+      pullRequestNumber: options.pullRequestNumber,
+      parallelId: options.parallelId || this.config.parallelId,
       onProgress: progress => {
         this.emit('upload:progress', progress);
         if (options.onProgress) {

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

@@ -47,7 +47,7 @@ export const createApiHandler = (client, {
   let vizzlyDisabled = false;
   let screenshotCount = 0;
   let uploadPromises = [];
-  const handleScreenshot = async (buildId, name, image, properties = {}, type) => {
+  const handleScreenshot = async (buildId, name, image, properties = {}, type, warnings = []) => {
     let handlerStart = Date.now();
     output.debug('upload', `${name} received`, {
       buildId: buildId?.slice(0, 8)
@@ -177,7 +177,8 @@ export const createApiHandler = (client, {
       body: {
         success: true,
         name,
-        count: screenshotCount
+        count: screenshotCount,
+        warnings
       }
     };
   };

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

@@ -305,7 +305,7 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
       output.debug('tdd', `baseline: ${baseline.buildName}`);
     }
   };
-  const handleScreenshot = async (_buildId, name, image, properties = {}, type) => {
+  const handleScreenshot = async (_buildId, name, image, properties = {}, type, warnings = []) => {
     let handlerStart = Date.now();
     output.debug('tdd', `${name} received`);
 
@@ -447,6 +447,7 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
       aaPercentage: comparison.aaPercentage,
       heightDiff: comparison.heightDiff,
       error: comparison.error,
+      warnings,
       originalName: name,
       timestamp: Date.now(),
       // Boolean hints so UI can show toggle buttons without fetching heavy data
@@ -490,6 +491,7 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
           diff: comparison.diff,
           diffPercentage: comparison.diffPercentage,
           threshold: comparison.threshold,
+          warnings,
           tddMode: true
         }
       };
@@ -503,6 +505,7 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
           message: `Baseline updated for '${name}'`,
           baseline: comparison.baseline,
           current: comparison.current,
+          warnings,
           tddMode: true
         }
       };
@@ -530,6 +533,7 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
         name: comparison.name,
         baseline: comparison.baseline,
         current: comparison.current,
+        warnings,
         tddMode: true
       }
     };

package/dist/server/routers/screenshot.js

@@ -32,7 +32,8 @@ export function createScreenshotRouter({
           name,
           properties,
           image,
-          type
+          type,
+          warnings
         } = body;
         if (!name || !image) {
           sendError(res, 400, 'name and image are required');
@@ -41,7 +42,7 @@ 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);
+        const result = await screenshotHandler.handleScreenshot(effectiveBuildId, name, image, properties, type, warnings);
         sendJson(res, result.statusCode, result.body);
         return true;
       } catch (error) {
@@ -57,9 +58,15 @@ export function createScreenshotRouter({
     // Flush endpoint - signals test completion and prints summary
     if (pathname === '/flush') {
       try {
-        if (screenshotHandler.getResults) {
+        if (screenshotHandler.flush) {
+          let stats = await screenshotHandler.flush();
+          sendJson(res, 200, {
+            success: true,
+            ...stats
+          });
+        } else if (screenshotHandler.getResults) {
           // This triggers printResults() which outputs the summary
-          const results = await screenshotHandler.getResults();
+          let results = await screenshotHandler.getResults();
           sendJson(res, 200, {
             success: true,
             summary: {

package/dist/services/build-manager.js

@@ -20,9 +20,12 @@ import { randomUUID } from 'node:crypto';
 export function createBuildObject(buildOptions, deps = {}) {
   let {
     name,
+    buildName,
     branch,
     commit,
+    message,
     environment = 'test',
+    parallelId,
     metadata = {}
   } = buildOptions;
   let randomId = deps.randomId || randomUUID;
@@ -30,10 +33,12 @@ export function createBuildObject(buildOptions, deps = {}) {
   let timestamp = deps.timestamp || Date.now;
   return {
     id: `build-${randomId()}`,
-    name: name || `build-${timestamp()}`,
+    name: name || buildName || `build-${timestamp()}`,
     branch,
     commit,
+    message,
     environment,
+    parallelId,
     metadata,
     status: 'pending',
     createdAt: now(),

package/dist/tdd/tdd-service.js

@@ -1163,6 +1163,9 @@ export class TddService {
     let newComparisons = getNewComparisons(this.comparisons);
     let passedComparisons = this.comparisons.filter(c => c.status === 'passed' || c.status === 'baseline-created' || c.status === 'baseline-updated');
     let hasChanges = failedComparisons.length > 0 || newComparisons.length > 0;
+    if (output.isJson?.()) {
+      return results;
+    }
 
     // Header with summary - use bear emoji as Vizzly mascot
     output.blank();
@@ -1239,9 +1242,10 @@ export class TddService {
       let serverFile = `${this.workingDir}/.vizzly/server.json`;
       let serverRunning = false;
       let serverPort = 47392;
+      let serverInfo = {};
       try {
         if (existsSync(serverFile)) {
-          let serverInfo = JSON.parse(readFileSync(serverFile, 'utf8'));
+          serverInfo = JSON.parse(readFileSync(serverFile, 'utf8'));
           if (serverInfo.port) {
             serverPort = serverInfo.port;
             serverRunning = true;
@@ -1250,7 +1254,7 @@ export class TddService {
       } catch {
         // Ignore errors reading server file
       }
-      if (serverRunning) {
+      if (serverRunning && !serverInfo.buildId) {
         // Server is running - show the dashboard URL
         output.print(`  ${textTertiary('→')} Review changes: ${infoColor(colors.underline(`http://localhost:${serverPort}`))}`);
       } else {

package/dist/test-runner/core.js

@@ -14,6 +14,7 @@
  * @param {number} options.port - Server port
  * @param {string} options.buildId - Build ID
  * @param {boolean} [options.setBaseline] - Whether to set baseline
+ * @param {boolean} [options.failOnDiff] - Whether visual diffs should fail tests
  * @param {Object} [options.baseEnv] - Base environment (defaults to process.env)
  * @returns {Object} Environment variables object
  */
@@ -21,6 +22,7 @@ export function buildTestEnv({
   port,
   buildId,
   setBaseline = false,
+  failOnDiff = false,
   baseEnv = process.env
 }) {
   return {
@@ -28,7 +30,8 @@ export function buildTestEnv({
     VIZZLY_SERVER_URL: `http://localhost:${port}`,
     VIZZLY_BUILD_ID: buildId,
     VIZZLY_ENABLED: 'true',
-    VIZZLY_SET_BASELINE: setBaseline ? 'true' : 'false'
+    VIZZLY_SET_BASELINE: setBaseline ? 'true' : 'false',
+    VIZZLY_FAIL_ON_DIFF: failOnDiff ? 'true' : 'false'
   };
 }
 
@@ -231,12 +234,14 @@ export function hasApiKey(config) {
 /**
  * Build spawn options for test command execution
  * @param {Object} env - Environment variables
+ * @param {Object} [options] - Spawn display options
+ * @param {boolean} [options.json] - Keep stdout reserved for CLI JSON output
  * @returns {Object} Spawn options
  */
-export function buildSpawnOptions(env) {
+export function buildSpawnOptions(env, options = {}) {
   return {
     env,
-    stdio: 'inherit',
+    stdio: options.json ? ['inherit', 'pipe', 'pipe'] : 'inherit',
     shell: true
   };
 }

package/dist/test-runner/operations.js

@@ -188,6 +188,7 @@ export async function finalizeBuild({
 export function executeTestCommand({
   command,
   env,
+  json = false,
   deps
 }) {
   let {
@@ -195,8 +196,18 @@ export function executeTestCommand({
     createError
   } = deps;
   return new Promise((resolve, reject) => {
-    let spawnOptions = buildSpawnOptions(env);
+    let spawnOptions = buildSpawnOptions(env, {
+      json
+    });
     let testProcess = spawn(command, spawnOptions);
+    if (json) {
+      testProcess.stdout?.on('data', data => {
+        process.stderr.write(data);
+      });
+      testProcess.stderr?.on('data', data => {
+        process.stderr.write(data);
+      });
+    }
     testProcess.on('error', error => {
       reject(createError(`Failed to run test command: ${error.message}`, 'TEST_COMMAND_FAILED'));
     });
@@ -271,6 +282,7 @@ export async function runTests({
     await executeTestCommand({
       command: testCommand,
       env,
+      json: runOptions.json,
       deps: {
         spawn,
         createError
@@ -334,12 +346,14 @@ export async function runTests({
     let env = buildTestEnv({
       port: config.server?.port,
       buildId,
-      setBaseline
+      setBaseline,
+      failOnDiff: runOptions.failOnDiff || false
     });
     try {
       await executeTestCommand({
         command: testCommand,
         env,
+        json: runOptions.json,
         deps: {
           spawn,
           createError
@@ -408,7 +422,9 @@ export async function runTests({
 
   // Throw test error after cleanup
   if (testError) {
-    output.error('Test run failed:', testError);
+    if (!runOptions.json) {
+      output.error('Test run failed:', testError);
+    }
     throw testError;
   }
   return buildRunResult({

package/dist/types/client.d.ts

@@ -24,6 +24,7 @@ export function autoDiscoverTddServer(
   deps?: {
     exists?: (path: string) => boolean;
     readFile?: (path: string, encoding: BufferEncoding) => string | Buffer;
+    env?: Record<string, string | undefined>;
   }
 ): string | null;
 
@@ -32,7 +33,14 @@ export function autoDiscoverTddServer(
  */
 export interface ScreenshotResult {
   success: boolean;
-  status?: 'passed' | 'failed' | 'new';
+  status?:
+    | 'passed'
+    | 'failed'
+    | 'new'
+    | 'match'
+    | 'diff'
+    | 'baseline-updated'
+    | 'error';
   name?: string;
   diffPercentage?: number;
   [key: string]: unknown;
@@ -59,10 +67,16 @@ export interface ScreenshotResult {
  * @example
  * // With properties and comparison settings
  * await vizzlyScreenshot('checkout-form', screenshot, {
- *   properties: { browser: 'chrome', viewport: '1920x1080' },
+ *   properties: { browser: 'chrome', viewport: { width: 1920, height: 1080 } },
  *   threshold: 5,
- *   minClusterSize: 10
+ *   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.
  */
 export function vizzlyScreenshot(
   name: string,
@@ -72,7 +86,10 @@ export function vizzlyScreenshot(
     threshold?: number;
     minClusterSize?: number;
     fullPage?: boolean;
-    [key: string]: unknown;
+    /** Transport-only build ID used to route the request. */
+    buildId?: string;
+    /** Client-side HTTP timeout in milliseconds; not stored as metadata. */
+    requestTimeout?: number;
   }
 ): Promise<ScreenshotResult | null>;
 
@@ -81,7 +98,15 @@ export function vizzlyScreenshot(
  */
 export interface FlushResult {
   success: boolean;
-  summary: {
+  uploaded?: number;
+  flushed?: boolean;
+  total?: number;
+  passed?: number;
+  failed?: number;
+  new?: number;
+  errors?: number;
+  message?: string;
+  summary?: {
     total: number;
     passed: number;
     failed: number;
@@ -124,6 +149,7 @@ export function isVizzlyReady(): boolean;
 export function configure(config?: {
   serverUrl?: string;
   enabled?: boolean;
+  failOnDiff?: boolean;
 }): void;
 
 /**
@@ -145,4 +171,5 @@ export function getVizzlyInfo(): {
   buildId: string | null;
   tddMode: boolean;
   disabled: boolean;
+  failOnDiff: boolean;
 };

package/dist/types/index.d.ts

@@ -24,7 +24,9 @@ export interface BuildConfig {
 
 export interface UploadConfig {
   screenshotsDir?: string | string[];
+  /** Batch size used when uploading screenshots. */
   batchSize?: number;
+  /** Timeout in milliseconds for waiting on build processing after upload. */
   timeout?: number;
 }
 
@@ -76,13 +78,22 @@ export interface ScreenshotOptions {
   threshold?: number;
   minClusterSize?: number;
   fullPage?: boolean;
+  /** Transport-only build ID used to route the request. */
   buildId?: string;
-  [key: string]: unknown;
+  /** Client-side HTTP timeout in milliseconds; not stored as metadata. */
+  requestTimeout?: number;
 }
 
 export interface ScreenshotResult {
   success: boolean;
-  status?: 'passed' | 'failed' | 'new';
+  status?:
+    | 'passed'
+    | 'failed'
+    | 'new'
+    | 'match'
+    | 'diff'
+    | 'baseline-updated'
+    | 'error';
   name?: string;
   diffPercentage?: number;
   [key: string]: unknown;
@@ -95,7 +106,13 @@ export interface ScreenshotResult {
 export interface ComparisonResult {
   id: string;
   name: string;
-  status: 'passed' | 'failed' | 'new' | 'error' | 'baseline-updated';
+  status:
+    | 'passed'
+    | 'failed'
+    | 'new'
+    | 'error'
+    | 'baseline-created'
+    | 'baseline-updated';
   baseline: string;
   current: string;
   diff: string | null;
@@ -150,7 +167,9 @@ export interface UploadOptions {
   message?: string;
   environment?: string;
   threshold?: number;
-  pullRequestNumber?: string;
+  minClusterSize?: number;
+  metadata?: Record<string, unknown>;
+  pullRequestNumber?: string | number;
   parallelId?: string;
   onProgress?: (progress: UploadProgress) => void;
 }
@@ -186,8 +205,10 @@ export interface BuildResult {
   status: 'completed' | 'failed' | 'pending';
   build: unknown;
   comparisons?: number;
+  totalComparisons: number;
   passedComparisons?: number;
   failedComparisons?: number;
+  newComparisons: number;
   url?: string;
 }
 
@@ -487,15 +508,19 @@ export interface BuildOptions {
   buildName?: string;
   branch?: string;
   commit?: string;
+  commit_sha?: string;
   message?: string;
+  commit_message?: string;
   environment?: string;
   threshold?: number;
   eager?: boolean;
   allowNoToken?: boolean;
   wait?: boolean;
   uploadAll?: boolean;
-  pullRequestNumber?: string;
+  pullRequestNumber?: string | number;
+  github_pull_request_number?: string | number;
   parallelId?: string;
+  parallel_id?: string;
 }
 
 /**
@@ -565,6 +590,8 @@ export function vizzlyScreenshot(
     threshold?: number;
     minClusterSize?: number;
     fullPage?: boolean;
+    requestTimeout?: number;
+    buildId?: string;
     [key: string]: unknown;
   }
 ): Promise<ScreenshotResult | null>;
@@ -573,6 +600,7 @@ export function vizzlyScreenshot(
 export function configure(config?: {
   serverUrl?: string;
   enabled?: boolean;
+  failOnDiff?: boolean;
 }): void;
 
 /** Enable or disable screenshot capture */

package/dist/uploader/core.js

@@ -123,6 +123,25 @@ export function extractBrowserFromFilename(filename) {
 // Build Info Construction
 // ============================================================================
 
+function buildUploadMetadata(options) {
+  let metadata = {
+    ...(options.metadata || {})
+  };
+  let comparison = {
+    ...(metadata.comparison || {})
+  };
+  if (options.threshold !== undefined) {
+    comparison.threshold = options.threshold;
+  }
+  if (options.minClusterSize !== undefined) {
+    comparison.minClusterSize = options.minClusterSize;
+  }
+  if (Object.keys(comparison).length > 0) {
+    metadata.comparison = comparison;
+  }
+  return Object.keys(metadata).length > 0 ? metadata : undefined;
+}
+
 /**
  * Build API build info payload
  * @param {Object} options - Upload options
@@ -130,7 +149,7 @@ export function extractBrowserFromFilename(filename) {
  * @returns {Object} Build info payload
  */
 export function buildBuildInfo(options, defaultBranch = 'main') {
-  return {
+  let buildInfo = {
     name: options.buildName || `Upload ${new Date().toISOString()}`,
     branch: options.branch || defaultBranch || 'main',
     commit_sha: options.commit,
@@ -140,6 +159,11 @@ export function buildBuildInfo(options, defaultBranch = 'main') {
     github_pull_request_number: options.pullRequestNumber,
     parallel_id: options.parallelId
   };
+  let metadata = buildUploadMetadata(options);
+  if (metadata) {
+    buildInfo.metadata = metadata;
+  }
+  return buildInfo;
 }
 
 // ============================================================================
@@ -316,17 +340,25 @@ export function buildUploadResult({
  * @returns {Object} Wait result
  */
 export function buildWaitResult(build) {
+  let totalComparisons = build.comparisonsTotal ?? build.total_comparisons ?? 0;
+  let passedComparisons = build.comparisonsPassed ?? build.passed_comparisons ?? build.identicalComparisons ?? build.identical_comparisons ?? 0;
+  let failedComparisons = build.comparisonsFailed ?? build.failed_comparisons ?? build.changedComparisons ?? build.changed_comparisons ?? 0;
+  let newComparisons = build.comparisonsNew ?? build.newComparisons ?? build.new_comparisons ?? 0;
+  let identicalComparisons = build.identicalComparisons ?? build.identical_comparisons ?? passedComparisons;
+  let approvalStatus = build.approvalStatus ?? build.approval_status ?? 'pending';
+  let hasComparisonCounts = build.comparisonsTotal !== undefined || build.total_comparisons !== undefined || build.comparisonsPassed !== undefined || build.passed_comparisons !== undefined || build.comparisonsFailed !== undefined || build.failed_comparisons !== undefined || build.comparisonsNew !== undefined || build.new_comparisons !== undefined || build.identicalComparisons !== undefined || build.identical_comparisons !== undefined;
   let result = {
     status: 'completed',
-    build
+    build,
+    passedComparisons,
+    failedComparisons,
+    newComparisons,
+    identicalComparisons,
+    approvalStatus,
+    totalComparisons
   };
-  if (typeof build.comparisonsTotal === 'number') {
-    result.comparisons = build.comparisonsTotal;
-    result.passedComparisons = build.comparisonsPassed || 0;
-    result.failedComparisons = build.comparisonsFailed || 0;
-  } else {
-    result.passedComparisons = 0;
-    result.failedComparisons = 0;
+  if (hasComparisonCounts) {
+    result.comparisons = totalComparisons;
   }
   if (build.url) {
     result.url = build.url;

package/dist/uploader/operations.js

@@ -386,23 +386,25 @@ export async function upload({
     let buildInfo = buildBuildInfo(uploadOptions, defaultBranch);
     let build = await createBuild(client, buildInfo);
     let buildId = build.id;
-
-    // Check existing files
-    let {
-      toUpload,
-      existing,
-      screenshots
-    } = await checkExistingFiles({
-      fileMetadata,
-      client,
-      signal,
-      buildId,
-      deps: {
-        checkShas,
-        createError,
-        output
-      }
-    });
+    let toUpload = fileMetadata;
+    let existing = [];
+    let screenshots = [];
+    if (!uploadOptions.uploadAll) {
+      let existingResult = await checkExistingFiles({
+        fileMetadata,
+        client,
+        signal,
+        buildId,
+        deps: {
+          checkShas,
+          createError,
+          output
+        }
+      });
+      toUpload = existingResult.toUpload;
+      existing = existingResult.existing;
+      screenshots = existingResult.screenshots;
+    }
     onProgress(buildDeduplicationProgress(toUpload.length, existing.length, files.length));
 
     // Upload files