@vizzly-testing/cli 0.5.0 → 0.6.0

package/dist/services/test-runner.js

@@ -39,10 +39,11 @@ export class TestRunner extends BaseService {
         screenshotsCaptured: 0
       };
     }
+    let buildUrl = null;
+    let screenshotCount = 0;
+    let testSuccess = false;
+    let testError = null;
     try {
-      let buildUrl = null;
-      let screenshotCount = 0;
-
       // Create build based on mode
       buildId = await this.createBuild(options, tdd);
       if (!tdd && buildId) {
@@ -62,7 +63,7 @@ export class TestRunner extends BaseService {
       }
 
       // Start server with appropriate handler
-      await this.serverManager.start(buildId, tdd);
+      await this.serverManager.start(buildId, tdd, options.setBaseline);
 
       // Forward server events
       if (this.serverManager.server?.emitter) {
@@ -78,28 +79,46 @@ export class TestRunner extends BaseService {
         VIZZLY_ENABLED: 'true',
         VIZZLY_SET_BASELINE: options.setBaseline || options['set-baseline'] ? 'true' : 'false'
       };
-      await this.executeTestCommand(testCommand, env);
-
-      // Finalize build
-      const executionTime = Date.now() - startTime;
-      await this.finalizeBuild(buildId, tdd, true, executionTime);
-      return {
-        buildId: buildId,
-        url: buildUrl,
-        testsPassed: 1,
-        testsFailed: 0,
-        screenshotsCaptured: screenshotCount
-      };
+      try {
+        await this.executeTestCommand(testCommand, env);
+        testSuccess = true;
+      } catch (error) {
+        testError = error;
+        testSuccess = false;
+      }
     } catch (error) {
-      this.logger.error('Test run failed:', error);
-
-      // Finalize build on failure
-      const executionTime = Date.now() - startTime;
-      await this.finalizeBuild(buildId, tdd, false, executionTime);
-      throw error;
+      // Error in setup phase
+      testError = error;
+      testSuccess = false;
     } finally {
-      await this.serverManager.stop();
+      // Always finalize the build and stop the server
+      const executionTime = Date.now() - startTime;
+      if (buildId) {
+        try {
+          await this.finalizeBuild(buildId, tdd, testSuccess, executionTime);
+        } catch (finalizeError) {
+          this.logger.error('Failed to finalize build:', finalizeError);
+        }
+      }
+      try {
+        await this.serverManager.stop();
+      } catch (stopError) {
+        this.logger.error('Failed to stop server:', stopError);
+      }
     }
+
+    // If there was a test error, throw it now (after cleanup)
+    if (testError) {
+      this.logger.error('Test run failed:', testError);
+      throw testError;
+    }
+    return {
+      buildId: buildId,
+      url: buildUrl,
+      testsPassed: testSuccess ? 1 : 0,
+      testsFailed: testSuccess ? 0 : 1,
+      screenshotsCaptured: screenshotCount
+    };
   }
   async createBuild(options, tdd) {
     if (tdd) {
@@ -190,8 +209,11 @@ export class TestRunner extends BaseService {
       this.testProcess.on('error', error => {
         reject(new VizzlyError(`Failed to run test command: ${error.message}`), 'TEST_COMMAND_FAILED');
       });
-      this.testProcess.on('exit', code => {
-        if (code !== 0) {
+      this.testProcess.on('exit', (code, signal) => {
+        // If process was killed by SIGINT, treat as interruption
+        if (signal === 'SIGINT') {
+          reject(new VizzlyError('Test command was interrupted', 'TEST_COMMAND_INTERRUPTED'));
+        } else if (code !== 0) {
           reject(new VizzlyError(`Test command exited with code ${code}`, 'TEST_COMMAND_FAILED'));
         } else {
           resolve();
@@ -200,8 +222,13 @@ export class TestRunner extends BaseService {
     });
   }
   async cancel() {
-    if (this.testProcess) {
-      this.testProcess.kill('SIGTERM');
+    if (this.testProcess && !this.testProcess.killed) {
+      this.testProcess.kill('SIGKILL');
+    }
+
+    // Stop server manager if running
+    if (this.serverManager) {
+      await this.serverManager.stop();
     }
   }
 }

package/dist/types/server/handlers/tdd-handler.d.ts

@@ -1,7 +1,18 @@
-export function createTddHandler(config: any, workingDir: any, baselineBuild: any, baselineComparison: any): {
+export function createTddHandler(config: any, workingDir: any, baselineBuild: any, baselineComparison: any, setBaseline?: boolean): {
     initialize: () => Promise<void>;
     registerBuild: (buildId: any) => void;
     handleScreenshot: (buildId: any, name: any, image: any, properties?: {}) => Promise<{
+        statusCode: number;
+        body: {
+            error: string;
+            details: any;
+            tddMode: boolean;
+            comparison?: undefined;
+            status?: undefined;
+            message?: undefined;
+            success?: undefined;
+        };
+    } | {
         statusCode: number;
         body: {
             error: string;
@@ -12,6 +23,8 @@ export function createTddHandler(config: any, workingDir: any, baselineBuild: an
                 baseline: any;
                 current: any;
                 diff: any;
+                diffPercentage: any;
+                threshold: any;
             };
             tddMode: boolean;
             status?: undefined;
@@ -29,6 +42,8 @@ export function createTddHandler(config: any, workingDir: any, baselineBuild: an
                 baseline: any;
                 current: any;
                 diff?: undefined;
+                diffPercentage?: undefined;
+                threshold?: undefined;
             };
             tddMode: boolean;
             error?: undefined;
@@ -56,6 +71,8 @@ export function createTddHandler(config: any, workingDir: any, baselineBuild: an
                 baseline?: undefined;
                 current?: undefined;
                 diff?: undefined;
+                diffPercentage?: undefined;
+                threshold?: undefined;
             };
             tddMode: boolean;
             error?: undefined;

package/dist/types/services/html-report-generator.d.ts

@@ -0,0 +1,52 @@
+export class HtmlReportGenerator {
+    constructor(workingDir: any, config: any);
+    workingDir: any;
+    config: any;
+    reportDir: string;
+    reportPath: string;
+    cssPath: string;
+    /**
+     * Sanitize HTML content to prevent XSS attacks
+     * @param {string} text - Text to sanitize
+     * @returns {string} Sanitized text
+     */
+    sanitizeHtml(text: string): string;
+    /**
+     * Sanitize build info object
+     * @param {Object} buildInfo - Build information to sanitize
+     * @returns {Object} Sanitized build info
+     */
+    sanitizeBuildInfo(buildInfo?: any): any;
+    /**
+     * Generate HTML report from TDD results
+     * @param {Object} results - TDD comparison results
+     * @param {Object} buildInfo - Build information
+     * @returns {string} Path to generated report
+     */
+    generateReport(results: any, buildInfo?: any): string;
+    /**
+     * Process comparison data for HTML report
+     * @param {Object} comparison - Comparison object
+     * @returns {Object} Processed comparison data
+     */
+    processComparison(comparison: any): any;
+    /**
+     * Get relative path from report directory to image file
+     * @param {string} imagePath - Absolute path to image
+     * @param {string} reportDir - Report directory path
+     * @returns {string|null} Relative path or null if invalid
+     */
+    getRelativePath(imagePath: string, reportDir: string): string | null;
+    /**
+     * Generate the complete HTML template
+     * @param {Object} data - Report data
+     * @returns {string} HTML content
+     */
+    generateHtmlTemplate(data: any): string;
+    /**
+     * Generate HTML for a single comparison
+     * @param {Object} comparison - Comparison data
+     * @returns {string} HTML content
+     */
+    generateComparisonHtml(comparison: any): string;
+}

package/dist/types/services/server-manager.d.ts

@@ -9,6 +9,17 @@ export class ServerManager extends BaseService {
         initialize: () => Promise<void>;
         registerBuild: (buildId: any) => void;
         handleScreenshot: (buildId: any, name: any, image: any, properties?: {}) => Promise<{
+            statusCode: number;
+            body: {
+                error: string;
+                details: any;
+                tddMode: boolean;
+                comparison?: undefined;
+                status?: undefined;
+                message?: undefined;
+                success?: undefined;
+            };
+        } | {
             statusCode: number;
             body: {
                 error: string;
@@ -19,6 +30,8 @@ export class ServerManager extends BaseService {
                     baseline: any;
                     current: any;
                     diff: any;
+                    diffPercentage: any;
+                    threshold: any;
                 };
                 tddMode: boolean;
                 status?: undefined;
@@ -36,6 +49,8 @@ export class ServerManager extends BaseService {
                     baseline: any;
                     current: any;
                     diff?: undefined;
+                    diffPercentage?: undefined;
+                    threshold?: undefined;
                 };
                 tddMode: boolean;
                 error?: undefined;
@@ -63,6 +78,8 @@ export class ServerManager extends BaseService {
                     baseline?: undefined;
                     current?: undefined;
                     diff?: undefined;
+                    diffPercentage?: undefined;
+                    threshold?: undefined;
                 };
                 tddMode: boolean;
                 error?: undefined;
@@ -139,9 +156,10 @@ export class ServerManager extends BaseService {
         cleanup: () => void;
     };
     emitter: EventEmitter<[never]>;
-    start(buildId?: any, tddMode?: boolean): Promise<void>;
+    start(buildId?: any, tddMode?: boolean, setBaseline?: boolean): Promise<void>;
     buildId: any;
     tddMode: boolean;
+    setBaseline: boolean;
     createApiService(): Promise<import("./api-service.js").ApiService>;
     get server(): {
         emitter: EventEmitter<[never]>;

package/dist/types/services/tdd-service.d.ts

@@ -3,8 +3,9 @@
  */
 export function createTDDService(config: any, options?: {}): TddService;
 export class TddService {
-    constructor(config: any, workingDir?: string);
+    constructor(config: any, workingDir?: string, setBaseline?: boolean);
     config: any;
+    setBaseline: boolean;
     api: ApiService;
     workingDir: string;
     baselinePath: string;
@@ -14,6 +15,11 @@ export class TddService {
     comparisons: any[];
     threshold: any;
     downloadBaselines(environment?: string, branch?: any, buildId?: any, comparisonId?: any): Promise<any>;
+    /**
+     * Handle local baseline logic (either load existing or prepare for new baselines)
+     * @returns {Promise<Object|null>} Baseline data or null if no local baselines exist
+     */
+    handleLocalBaselines(): Promise<any | null>;
     loadBaseline(): Promise<any>;
     compareScreenshot(name: any, imageBuffer: any, properties?: {}): Promise<{
         name: any;
@@ -32,7 +38,7 @@ export class TddService {
         comparisons: any[];
         baseline: any;
     };
-    printResults(): {
+    printResults(): Promise<{
         total: number;
         passed: number;
         failed: number;
@@ -40,12 +46,27 @@ export class TddService {
         errors: number;
         comparisons: any[];
         baseline: any;
-    };
+    }>;
+    /**
+     * Generate HTML report for TDD results
+     * @param {Object} results - TDD comparison results
+     */
+    generateHtmlReport(results: any): Promise<string>;
+    /**
+     * Open HTML report in default browser
+     * @param {string} reportPath - Path to HTML report
+     */
+    openReport(reportPath: string): Promise<void>;
     /**
      * Update baselines with current screenshots (accept changes)
      * @returns {number} Number of baselines updated
      */
     updateBaselines(): number;
+    /**
+     * Create a new baseline (used during --set-baseline mode)
+     * @private
+     */
+    private createNewBaseline;
     /**
      * Update a single baseline with current screenshot
      * @private

package/dist/types/utils/config-loader.d.ts

@@ -16,6 +16,9 @@ export function loadConfig(configPath?: any, cliOverrides?: {}): Promise<{
     comparison: {
         threshold: number;
     };
+    tdd: {
+        openReport: boolean;
+    };
     apiKey: string;
     apiUrl: string;
 }>;

package/dist/types/utils/security.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Sanitizes a screenshot name to prevent path traversal and ensure safe file naming
+ * @param {string} name - Original screenshot name
+ * @param {number} maxLength - Maximum allowed length (default: 255)
+ * @returns {string} Sanitized screenshot name
+ */
+export function sanitizeScreenshotName(name: string, maxLength?: number): string;
+/**
+ * Validates that a path stays within the allowed working directory bounds
+ * @param {string} targetPath - Path to validate
+ * @param {string} workingDir - Working directory that serves as the security boundary
+ * @returns {string} Resolved and normalized path if valid
+ * @throws {Error} If path is invalid or outside bounds
+ */
+export function validatePathSecurity(targetPath: string, workingDir: string): string;
+/**
+ * Safely constructs a path within the working directory
+ * @param {string} workingDir - Base working directory
+ * @param {...string} pathSegments - Path segments to join
+ * @returns {string} Safely constructed path
+ * @throws {Error} If resulting path would be outside working directory
+ */
+export function safePath(workingDir: string, ...pathSegments: string[]): string;
+/**
+ * Validates screenshot properties object for safe values
+ * @param {Object} properties - Properties to validate
+ * @returns {Object} Validated properties object
+ */
+export function validateScreenshotProperties(properties?: any): any;

package/dist/utils/config-loader.js

@@ -25,6 +25,10 @@ const DEFAULT_CONFIG = {
   // Comparison Configuration
   comparison: {
     threshold: 0.1
+  },
+  // TDD Configuration
+  tdd: {
+    openReport: false // Whether to auto-open HTML report in browser
   }
 };
 export async function loadConfig(configPath = null, cliOverrides = {}) {
@@ -42,6 +46,9 @@ export async function loadConfig(configPath = null, cliOverrides = {}) {
     },
     comparison: {
       ...DEFAULT_CONFIG.comparison
+    },
+    tdd: {
+      ...DEFAULT_CONFIG.tdd
     }
   };
 

package/dist/utils/security.js

@@ -0,0 +1,154 @@
+/**
+ * Security utilities for path sanitization and validation
+ * Protects against path traversal attacks and ensures safe file operations
+ */
+
+import { resolve, normalize, isAbsolute, join } from 'path';
+import { createServiceLogger } from './logger-factory.js';
+const logger = createServiceLogger('SECURITY');
+
+/**
+ * Sanitizes a screenshot name to prevent path traversal and ensure safe file naming
+ * @param {string} name - Original screenshot name
+ * @param {number} maxLength - Maximum allowed length (default: 255)
+ * @returns {string} Sanitized screenshot name
+ */
+export function sanitizeScreenshotName(name, maxLength = 255) {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new Error('Screenshot name must be a non-empty string');
+  }
+  if (name.length > maxLength) {
+    throw new Error(`Screenshot name exceeds maximum length of ${maxLength} characters`);
+  }
+
+  // Block directory traversal patterns
+  if (name.includes('..') || name.includes('/') || name.includes('\\')) {
+    throw new Error('Screenshot name contains invalid path characters');
+  }
+
+  // Block absolute paths
+  if (isAbsolute(name)) {
+    throw new Error('Screenshot name cannot be an absolute path');
+  }
+
+  // Allow only safe characters: alphanumeric, hyphens, underscores, and dots
+  // Replace other characters with underscores
+  let sanitized = name.replace(/[^a-zA-Z0-9._-]/g, '_');
+
+  // Prevent names that start with dots (hidden files)
+  if (sanitized.startsWith('.')) {
+    sanitized = 'file_' + sanitized;
+  }
+
+  // Ensure we have a valid filename
+  if (sanitized.length === 0 || sanitized === '.' || sanitized === '..') {
+    sanitized = 'unnamed_screenshot';
+  }
+  return sanitized;
+}
+
+/**
+ * Validates that a path stays within the allowed working directory bounds
+ * @param {string} targetPath - Path to validate
+ * @param {string} workingDir - Working directory that serves as the security boundary
+ * @returns {string} Resolved and normalized path if valid
+ * @throws {Error} If path is invalid or outside bounds
+ */
+export function validatePathSecurity(targetPath, workingDir) {
+  if (typeof targetPath !== 'string' || targetPath.length === 0) {
+    throw new Error('Path must be a non-empty string');
+  }
+  if (typeof workingDir !== 'string' || workingDir.length === 0) {
+    throw new Error('Working directory must be a non-empty string');
+  }
+
+  // Normalize and resolve both paths
+  let resolvedWorkingDir = resolve(normalize(workingDir));
+  let resolvedTargetPath = resolve(normalize(targetPath));
+
+  // Ensure the target path starts with the working directory
+  if (!resolvedTargetPath.startsWith(resolvedWorkingDir)) {
+    logger.warn(`Path traversal attempt blocked: ${targetPath} (resolved: ${resolvedTargetPath}) is outside working directory: ${resolvedWorkingDir}`);
+    throw new Error('Path is outside the allowed working directory');
+  }
+  return resolvedTargetPath;
+}
+
+/**
+ * Safely constructs a path within the working directory
+ * @param {string} workingDir - Base working directory
+ * @param {...string} pathSegments - Path segments to join
+ * @returns {string} Safely constructed path
+ * @throws {Error} If resulting path would be outside working directory
+ */
+export function safePath(workingDir, ...pathSegments) {
+  if (pathSegments.length === 0) {
+    return validatePathSecurity(workingDir, workingDir);
+  }
+
+  // Sanitize each path segment
+  let sanitizedSegments = pathSegments.map(segment => {
+    if (typeof segment !== 'string') {
+      throw new Error('Path segment must be a string');
+    }
+
+    // Block directory traversal in segments
+    if (segment.includes('..')) {
+      throw new Error('Path segment contains directory traversal sequence');
+    }
+    return segment;
+  });
+  let targetPath = join(workingDir, ...sanitizedSegments);
+  return validatePathSecurity(targetPath, workingDir);
+}
+
+/**
+ * Validates screenshot properties object for safe values
+ * @param {Object} properties - Properties to validate
+ * @returns {Object} Validated properties object
+ */
+export function validateScreenshotProperties(properties = {}) {
+  if (properties === null || typeof properties !== 'object') {
+    return {};
+  }
+  let validated = {};
+
+  // Validate common properties with safe constraints
+  if (properties.browser && typeof properties.browser === 'string') {
+    try {
+      validated.browser = sanitizeScreenshotName(properties.browser, 50);
+    } catch (error) {
+      // Skip invalid browser names, don't include them
+      logger.warn(`Invalid browser name '${properties.browser}': ${error.message}`);
+    }
+  }
+  if (properties.viewport && typeof properties.viewport === 'object') {
+    let viewport = {};
+    if (typeof properties.viewport.width === 'number' && properties.viewport.width > 0 && properties.viewport.width <= 10000) {
+      viewport.width = Math.floor(properties.viewport.width);
+    }
+    if (typeof properties.viewport.height === 'number' && properties.viewport.height > 0 && properties.viewport.height <= 10000) {
+      viewport.height = Math.floor(properties.viewport.height);
+    }
+    if (Object.keys(viewport).length > 0) {
+      validated.viewport = viewport;
+    }
+  }
+
+  // Allow other safe string properties but sanitize them
+  for (let [key, value] of Object.entries(properties)) {
+    if (key === 'browser' || key === 'viewport') continue; // Already handled
+
+    if (typeof key === 'string' && key.length <= 50 && /^[a-zA-Z0-9_-]+$/.test(key)) {
+      if (typeof value === 'string' && value.length <= 200) {
+        // Store sanitized version of string values
+        validated[key] = value.replace(/[<>&"']/g, ''); // Basic HTML entity prevention
+      } else if (typeof value === 'number' && !isNaN(value) && isFinite(value)) {
+        validated[key] = value;
+      } else if (typeof value === 'boolean') {
+        validated[key] = value;
+      }
+    }
+  }
+  return validated;
+}