@vizzly-testing/cli 0.34.0 → 0.35.1

package/dist/client/index.js

@@ -8,22 +8,27 @@ import { request as httpRequest } from 'node:http';
 import { request as httpsRequest } from 'node:https';
 import { dirname, join, parse } from 'node:path';
 import { getBuildId, getServerUrl, isTddMode, setVizzlyEnabled } from '../utils/environment-config.js';
-import { createScreenshotProperties } from '../utils/screenshot-options.js';
+import { normalizeScreenshotOptions } from '../utils/screenshot-options.js';
 
 // Internal client state
 let currentClient = null;
+let currentServerUrl = null;
 let isDisabled = false;
+let currentFailOnDiff = false;
 
 // Default timeout for screenshot requests (30 seconds)
 let DEFAULT_TIMEOUT_MS = 30000;
 
 // Log levels for client SDK output control
-export let LOG_LEVELS = {
+export let LOG_LEVELS = Object.freeze({
   debug: 0,
   info: 1,
   warn: 2,
   error: 3
-};
+});
+function getEnvFailOnDiff(env = process.env) {
+  return env.VIZZLY_FAIL_ON_DIFF === 'true' || env.VIZZLY_FAIL_ON_DIFF === '1';
+}
 
 /**
  * Check if client should log at the given level
@@ -56,6 +61,7 @@ function isVizzlyDisabled() {
 function disableVizzly() {
   isDisabled = true;
   currentClient = null;
+  currentServerUrl = null;
 }
 
 /**
@@ -67,7 +73,8 @@ function disableVizzly() {
 export function autoDiscoverTddServer(startDir, deps = {}) {
   let {
     exists = existsSync,
-    readFile = readFileSync
+    readFile = readFileSync,
+    env = process.env
   } = deps;
   try {
     // Look for .vizzly/server.json in current directory and parent directories
@@ -80,6 +87,7 @@ export function autoDiscoverTddServer(startDir, deps = {}) {
           let serverInfo = JSON.parse(readFile(serverJsonPath, 'utf8'));
           if (serverInfo.port) {
             let url = `http://localhost:${serverInfo.port}`;
+            currentFailOnDiff = getEnvFailOnDiff(env) || Boolean(serverInfo.failOnDiff);
             return url;
           }
         } catch {
@@ -104,6 +112,7 @@ function getClient() {
   }
   if (!currentClient) {
     let serverUrl = getServerUrl();
+    currentFailOnDiff = getEnvFailOnDiff();
 
     // Auto-detect local TDD server and enable Vizzly if TDD server is found
     if (!serverUrl) {
@@ -116,7 +125,10 @@ function getClient() {
 
     // If we have a server URL, create the client (regardless of initial enabled state)
     if (serverUrl) {
-      currentClient = createSimpleClient(serverUrl);
+      currentServerUrl = serverUrl;
+      currentClient = createSimpleClient(serverUrl, {
+        failOnDiff: currentFailOnDiff
+      });
     }
   }
   return currentClient;
@@ -183,28 +195,38 @@ function httpPost(url, body, timeoutMs) {
  * Create a simple HTTP client for screenshots
  * @private
  */
