@vizzly-testing/cli 0.16.2 → 0.16.4

package/dist/services/api-service.js

@@ -27,7 +27,7 @@ export class ApiService {
     const sdkUserAgent = options.userAgent || getUserAgent();
     this.userAgent = sdkUserAgent ? `${baseUserAgent} ${sdkUserAgent}` : baseUserAgent;
     if (!this.token && !options.allowNoToken) {
-      throw new VizzlyError('No API token provided. Set VIZZLY_TOKEN environment variable or run "vizzly login".');
+      throw new VizzlyError('No API token provided. Set VIZZLY_TOKEN environment variable or link a project in the TDD dashboard.');
     }
   }
 
@@ -101,10 +101,10 @@ export class ApiService {
             // Token refresh failed, fall through to auth error
           }
         }
-        throw new AuthError('Invalid or expired API token. Please run "vizzly login" to authenticate.');
+        throw new AuthError('Invalid or expired API token. Link a project via "vizzly project:select" or set VIZZLY_TOKEN.');
       }
       if (response.status === 401) {
-        throw new AuthError('Invalid or expired API token. Please run "vizzly login" to authenticate.');
+        throw new AuthError('Invalid or expired API token. Link a project via "vizzly project:select" or set VIZZLY_TOKEN.');
       }
       throw new VizzlyError(`API request failed: ${response.status}${errorText ? ` - ${errorText}` : ''} (URL: ${url})`);
     }

package/dist/services/server-manager.js

@@ -6,7 +6,7 @@
 import { createHttpServer } from '../server/http-server.js';
 import { createTddHandler } from '../server/handlers/tdd-handler.js';
 import { createApiHandler } from '../server/handlers/api-handler.js';
-import { writeFileSync, mkdirSync } from 'fs';
+import { writeFileSync, mkdirSync, unlinkSync, existsSync } from 'fs';
 import { join } from 'path';
 export class ServerManager {
   constructor(config, options = {}) {
@@ -85,6 +85,16 @@ export class ServerManager {
         // Don't throw - cleanup errors shouldn't fail the stop process
       }
     }
+
+    // Clean up server.json so the client SDK doesn't try to connect to a dead server
+    try {
+      let serverFile = join(process.cwd(), '.vizzly', 'server.json');
+      if (existsSync(serverFile)) {
+        unlinkSync(serverFile);
+      }
+    } catch {
+      // Non-fatal - cleanup errors shouldn't fail the stop process
+    }
   }
 
   // Expose server interface for compatibility
@@ -94,4 +104,13 @@ export class ServerManager {
       finishBuild: buildId => this.httpServer?.finishBuild?.(buildId)
     };
   }
+
+  /**
+   * Get TDD results (comparisons, screenshot count, etc.)
+   * Only available in TDD mode after tests have run
+   */
+  async getTddResults() {
+    if (!this.tddMode || !this.handler?.getResults) return null;
+    return await this.handler.getResults();
+  }
 }

package/dist/services/tdd-service.js

