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

package/README.md

@@ -144,19 +144,19 @@ test('homepage looks correct', async ({ page }) => {
     fullPage: true,
     requestTimeout: 5000,
     properties: {
-      browser: 'chrome',
-      viewport: { width: 1920, height: 1080 },
+      theme: 'dark',
+      locale: 'en-US',
     },
   });
 });
 ```
 
-`properties` is your metadata bag for baseline grouping, filtering, and
-debugging. SDK options such as `threshold`, `minClusterSize`, `fullPage`,
-`requestTimeout`, and `buildId` stay at the top level. If one of those reserved
-SDK options is accidentally placed inside `properties`, Vizzly removes it from
-metadata, applies it as an option when possible, and warns so the call site can
-be cleaned up.
+`properties` is your key/value metadata bag for baseline grouping, filtering,
+and debugging. Vizzly passes every property through as user metadata; property
+names are never interpreted as options. The supported top-level options are
+`threshold`, `minClusterSize`, `fullPage`, `requestTimeout`, and `buildId`.
+Vizzly reads width and height from the captured image, so viewport dimensions do
+not need to be included in `properties`.
 
 The client SDK is lightweight. It posts screenshots to the local Vizzly server
 or the cloud build wrapper. It works with any test runner.

package/dist/api/core.js

@@ -7,6 +7,7 @@
 
 import crypto from 'node:crypto';
 import { URLSearchParams } from 'node:url';
+import { createScreenshotProperties, getScreenshotOptionsPayload } from '../utils/screenshot-options.js';
 
 // ============================================================================
 // Header Building
@@ -29,14 +30,17 @@ export function buildAuthHeader(token) {
  * @param {string} version - CLI version
  * @param {string} command - Command being executed (run, upload, tdd, etc.)
  * @param {string|null} sdkUserAgent - Optional SDK user agent to append
+ * @param {string} nodeVersion - Node.js version to append
  * @returns {string} Complete User-Agent string
  */
-export function buildUserAgent(version, command, sdkUserAgent = null) {
+export function buildUserAgent(version, command, sdkUserAgent = null, nodeVersion = process.versions.node) {
   let baseUserAgent = `vizzly-cli/${version} (${command})`;
+  let userAgentParts = [baseUserAgent];
   if (sdkUserAgent) {
-    return `${baseUserAgent} ${sdkUserAgent}`;
+    userAgentParts.push(sdkUserAgent);
   }
-  return baseUserAgent;
+  if (nodeVersion) userAgentParts.push(`node/${nodeVersion}`);
+  return userAgentParts.join(' ');
 }
 
 /**
@@ -73,15 +77,18 @@ export function buildRequestHeaders({
  * Build payload for screenshot upload or SHA resolution
  * @param {string} name - Screenshot name
  * @param {Buffer|null} buffer - Image data, or null when resolving by SHA
- * @param {Object} metadata - Screenshot metadata (viewport, browser, etc.)
+ * @param {Object} metadata - User screenshot properties
  * @param {string|null} sha256 - Pre-computed SHA256 hash (optional)
  * @returns {Object} Screenshot upload payload
  */
-export function buildScreenshotPayload(name, buffer, metadata = {}, sha256 = null) {
+export function buildScreenshotPayload(name, buffer, metadata = {}, sha256 = null, screenshotOptions = {}) {
   let payload = {
     name,
-    properties: metadata ?? {}
+    properties: createScreenshotProperties({
+      properties: metadata
+    })
   };
+  Object.assign(payload, getScreenshotOptionsPayload(screenshotOptions));
   if (buffer) {
     payload.image_data = buffer.toString('base64');
   }
@@ -94,12 +101,12 @@ export function buildScreenshotPayload(name, buffer, metadata = {}, sha256 = nul
 /**
  * Build payload for server-side screenshot resolution without sending image bytes
  * @param {string} name - Screenshot name
- * @param {Object} metadata - Screenshot metadata (viewport, browser, etc.)
+ * @param {Object} metadata - User screenshot properties
  * @param {string} sha256 - Pre-computed SHA256 hash
  * @returns {Object} Screenshot resolution payload
  */
-export function buildScreenshotResolvePayload(name, metadata = {}, sha256) {
-  return buildScreenshotPayload(name, null, metadata, sha256);
+export function buildScreenshotResolvePayload(name, metadata = {}, sha256, screenshotOptions = {}) {
+  return buildScreenshotPayload(name, null, metadata, sha256, screenshotOptions);
 }
 
 /**
@@ -180,13 +187,13 @@ export function buildShaCheckPayload(screenshots, buildId) {
  */
 export function buildScreenshotCheckObject(sha256, name, metadata = {}) {
   let meta = metadata || {};
+  let properties = createScreenshotProperties({
+    properties: meta
+  });
   return {
     sha256,
     name,
-    browser: meta.browser || 'chrome',
-    viewport_width: meta.viewport?.width || meta.viewport_width || 1920,
-    viewport_height: meta.viewport?.height || meta.viewport_height || 1080,
-    properties: meta
+    properties
   };
 }
 

package/dist/api/endpoints.js

@@ -80,13 +80,15 @@ export async function createBuild(client, metadata) {
  * @param {Object} client - API client
  * @param {string} buildId - Build ID
  * @param {string} status - Build status (pending|running|completed|failed)
- * @param {number|null} executionTimeMs - Execution time in milliseconds
+ * @param {number|null} [executionTimeMs=null] - Execution time in milliseconds
+ * @param {string} [failureReason] - Explanation sent only for a failed build
  * @returns {Promise<Object>} Updated build data
  */
-export async function updateBuildStatus(client, buildId, status, executionTimeMs = null) {
+export async function updateBuildStatus(client, buildId, status, executionTimeMs = null, failureReason) {
   let body = {
     status
   };
+  if (status === 'failed' && failureReason) body.failureReason = failureReason;
   if (executionTimeMs != null) {
     body.executionTimeMs = executionTimeMs;
   }
@@ -100,16 +102,17 @@ export async function updateBuildStatus(client, buildId, status, executionTimeMs
 }
 
 /**
- * Finalize a build (convenience wrapper for updateBuildStatus)
+ * Mark a build completed or failed, with an optional failure explanation.
  * @param {Object} client - API client
  * @param {string} buildId - Build ID
- * @param {boolean} success - Whether the build succeeded
- * @param {number|null} executionTimeMs - Execution time in milliseconds
+ * @param {boolean} [success=true] - Whether tests and uploads succeeded
+ * @param {number|null} [executionTimeMs=null] - Execution time in milliseconds
+ * @param {string} [failureReason] - Explanation sent only for a failed build
  * @returns {Promise<Object>} Finalized build data
  */
-export async function finalizeBuild(client, buildId, success = true, executionTimeMs = null) {
+export async function finalizeBuild(client, buildId, success = true, executionTimeMs = null, failureReason) {
   let status = success ? 'completed' : 'failed';
-  return updateBuildStatus(client, buildId, status, executionTimeMs);
+  return updateBuildStatus(client, buildId, status, executionTimeMs, failureReason);
 }
 
 /**
@@ -179,10 +182,10 @@ function canUploadBytesAfterShaResolveError(error) {
  * @param {boolean} skipDedup - Skip SHA deduplication (uploadAll mode)
  * @returns {Promise<Object>} Upload result
  */
-export async function uploadScreenshot(client, buildId, name, buffer, metadata = {}, skipDedup = false) {
+export async function uploadScreenshot(client, buildId, name, buffer, metadata = {}, skipDedup = false, screenshotOptions = {}) {
   // Skip SHA deduplication if requested
   if (skipDedup) {
-    let payload = buildScreenshotPayload(name, buffer, metadata);
+    let payload = buildScreenshotPayload(name, buffer, metadata, null, screenshotOptions);
     return client.request(`/api/sdk/builds/${buildId}/screenshots`, {
       method: 'POST',
       headers: {
@@ -194,7 +197,7 @@ export async function uploadScreenshot(client, buildId, name, buffer, metadata =
 
   // Normal flow with server-side SHA resolution.
   let sha256 = computeSha256(buffer);
-  let resolvePayload = buildScreenshotResolvePayload(name, metadata, sha256);
+  let resolvePayload = buildScreenshotResolvePayload(name, metadata, sha256, screenshotOptions);
   try {
     let resolveResult = await client.request(`/api/sdk/builds/${buildId}/screenshots`, {
       method: 'POST',
@@ -222,7 +225,7 @@ export async function uploadScreenshot(client, buildId, name, buffer, metadata =
   }
 
   // File doesn't exist, or resolve failed; proceed with upload.
-  let payload = buildScreenshotPayload(name, buffer, metadata, sha256);
+  let payload = buildScreenshotPayload(name, buffer, metadata, sha256, screenshotOptions);
   return client.request(`/api/sdk/builds/${buildId}/screenshots`, {
     method: 'POST',
     headers: {

package/dist/client/index.js

@@ -8,7 +8,7 @@ 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 { normalizeScreenshotOptions } from '../utils/screenshot-options.js';
+import { getScreenshotOptionsPayload, normalizeScreenshotOptions } from '../utils/screenshot-options.js';
 
 // Internal client state
 let currentClient = null;
@@ -203,9 +203,6 @@ function createSimpleClient(serverUrl, clientOptions = {}) {
     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
@@ -219,9 +216,7 @@ function createSimpleClient(serverUrl, clientOptions = {}) {
           type,
           properties: normalizedOptions.properties
         };
-        if (normalizedOptions.warnings.length > 0) {
-          screenshotData.warnings = normalizedOptions.warnings;
-        }
+        Object.assign(screenshotData, getScreenshotOptionsPayload(normalizedOptions));
         let httpStart = Date.now();
         let {
           status,

package/dist/commands/run.js

@@ -1,5 +1,10 @@
 /**
- * Run command implementation
+ * Run tests and report their visual results in terminal or JSON output.
+ *
+ * Incomplete uploads preserve the test exit code and skip comparison waiting.
+ * After successful uploads, --wait can still fail for visual comparison results.
+ * The returned success flag describes command success, not upload completeness.
+ *
  * Uses functional operations directly - no class wrappers needed
  */
 
@@ -16,6 +21,14 @@ import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
 import { detectBranch as defaultDetectBranch, detectCommit as defaultDetectCommit, detectCommitMessage as defaultDetectCommitMessage, detectPullRequestNumber as defaultDetectPullRequestNumber, generateBuildNameWithGit as defaultGenerateBuildNameWithGit } from '../utils/git.js';
 import * as defaultOutput from '../utils/output.js';
 import { writeSession as defaultWriteSession } from '../utils/session.js';
+function formatUploadCounts({
+  total,
+  uploaded,
+  reused,
+  failed
+}) {
+  return `${total} captured, ${uploaded} uploaded, ${reused} reused, ${failed} failed`;
+}
 export async function resolveBuildDisplayUrl({
   result,
   config,
@@ -68,7 +81,9 @@ function buildContextCommand(buildId, {
  * @param {string} testCommand - Test command to execute
  * @param {Object} options - Command options
  * @param {Object} globalOptions - Global CLI options
- * @param {Object} deps - Dependencies for testing
+ * @param {Object} deps - Command services and process hooks.
+ * @returns {Promise<Object>} Command outcome with success, an optional exitCode,
+ * and run results when available.
  */
 export async function runCommand(testCommand, options = {}, globalOptions = {}, deps = {}) {
   let {
@@ -321,6 +336,33 @@ export async function runCommand(testCommand, options = {}, globalOptions = {},
       if (result.buildId) {
         buildId = result.buildId;
       }
+      if (result.uploads?.failed > 0) {
+        let message = `${result.uploads.failed} screenshot(s) failed to upload. Visual testing is incomplete.`;
+        if (globalOptions.json) {
+          output.data({
+            buildId: result.buildId,
+            status: 'incomplete',
+            screenshotsCaptured: result.screenshotsCaptured,
+            uploads: result.uploads,
+            error: {
+              code: 'SCREENSHOT_UPLOAD_FAILED',
+              message
+            },
+            url: result.url,
+            exitCode: 0
+          });
+        } else {
+          output.warn(message);
+          output.print(`Screenshots: ${formatUploadCounts(result.uploads)}`);
+          if (result.url) output.info(`Results: ${result.url}`);
+        }
+        output.cleanup();
+        return {
+          success: true,
+          exitCode: 0,
+          result
+        };
+      }
 
       // JSON output mode - output structured data and exit
       if (globalOptions.json && !runOptions.wait) {
@@ -336,6 +378,9 @@ export async function runCommand(testCommand, options = {}, globalOptions = {},
           status: 'completed',
           url: displayUrl,
           screenshotsCaptured: result.screenshotsCaptured || 0,
+          ...(result.uploads ? {
+            uploads: result.uploads
+          } : {}),
           executionTimeMs,
           git: {
             branch,
@@ -362,7 +407,8 @@ export async function runCommand(testCommand, options = {}, globalOptions = {},
       if (result.buildId && !globalOptions.json) {
         output.blank();
         let colors = output.getColors();
-        output.print(`  ${colors.brand.textTertiary('Screenshots')}  ${colors.white(result.screenshotsCaptured)}`);
+        let screenshotSummary = result.uploads ? formatUploadCounts(result.uploads) : result.screenshotsCaptured;
+        output.print(`  ${colors.brand.textTertiary('Screenshots')}  ${colors.white(screenshotSummary)}`);
         let displayUrl = await resolveBuildDisplayUrl({
           result,
           config,
@@ -392,6 +438,9 @@ export async function runCommand(testCommand, options = {}, globalOptions = {},
           output.data({
             buildId: buildId || null,
             status: 'failed',
+            ...(error.uploads ? {
+              uploads: error.uploads
+            } : {}),
             error: {
               code: error.code,
               message: error.message
@@ -479,6 +528,9 @@ export async function runCommand(testCommand, options = {}, globalOptions = {},
             status: buildResult.status,
             url: displayUrl,
             screenshotsCaptured: result.screenshotsCaptured || 0,
+            ...(result.uploads ? {
+              uploads: result.uploads
+            } : {}),
             executionTimeMs,
             git: {
               branch,