@vizzly-testing/cli 0.19.2 → 0.20.0

package/dist/client/index.js

@@ -120,7 +120,6 @@ function createSimpleClient(serverUrl) {
             name,
             image,
             properties: options,
-            threshold: options.threshold || 0,
             fullPage: options.fullPage || false
           }),
           signal: controller.signal

package/dist/services/tdd-service.js

@@ -142,7 +142,7 @@ export class TddService {
     this.comparisons = [];
     this.threshold = config.comparison?.threshold || 2.0;
     this.minClusterSize = config.comparison?.minClusterSize ?? 2; // Filter single-pixel noise by default
-    this.signatureProperties = []; // Custom properties from project's baseline_signature_properties
+    this.signatureProperties = config.signatureProperties ?? []; // Custom properties from project's baseline_signature_properties
 
     // Check if we're in baseline update mode
     if (this.setBaseline) {
@@ -748,7 +748,7 @@ export class TddService {
       this.threshold = metadata.threshold || this.threshold;
 
       // Restore signature properties from saved metadata (for variant support)
-      this.signatureProperties = metadata.signatureProperties || [];
+      this.signatureProperties = metadata.signatureProperties || this.signatureProperties;
       if (this.signatureProperties.length > 0) {
         output.debug('tdd', `loaded signature properties: ${this.signatureProperties.join(', ')}`);
       }
@@ -857,16 +857,22 @@ export class TddService {
 
     // Baseline exists - compare with it
     try {
+      // Per-screenshot threshold/minClusterSize override support
+      // Priority: screenshot-level > config > defaults
+      // Validate overrides before using them
+      const effectiveThreshold = typeof validatedProperties.threshold === 'number' && validatedProperties.threshold >= 0 ? validatedProperties.threshold : this.threshold;
+      const effectiveMinClusterSize = Number.isInteger(validatedProperties.minClusterSize) && validatedProperties.minClusterSize >= 1 ? validatedProperties.minClusterSize : this.minClusterSize;
+
       // Try to compare - honeydiff will throw if dimensions don't match
       const result = await compare(baselineImagePath, currentImagePath, {
-        threshold: this.threshold,
+        threshold: effectiveThreshold,
         // CIEDE2000 Delta E (2.0 = recommended default)
         antialiasing: true,
         diffPath: diffImagePath,
         overwrite: true,
         includeClusters: true,
         // Enable spatial clustering analysis
-        minClusterSize: this.minClusterSize // Filter single-pixel noise (default: 2)
+        minClusterSize: effectiveMinClusterSize // Filter single-pixel noise (default: 2)
       });
       if (!result.isDifferent) {
         // Images match
@@ -879,7 +885,8 @@ export class TddService {
           diff: null,
           properties: validatedProperties,
           signature,
-          threshold: this.threshold,
+          threshold: effectiveThreshold,
+          minClusterSize: effectiveMinClusterSize,
           // Include honeydiff metrics even for passing comparisons
           totalPixels: result.totalPixels,
           aaPixelsIgnored: result.aaPixelsIgnored,
@@ -925,7 +932,8 @@ export class TddService {
           diff: diffImagePath,
           properties: validatedProperties,
           signature,
-          threshold: this.threshold,
+          threshold: effectiveThreshold,
+          minClusterSize: effectiveMinClusterSize,
           diffPercentage: result.diffPercentage,
           diffCount: result.diffPixels,
           reason: isHotspotFiltered ? 'hotspot-filtered' : 'pixel-diff',

package/dist/services/test-runner.js

@@ -189,10 +189,11 @@ export class TestRunner extends EventEmitter {
         };
 
         // Only include metadata if we have meaningful config to send
-        if (this.config.comparison?.threshold != null) {
+        if (this.config.comparison?.threshold != null || this.config.comparison?.minClusterSize != null) {
           buildPayload.metadata = {
             comparison: {
-              threshold: this.config.comparison.threshold
+              threshold: this.config.comparison.threshold,
+              minClusterSize: this.config.comparison.minClusterSize
             }
           };
         }

package/dist/types/client.d.ts

@@ -23,10 +23,11 @@
  * await vizzlyScreenshot('homepage', './screenshots/homepage.png');
  *
  * @example
- * // With properties and threshold
+ * // With properties and comparison settings
  * await vizzlyScreenshot('checkout-form', screenshot, {
  *   properties: { browser: 'chrome', viewport: '1920x1080' },
- *   threshold: 5
+ *   threshold: 5,
+ *   minClusterSize: 10
  * });
  */
 export function vizzlyScreenshot(
@@ -35,6 +36,7 @@ export function vizzlyScreenshot(
   options?: {
     properties?: Record<string, unknown>;
     threshold?: number;
+    minClusterSize?: number;
     fullPage?: boolean;
   }
 ): Promise<void>;

package/dist/types/index.d.ts

@@ -54,6 +54,8 @@ export interface VizzlyConfig {
   upload?: UploadConfig;
   comparison?: ComparisonConfig;
   tdd?: TddConfig;
+  /** Custom properties for baseline matching (e.g., ['theme', 'device']) */
+  signatureProperties?: string[];
   plugins?: string[];
   parallelId?: string;
   baselineBuildId?: string;
@@ -72,6 +74,7 @@ export interface VizzlyConfig {
 export interface ScreenshotOptions {
   properties?: Record<string, unknown>;
   threshold?: number;
+  minClusterSize?: number;
   fullPage?: boolean;
   buildId?: string;
 }
@@ -97,6 +100,7 @@ export interface ComparisonResult {
   properties: Record<string, unknown>;
   signature: string;
   threshold?: number;
+  minClusterSize?: number;
   diffPercentage?: number;
   diffCount?: number;
   error?: string;
@@ -465,6 +469,7 @@ export function vizzlyScreenshot(
   options?: {
     properties?: Record<string, unknown>;
     threshold?: number;
+    minClusterSize?: number;
     fullPage?: boolean;
   }
 ): Promise<void>;

package/dist/utils/config-schema.js

@@ -36,9 +36,11 @@ const uploadSchema = z.object({
 /**
  * Comparison configuration schema
  * threshold: CIEDE2000 Delta E units (0.0 = exact, 1.0 = JND, 2.0 = recommended, 3.0+ = permissive)
+ * minClusterSize: pixels (1 = exact)
  */
 const comparisonSchema = z.object({
-  threshold: z.number().min(0).default(2.0)
+  threshold: z.number().min(0).default(2.0),
+  minClusterSize: z.int().min(1).default(2)
 });
 
 /**
@@ -70,11 +72,13 @@ export const vizzlyConfigSchema = z.object({
     timeout: 30000
   }),
   comparison: comparisonSchema.default({
-    threshold: 2.0
+    threshold: 2.0,
+    minClusterSize: 2
   }),
   tdd: tddSchema.default({
     openReport: false
   }),
+  signatureProperties: z.array(z.string()).default([]),
   plugins: z.array(z.string()).default([]),
   // Additional optional fields
   parallelId: z.string().optional(),
@@ -99,7 +103,8 @@ export const vizzlyConfigSchema = z.object({
     timeout: 30000
   },
   comparison: {
-    threshold: 2.0
+    threshold: 2.0,
+    minClusterSize: 2
   },
   tdd: {
     openReport: false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.19.2",
+  "version": "0.20.0",
   "description": "Visual review platform for UI developers and designers",
   "keywords": [
     "visual-testing",