@@ -13,14 +13,20 @@ import { sanitizeScreenshotName, validatePathSecurity, safePath, validateScreens
 
 /**
  * Generate a screenshot signature for baseline matching
- * Uses same logic as screenshot-identity.js: name + viewport_width + browser
+ * Uses same logic as screenshot-identity.js: name + viewport_width + browser + custom properties
  *
  * Matches backend signature generation which uses:
  * - screenshot.name
  * - screenshot.viewport_width (top-level property)
  * - screenshot.browser (top-level property)
+ * - custom properties from project's baseline_signature_properties setting
+ *
+ * @param {string} name - Screenshot name
+ * @param {Object} properties - Screenshot properties (viewport, browser, metadata, etc.)
+ * @param {Array<string>} customProperties - Custom property names from project settings
+ * @returns {string} Signature like "Login|1920|chrome|iPhone 15 Pro"
  */
-function generateScreenshotSignature(name, properties = {}) {
+function generateScreenshotSignature(name, properties = {}, customProperties = []) {
   let parts = [name];
 
   // Check for viewport_width as top-level property first (backend format)
@@ -40,15 +46,30 @@ function generateScreenshotSignature(name, properties = {}) {
   if (properties.browser) {
     parts.push(properties.browser);
   }
+
+  // Add custom properties in order (matches cloud screenshot-identity.js behavior)
+  for (let propName of customProperties) {
+    // Check multiple locations where property might exist:
+    // 1. Top-level property (e.g., properties.device)
+    // 2. In metadata object (e.g., properties.metadata.device)
+    // 3. In nested metadata.properties (e.g., properties.metadata.properties.device)
+    let value = properties[propName] ?? properties.metadata?.[propName] ?? properties.metadata?.properties?.[propName] ?? '';
+
+    // Normalize: convert to string, trim whitespace
+    parts.push(String(value).trim());
+  }
   return parts.join('|');
 }
 
 /**
  * Create a safe filename from signature
+ * Handles custom property values that may contain spaces or special characters
  */
 function signatureToFilename(signature) {
-  // Replace pipe separators with underscores for filesystem safety
-  return signature.replace(/\|/g, '_');
+  return signature.replace(/\|/g, '_') // pipes to underscores
+  .replace(/\s+/g, '_') // spaces to underscores
+  .replace(/[/\\:*?"<>]/g, '') // remove unsafe filesystem chars
+  .replace(/_+/g, '_'); // collapse multiple underscores
 }
 
 /**
@@ -92,6 +113,7 @@ export class TddService {
     this.baselineData = null;
     this.comparisons = [];
     this.threshold = config.comparison?.threshold || 0.1;
+    this.signatureProperties = []; // Custom properties from project's baseline_signature_properties
 
     // Check if we're in baseline update mode
     if (this.setBaseline) {
@@ -138,6 +160,14 @@ export class TddService {
           throw new Error(`Build ${buildId} not found or API returned null`);
         }
 
+        // Extract signature properties from API response (for variant support)
+        if (apiResponse.signatureProperties && Array.isArray(apiResponse.signatureProperties)) {
+          this.signatureProperties = apiResponse.signatureProperties;
+          if (this.signatureProperties.length > 0) {
+            output.info(`Using custom signature properties: ${this.signatureProperties.join(', ')}`);
+          }
+        }
+
         // Handle wrapped response format
         baselineBuild = apiResponse.build || apiResponse;
         if (!baselineBuild.id) {
@@ -280,8 +310,14 @@ export class TddService {
         }
 
         // Generate signature for baseline matching (same as compareScreenshot)
-        let properties = validateScreenshotProperties(screenshot.metadata || screenshot.properties || {});
-        let signature = generateScreenshotSignature(sanitizedName, properties);
+        // Build properties object with top-level viewport_width and browser
+        // These are returned as top-level fields from the API, not inside metadata
+        let properties = validateScreenshotProperties({
+          viewport_width: screenshot.viewport_width,
+          browser: screenshot.browser,
+          ...(screenshot.metadata || screenshot.properties || {})
+        });
+        let signature = generateScreenshotSignature(sanitizedName, properties, this.signatureProperties);
         let filename = signatureToFilename(signature);
         const imagePath = safePath(this.baselinePath, `${filename}.png`);
 
@@ -381,6 +417,8 @@ export class TddService {
         environment,
         branch,
         threshold: this.threshold,
+        signatureProperties: this.signatureProperties,
+        // Store for TDD comparison
         createdAt: new Date().toISOString(),
         buildInfo: {
           commitSha: baselineBuild.commit_sha,
@@ -396,8 +434,15 @@ export class TddService {
             output.warn(`Screenshot name sanitization failed for '${s.name}': ${error.message}`);
             return null; // Skip invalid screenshots
           }
-          let properties = validateScreenshotProperties(s.metadata || s.properties || {});
-          let signature = generateScreenshotSignature(sanitizedName, properties);
+
+          // Build properties object with top-level viewport_width and browser
+          // These are returned as top-level fields from the API, not inside metadata
+          let properties = validateScreenshotProperties({
+            viewport_width: s.viewport_width,
+            browser: s.browser,
+            ...(s.metadata || s.properties || {})
+          });
+          let signature = generateScreenshotSignature(sanitizedName, properties, this.signatureProperties);
           let filename = signatureToFilename(signature);
           return {
             name: sanitizedName,
@@ -630,8 +675,17 @@ export class TddService {
       });
       let {
         build,
-        screenshots
+        screenshots,
+        signatureProperties
       } = response;
+
+      // Extract signature properties from API response (for variant support)
+      if (signatureProperties && Array.isArray(signatureProperties)) {
+        this.signatureProperties = signatureProperties;
+        if (this.signatureProperties.length > 0) {
+          output.info(`Using custom signature properties: ${this.signatureProperties.join(', ')}`);
+        }
+      }
       if (!screenshots || screenshots.length === 0) {
         output.warn('⚠️  No screenshots found in build');
         return {
@@ -668,8 +722,15 @@ export class TddService {
           errorCount++;
           continue;
         }
-        let properties = validateScreenshotProperties(screenshot.metadata || {});
-        let signature = generateScreenshotSignature(sanitizedName, properties);
+
+        // Build properties object with top-level viewport_width and browser
+        // These are returned as top-level fields from the API, not inside metadata
+        let properties = validateScreenshotProperties({
+          viewport_width: screenshot.viewport_width,
+          browser: screenshot.browser,
+          ...screenshot.metadata
+        });
+        let signature = generateScreenshotSignature(sanitizedName, properties, this.signatureProperties);
         let filename = signatureToFilename(signature);
         let filePath = safePath(this.baselinePath, `${filename}.png`);
 
@@ -724,6 +785,8 @@ export class TddService {
         buildName: build.name,
         branch: build.branch,
         threshold: this.threshold,
+        signatureProperties: this.signatureProperties,
+        // Store for TDD comparison
         screenshots: downloadedScreenshots
       };
       let metadataPath = join(this.baselinePath, 'metadata.json');
@@ -804,6 +867,12 @@ export class TddService {
       const metadata = JSON.parse(readFileSync(metadataPath, 'utf8'));
       this.baselineData = metadata;
       this.threshold = metadata.threshold || this.threshold;
+
+      // Restore signature properties from saved metadata (for variant support)
+      this.signatureProperties = metadata.signatureProperties || [];
+      if (this.signatureProperties.length > 0) {
+        output.debug('tdd', `loaded signature properties: ${this.signatureProperties.join(', ')}`);
+      }
       return metadata;
     } catch (error) {
       output.error(`❌ Failed to load baseline metadata: ${error.message}`);
@@ -833,8 +902,8 @@ export class TddService {
       validatedProperties.viewport_width = validatedProperties.viewport.width;
     }
 
-    // Generate signature for baseline matching (name + viewport_width + browser)
-    const signature = generateScreenshotSignature(sanitizedName, validatedProperties);
+    // Generate signature for baseline matching (name + viewport_width + browser + custom props)
+    const signature = generateScreenshotSignature(sanitizedName, validatedProperties, this.signatureProperties);
     const filename = signatureToFilename(signature);
     const currentImagePath = safePath(this.currentPath, `${filename}.png`);
     const baselineImagePath = safePath(this.baselinePath, `${filename}.png`);
@@ -1227,7 +1296,7 @@ export class TddService {
         continue;
       }
       let validatedProperties = validateScreenshotProperties(comparison.properties || {});
-      let signature = generateScreenshotSignature(sanitizedName, validatedProperties);
+      let signature = generateScreenshotSignature(sanitizedName, validatedProperties, this.signatureProperties);
       let filename = signatureToFilename(signature);
       const baselineImagePath = safePath(this.baselinePath, `${filename}.png`);
       try {
@@ -1291,7 +1360,7 @@ export class TddService {
     }
 
     // Generate signature for this screenshot
-    let signature = generateScreenshotSignature(name, properties || {});
+    let signature = generateScreenshotSignature(name, properties || {}, this.signatureProperties);
 
     // Add screenshot to baseline metadata
     const screenshotEntry = {
@@ -1348,7 +1417,7 @@ export class TddService {
     }
 
     // Generate signature for this screenshot
-    let signature = generateScreenshotSignature(name, properties || {});
+    let signature = generateScreenshotSignature(name, properties || {}, this.signatureProperties);
 
     // Add screenshot to baseline metadata
     const screenshotEntry = {
@@ -1403,7 +1472,7 @@ export class TddService {
     }
     const sanitizedName = comparison.name;
     let properties = comparison.properties || {};
-    let signature = generateScreenshotSignature(sanitizedName, properties);
+    let signature = generateScreenshotSignature(sanitizedName, properties, this.signatureProperties);
     let filename = signatureToFilename(signature);
 
     // Find the current screenshot file

package/dist/services/test-runner.js

@@ -112,8 +112,25 @@ export class TestRunner extends EventEmitter {
       // Error in setup phase
       testError = error;
       testSuccess = false;
-    } finally {
-      // Always finalize the build and stop the server
+    }
+
+    // Get TDD results before stopping the server (comparisons, screenshot count)
+    let tddResults = null;
+    if (tdd) {
+      try {
+        tddResults = await this.serverManager.getTddResults();
+        if (tddResults) {
+          screenshotCount = tddResults.total || 0;
+        }
+      } catch (tddError) {
+        output.debug('tdd', 'failed to get results', {
+          error: tddError.message
+        });
+      }
+    }
+
+    // Always finalize the build and stop the server (cleanup phase)
+    try {
       const executionTime = Date.now() - startTime;
       if (buildId) {
         try {
@@ -127,6 +144,8 @@ export class TestRunner extends EventEmitter {
       if (!tdd && this.serverManager.server?.getScreenshotCount) {
         screenshotCount = this.serverManager.server.getScreenshotCount(buildId) || 0;
       }
+    } finally {
+      // Always stop the server, even if finalization fails
       try {
         await this.serverManager.stop();
       } catch (stopError) {
@@ -144,7 +163,9 @@ export class TestRunner extends EventEmitter {
       url: buildUrl,
       testsPassed: testSuccess ? 1 : 0,
       testsFailed: testSuccess ? 0 : 1,
-      screenshotsCaptured: screenshotCount
+      screenshotsCaptured: screenshotCount,
+      comparisons: tddResults?.comparisons || null,
+      failed: (tddResults?.failed || 0) > 0
     };
   }
   async createBuild(options, tdd) {

package/dist/utils/config-loader.js

@@ -2,7 +2,7 @@ import { cosmiconfigSync } from 'cosmiconfig';
 import { resolve } from 'path';
 import { getApiToken, getApiUrl, getParallelId } from './environment-config.js';
 import { validateVizzlyConfigWithDefaults } from './config-schema.js';
-import { getAccessToken, getProjectMapping } from './global-config.js';
+import { getProjectMapping } from './global-config.js';
 import * as output from './output.js';
 let DEFAULT_CONFIG = {
   // API Configuration
@@ -98,14 +98,6 @@ export async function loadConfig(configPath = null, cliOverrides = {}) {
     }
   }
 
-  // 3.5. Check global config for user access token (if no CLI flag)
-  if (!config.apiKey && !cliOverrides.token) {
-    let globalToken = await getAccessToken();
-    if (globalToken) {
-      config.apiKey = globalToken;
-    }
-  }
-
   // 4. Override with environment variables (higher priority than fallbacks)
   let envApiKey = getApiToken();
   let envApiUrl = getApiUrl();

package/docs/tdd-mode.md

@@ -388,6 +388,62 @@ rm -rf .vizzly/baselines/
 npx vizzly tdd run "npm test"
 ```
 
+## Baseline Signature Properties
+
+Vizzly matches screenshots to baselines using a **signature**:
+
+```
+name | viewport_width | browser
+```
+
+For example: `homepage|1920|chromium`
+
+### Custom Properties vs Baseline Signature Properties
+
+You can pass custom properties when capturing screenshots:
+
+```javascript
+await vizzlyScreenshot('dashboard', screenshot, {
+  theme: 'dark',
+  locale: 'en-US',
+  mobile: true
+});
+```
+
+By default, these properties help you organize and filter in the dashboard—they don't affect baseline matching. Two screenshots with the same name but different `theme` values would match the same baseline.
+
+### Making Properties Affect Matching
+
+To create separate baselines for different variants, configure **Baseline Signature Properties** in your project settings:
+
+1. Go to your project on [app.vizzly.dev](https://app.vizzly.dev)
+2. Navigate to **Settings** → **Baseline Signature Properties**
+3. Add the property names (e.g., `theme`, `mobile`)
+
+With `theme` configured:
+
+```
+dashboard|1920|chromium|dark    → separate baseline
+dashboard|1920|chromium|light   → separate baseline
+```
+
+### TDD Mode Support
+
+When you download cloud baselines, the CLI automatically:
+
+1. Fetches your project's baseline signature properties
+2. Downloads baselines with variant-aware filenames
+3. Uses matching signatures during comparison
+
+This keeps TDD mode behavior consistent with cloud comparisons.
+
+### Quick Reference
+
+| Type | Purpose | Affects Matching? |
+|------|---------|-------------------|
+| Custom Properties | Organize and filter in dashboard | No |
+| Baseline Signature Properties | Create separate baselines per variant | Yes |
+
 ## Advanced Usage
 
 ### Conditional TDD Mode

package/package.json

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