-function createSimpleClient(serverUrl) {
+function createSimpleClient(serverUrl, clientOptions = {}) {
+  let {
+    failOnDiff = false
+  } = clientOptions;
   return {
     async screenshot(name, imageBuffer, options = {}) {
+      let normalizedOptions = normalizeScreenshotOptions(options);
+      let requestTimeout = normalizedOptions.requestTimeout || DEFAULT_TIMEOUT_MS;
+      for (let warning of normalizedOptions.warnings) {
+        console.warn(`[vizzly] ${warning.message}`);
+      }
       try {
         // If it's a string, assume it's a file path and send directly
         // Otherwise it's a Buffer, so convert to base64
         let isFilePath = typeof imageBuffer === 'string';
         let image = isFilePath ? imageBuffer : imageBuffer.toString('base64');
         let type = isFilePath ? 'file-path' : 'base64';
-        let requestTimeout = options.requestTimeout || DEFAULT_TIMEOUT_MS;
-        let properties = createScreenshotProperties(options);
+        let screenshotData = {
+          buildId: normalizedOptions.buildId ?? getBuildId(),
+          name,
+          image,
+          type,
+          properties: normalizedOptions.properties
+        };
+        if (normalizedOptions.warnings.length > 0) {
+          screenshotData.warnings = normalizedOptions.warnings;
+        }
         let httpStart = Date.now();
         let {
           status,
           json
-        } = await httpPost(`${serverUrl}/screenshot`, {
-          buildId: getBuildId(),
-          name,
-          image,
-          type,
-          properties
-        }, requestTimeout);
+        } = await httpPost(`${serverUrl}/screenshot`, screenshotData, requestTimeout);
         let httpMs = Date.now() - httpStart;
         if (shouldLogClient('debug')) {
           console.debug(`[vizzly-client] ${name} HTTP completed in ${httpMs}ms`);
@@ -215,6 +237,9 @@ function createSimpleClient(serverUrl) {
           // The summary will show all failures at the end
           if (status === 422 && json.tddMode && json.comparison) {
             let comp = json.comparison;
+            if (failOnDiff) {
+              throw new Error(`Visual diff detected for "${comp.name}" (${comp.diffPercentage ?? 0}% difference)`);
+            }
 
             // Return success so test continues and captures remaining screenshots
             // Visual diff details will be shown in the summary after tests complete
@@ -227,12 +252,15 @@ function createSimpleClient(serverUrl) {
           }
           throw new Error(`Screenshot failed: ${status} - ${json.error || 'Unknown error'}`);
         }
+        if (failOnDiff && json?.tddMode && ['diff', 'failed'].includes(json.status)) {
+          throw new Error(`Visual diff detected for "${json.name || name}" (${json.diffPercentage ?? 0}% difference)`);
+        }
         return json;
       } catch (error) {
         // Handle timeout
         if (error.message === 'Request timeout') {
           if (shouldLogClient('error')) {
-            console.error(`[vizzly] Screenshot timed out for "${name}" after ${DEFAULT_TIMEOUT_MS / 1000}s`);
+            console.error(`[vizzly] Screenshot timed out for "${name}" after ${requestTimeout / 1000}s`);
           }
           disableVizzly();
           return null;
@@ -308,7 +336,7 @@ function createSimpleClient(serverUrl) {
  * await vizzlyScreenshot('checkout-form', screenshot, {
  *   properties: {
  *     browser: 'chrome',
- *     viewport: '1920x1080'
+ *     viewport: { width: 1920, height: 1080 }
  *   },
  *   threshold: 5
  * });
@@ -366,8 +394,20 @@ export function isVizzlyReady() {
  * @param {boolean} [config.enabled] - Enable/disable screenshots
  */
 export function configure(config = {}) {
+  if ('failOnDiff' in config) {
+    currentFailOnDiff = config.failOnDiff === true;
+  } else if ('serverUrl' in config) {
+    currentFailOnDiff = getEnvFailOnDiff();
+  }
   if ('serverUrl' in config) {
-    currentClient = config.serverUrl ? createSimpleClient(config.serverUrl) : null;
+    currentServerUrl = config.serverUrl || null;
+    currentClient = config.serverUrl ? createSimpleClient(config.serverUrl, {
+      failOnDiff: currentFailOnDiff
+    }) : null;
+  } else if ('failOnDiff' in config && currentClient && currentServerUrl) {
+    currentClient = createSimpleClient(currentServerUrl, {
+      failOnDiff: currentFailOnDiff
+    });
   }
   if (typeof config.enabled === 'boolean') {
     setVizzlyEnabled(config.enabled);
@@ -397,10 +437,11 @@ export function getVizzlyInfo() {
   let client = getClient();
   return {
     enabled: !isVizzlyDisabled(),
-    serverUrl: getServerUrl(),
+    serverUrl: currentServerUrl || getServerUrl() || null,
     ready: !isVizzlyDisabled() && client !== null,
-    buildId: getBuildId(),
+    buildId: getBuildId() || null,
     tddMode: isTddMode(),
-    disabled: isVizzlyDisabled()
+    disabled: isVizzlyDisabled(),
+    failOnDiff: currentFailOnDiff
   };
 }

package/dist/commands/api.js

@@ -65,7 +65,8 @@ export function appendApiQuery(endpoint, queryOption) {
 }
 export function validateApiRequest({
   endpoint,
-  method
+  method,
+  hasData = false
 }) {
   let errors = [];
   if (method !== 'GET' && method !== 'POST') {
@@ -75,6 +76,9 @@ export function validateApiRequest({
   if (method === 'POST' && !isAllowedPostEndpoint(endpoint)) {
     errors.push(`POST not allowed for ${endpoint}. Only approve, reject, and comment endpoints support POST.`);
   }
+  if (hasData && method !== 'POST') {
+    errors.push('Request data requires --method POST.');
+  }
   return errors;
 }
 export function buildApiRequest({
@@ -85,7 +89,8 @@ export function buildApiRequest({
   let method = normalizeApiMethod(options.method || 'GET');
   let errors = validateApiRequest({
     endpoint: normalizedEndpoint,
-    method
+    method,
+    hasData: options.data !== undefined
   });
   if (errors.length > 0) {
     return {
@@ -239,7 +244,8 @@ export function validateApiOptions(endpoint, options = {}) {
   let method = normalizeApiMethod(options.method || 'GET');
   errors.push(...validateApiRequest({
     endpoint: normalizedEndpoint,
-    method
+    method,
+    hasData: options.data !== undefined
   }));
   return errors;
 }

package/dist/commands/preview.js

@@ -259,6 +259,7 @@ export async function previewCommand(path, options = {}, globalOptions = {}, dep
     formatSessionAge = defaultFormatSessionAge,
     detectBranch = defaultDetectBranch,
     openBrowser = defaultOpenBrowser,
+    createZipWithSystem: createZip = createZipWithSystem,
     output = defaultOutput,
     exit = code => process.exit(code)
   } = deps;
@@ -268,39 +269,42 @@ export async function previewCommand(path, options = {}, globalOptions = {}, dep
     color: !globalOptions.noColor
   });
   try {
-    // Load configuration
-    let allOptions = {
-      ...globalOptions,
-      ...options
-    };
-    let config = await loadConfig(globalOptions.config, allOptions);
+    let uploadPath = options.base ? resolve(path, options.base) : path;
 
-    // Validate API token (skip for dry-run)
-    if (!options.dryRun && !config.apiKey) {
-      output.error('API token required. Use --token or set VIZZLY_TOKEN environment variable');
+    // Validate path exists and is a directory before auth so local input
+    // mistakes are visible without requiring credentials.
+    if (!existsSync(uploadPath)) {
+      output.error(`Path does not exist: ${uploadPath}`);
       exit(1);
       return {
         success: false,
-        reason: 'no-api-key'
+        reason: 'path-not-found'
       };
     }
-
-    // Validate path exists and is a directory
-    if (!existsSync(path)) {
-      output.error(`Path does not exist: ${path}`);
+    let pathStat = statSync(uploadPath);
+    if (!pathStat.isDirectory()) {
+      output.error(`Path is not a directory: ${uploadPath}`);
       exit(1);
       return {
         success: false,
-        reason: 'path-not-found'
+        reason: 'not-a-directory'
       };
     }
-    let pathStat = statSync(path);
-    if (!pathStat.isDirectory()) {
-      output.error(`Path is not a directory: ${path}`);
+
+    // Load configuration
+    let allOptions = {
+      ...globalOptions,
+      ...options
+    };
+    let config = await loadConfig(globalOptions.config, allOptions);
+
+    // Validate API token (skip for dry-run)
+    if (!options.dryRun && !config.apiKey) {
+      output.error('API token required. Use --token or set VIZZLY_TOKEN environment variable');
       exit(1);
       return {
         success: false,
-        reason: 'not-a-directory'
+        reason: 'no-api-key'
       };
     }
 
@@ -455,14 +459,14 @@ export async function previewCommand(path, options = {}, globalOptions = {}, dep
       count: fileCount,
       totalSize,
       files
-    } = await countFiles(path, {
+    } = await countFiles(uploadPath, {
       collectPaths: options.dryRun,
       excludedDirs,
       excludedFiles
     });
     if (fileCount === 0) {
       output.stopSpinner();
-      output.error(`No files found in ${path}`);
+      output.error(`No files found in ${uploadPath}`);
       exit(1);
       return {
         success: false,
@@ -477,7 +481,7 @@ export async function previewCommand(path, options = {}, globalOptions = {}, dep
       if (globalOptions.json) {
         output.data({
           dryRun: true,
-          path: resolve(path),
+          path: resolve(uploadPath),
           fileCount,
           totalSize,
           excludedDirs,
@@ -490,7 +494,7 @@ export async function previewCommand(path, options = {}, globalOptions = {}, dep
       } else {
         output.info(`Dry run - would upload ${fileCount} files (${formatBytes(totalSize)})`);
         output.blank();
-        output.print(`  ${colors.brand.textTertiary('Source')}      ${resolve(path)}`);
+        output.print(`  ${colors.brand.textTertiary('Source')}      ${resolve(uploadPath)}`);
         output.print(`  ${colors.brand.textTertiary('Files')}       ${fileCount}`);
         output.print(`  ${colors.brand.textTertiary('Total size')}  ${formatBytes(totalSize)}`);
         output.blank();
@@ -538,7 +542,7 @@ export async function previewCommand(path, options = {}, globalOptions = {}, dep
     let zipPath = join(tmpdir(), `vizzly-preview-${Date.now()}-${randomSuffix}.zip`);
     let zipBuffer;
     try {
-      await createZipWithSystem(path, zipPath, exclusions);
+      await createZip(uploadPath, zipPath, exclusions);
       zipBuffer = await readFile(zipPath);
     } catch (zipError) {
       output.stopSpinner();
@@ -569,10 +573,10 @@ export async function previewCommand(path, options = {}, globalOptions = {}, dep
         success: true,
         buildId,
         previewUrl: result.previewUrl,
-        files: result.uploaded || fileCount,
+        files: result.uploaded ?? fileCount,
         bytes: totalSize,
         compressedBytes: zipBuffer.length,
-        compressionRatio,
+        compressionRatio: `${compressionPercent}%`,
         newBytes: result.newBytes,
         reusedBlobs: result.reusedBlobs || 0,
         deduplicationRatio: result.deduplicationRatio,

package/dist/commands/project.js

@@ -56,7 +56,7 @@ export async function projectLinkCommand(selector, options = {}, globalOptions =
   } = parseProjectSelector(selector, options);
   try {
     let config = await loadConfig(globalOptions.config, globalOptions);
-    let userToken = config.userToken || (await getAccessToken());
+    let userToken = config.userToken || globalOptions.token || (await getAccessToken());
     if (!userToken) {
       output.error('Login required before linking a project');
       output.hint('Run "vizzly login" first, then try project link again');

package/dist/commands/run.js

@@ -5,6 +5,7 @@
 
 import { spawn as defaultSpawn } from 'node:child_process';
 import { createBuild as defaultCreateApiBuild, createApiClient as defaultCreateApiClient, finalizeBuild as defaultFinalizeApiBuild, getBuild as defaultGetBuild, getTokenContext as defaultGetTokenContext } from '../api/index.js';
+import { CONFIG_DEFAULTS } from '../config/core.js';
 import { VizzlyError } from '../errors/vizzly-error.js';
 import { createServerManager as defaultCreateServerManager } from '../server-manager/index.js';
 import { createBuildObject as defaultCreateBuildObject } from '../services/build-manager.js';
@@ -174,10 +175,11 @@ export async function runCommand(testCommand, options = {}, globalOptions = {},
     }
 
     // Collect git metadata and build info
-    let branch = await detectBranch(options.branch);
-    let commit = await detectCommit(options.commit);
-    let message = options.message || (await detectCommitMessage());
-    let buildName = await generateBuildNameWithGit(options.buildName);
+    let configuredBuildName = config.build.name && config.build.name !== CONFIG_DEFAULTS.build.name ? config.build.name : undefined;
+    let branch = await detectBranch(options.branch || config.build.branch);
+    let commit = await detectCommit(options.commit || config.build.commit);
+    let message = options.message || config.build.message || (await detectCommitMessage());
+    let buildName = await generateBuildNameWithGit(options.buildName || configuredBuildName);
     let pullRequestNumber = detectPullRequestNumber();
     if (globalOptions.verbose) {
       output.info('Configuration loaded');
@@ -244,7 +246,8 @@ export async function runCommand(testCommand, options = {}, globalOptions = {},
       wait: config.wait || options.wait || false,
       uploadAll: options.uploadAll || false,
       pullRequestNumber,
-      parallelId: config.parallelId
+      parallelId: config.parallelId,
+      json: globalOptions.json
     };
 
     // Start test run
@@ -305,7 +308,7 @@ export async function runCommand(testCommand, options = {}, globalOptions = {},
       }
 
       // JSON output mode - output structured data and exit
-      if (globalOptions.json) {
+      if (globalOptions.json && !runOptions.wait) {
         let executionTimeMs = Date.now() - startTime;
         let displayUrl = await resolveBuildDisplayUrl({
           result,
@@ -334,10 +337,12 @@ export async function runCommand(testCommand, options = {}, globalOptions = {},
           result
         };
       }
-      output.complete('Test run completed');
+      if (!globalOptions.json) {
+        output.complete('Test run completed');
+      }
 
       // Show Vizzly summary with link to results
-      if (result.buildId) {
+      if (result.buildId && !globalOptions.json) {
         output.blank();
         let colors = output.getColors();
         output.print(`  ${colors.brand.textTertiary('Screenshots')}  ${colors.white(result.screenshotsCaptured)}`);
@@ -384,7 +389,7 @@ export async function runCommand(testCommand, options = {}, globalOptions = {},
           });
           output.cleanup();
         } else {
-          output.error('Test run failed');
+          output.error('Test run failed', error);
         }
         return {
           success: false,
@@ -490,7 +495,17 @@ export async function runCommand(testCommand, options = {}, globalOptions = {},
     // Don't fail CI for Vizzly infrastructure issues (5xx errors)
     let status = error.context?.status;
     if (status >= 500) {
-      output.warn('Vizzly API unavailable - visual tests skipped. Your tests still ran.');
+      if (globalOptions.json) {
+        output.data({
+          buildId: null,
+          status: 'skipped',
+          message: 'Vizzly API unavailable - visual tests skipped',
+          executionTimeMs: Date.now() - (startTime || Date.now())
+        });
+      } else {
+        output.warn('Vizzly API unavailable - visual tests skipped. Your tests still ran.');
+      }
+      output.cleanup();
       output.debug('api', 'API error details:', {
         error: error.message
       });

package/dist/commands/status.js

@@ -36,6 +36,19 @@ function createStatusClient({
     command: 'status'
   });
 }
+function isMissingPreviewError(error) {
+  return error.context?.status === 404;
+}
+async function fetchOptionalPreviewInfo(getPreviewInfo, client, buildId) {
+  try {
+    return await getPreviewInfo(client, buildId);
+  } catch (error) {
+    if (isMissingPreviewError(error)) {
+      return null;
+    }
+    throw error;
+  }
+}
 export function normalizeBuildStatus(buildStatus) {
   return buildStatus.build || buildStatus;
 }
@@ -251,7 +264,7 @@ export async function statusCommand(buildId, options = {}, globalOptions = {}, d
     let buildStatus = await getBuild(client, buildId);
 
     // Also fetch preview info (if exists)
-    let previewInfo = await getPreviewInfo(client, buildId);
+    let previewInfo = await fetchOptionalPreviewInfo(getPreviewInfo, client, buildId);
     output.stopSpinner();
 
     // Extract build data from API response

package/dist/commands/tdd-daemon-process.js

@@ -18,7 +18,7 @@ function isProcessRunning(pid) {
     return false;
   }
 }
-function parsePositiveInteger(value) {
+export function parsePositiveInteger(value) {
   let text = String(value).trim();
   if (!/^\d+$/.test(text)) {
     return null;
@@ -71,12 +71,16 @@ export async function resolveDaemonPid({
   pidFile = join(process.cwd(), '.vizzly', 'server.pid'),
   readPid = readDaemonPidFile,
   findByPort = findDaemonPidByPort,
+  allowPortFallback = false,
   fileDeps = {}
 } = {}) {
   let pid = readPid(pidFile, fileDeps);
   if (pid) {
     return pid;
   }
+  if (!allowPortFallback) {
+    return null;
+  }
   return await findByPort(port);
 }
 export async function waitForProcessExit(pid, {