@vizzly-testing/cli 0.4.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) {
@@ -114,13 +133,12 @@ export class TestRunner extends BaseService {
       const apiService = await this.createApiService();
       if (apiService) {
         const buildResult = await apiService.createBuild({
-          build: {
-            name: options.buildName || `Test Run ${new Date().toISOString()}`,
-            branch: options.branch || 'main',
-            environment: options.environment || 'test',
-            commit_sha: options.commit,
-            commit_message: options.message
-          }
+          name: options.buildName || `Test Run ${new Date().toISOString()}`,
+          branch: options.branch || 'main',
+          environment: options.environment || 'test',
+          commit_sha: options.commit,
+          commit_message: options.message,
+          github_pull_request_number: options.pullRequestNumber
         });
         this.logger.debug(`Build created with ID: ${buildResult.id}`);
 
@@ -154,10 +172,13 @@ export class TestRunner extends BaseService {
     }
     try {
       if (isTddMode) {
-        // TDD mode: use server handler to finalize
+        // TDD mode: use server handler to finalize (local-only)
         if (this.serverManager.server?.finishBuild) {
           await this.serverManager.server.finishBuild(buildId);
           this.logger.debug(`TDD build ${buildId} finalized with success: ${success}`);
+        } else {
+          // In TDD mode without a server, just log that finalization is skipped
+          this.logger.debug(`TDD build ${buildId} finalization skipped (local-only mode)`);
         }
       } else {
         // API mode: use API service to update build status
@@ -188,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();
@@ -198,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/services/uploader.js

@@ -50,6 +50,7 @@ export function createUploader({
     message,
     environment = 'production',
     threshold,
+    pullRequestNumber,
     onProgress = () => {}
   }) {
     try {
@@ -96,10 +97,11 @@ export function createUploader({
       const buildInfo = {
         name: buildName || `Upload ${new Date().toISOString()}`,
         branch: branch || (await getDefaultBranch()) || 'main',
-        commitSha: commit,
-        commitMessage: message,
+        commit_sha: commit,
+        commit_message: message,
         environment,
-        threshold
+        threshold,
+        github_pull_request_number: pullRequestNumber
       };
       const build = await api.createBuild(buildInfo);
       const buildId = build.id;

package/dist/types/commands/tdd.d.ts

@@ -3,10 +3,11 @@
  * @param {string} testCommand - Test command to execute
  * @param {Object} options - Command options
  * @param {Object} globalOptions - Global CLI options
+ * @returns {Promise<{result: Object, cleanup: Function}>} Result and cleanup function
  */
 export function tddCommand(testCommand: string, options?: any, globalOptions?: any): Promise<{
-    success: boolean;
-    exitCode: number;
+    result: any;
+    cleanup: Function;
 }>;
 /**
  * Validate TDD options

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/services/uploader.d.ts

@@ -8,7 +8,7 @@ export function createUploader({ apiKey, apiUrl, userAgent, command, upload: upl
     command: any;
     upload?: {};
 }, options?: {}): {
-    upload: ({ screenshotsDir, buildName, branch, commit, message, environment, threshold, onProgress, }: {
+    upload: ({ screenshotsDir, buildName, branch, commit, message, environment, threshold, pullRequestNumber, onProgress, }: {
         screenshotsDir: any;
         buildName: any;
         branch: any;
@@ -16,6 +16,7 @@ export function createUploader({ apiKey, apiUrl, userAgent, command, upload: upl
         message: any;
         environment?: string;
         threshold: any;
+        pullRequestNumber: any;
         onProgress?: () => void;
     }) => Promise<{
         success: boolean;

package/dist/types/utils/ci-env.d.ts

@@ -0,0 +1,55 @@
+/**
+ * CI Environment Detection
+ *
+ * Generic functions to extract git and PR information from any CI provider
+ */
+/**
+ * Get the branch name from CI environment variables
+ * @returns {string|null} Branch name or null if not available
+ */
+export function getBranch(): string | null;
+/**
+ * Get the commit SHA from CI environment variables
+ * @returns {string|null} Commit SHA or null if not available
+ */
+export function getCommit(): string | null;
+/**
+ * Get the commit message from CI environment variables
+ * @returns {string|null} Commit message or null if not available
+ */
+export function getCommitMessage(): string | null;
+/**
+ * Get the pull request number from CI environment variables
+ * @returns {number|null} PR number or null if not available/not a PR
+ */
+export function getPullRequestNumber(): number | null;
+/**
+ * Get the PR head SHA from CI environment variables
+ * @returns {string|null} PR head SHA or null if not available
+ */
+export function getPullRequestHeadSha(): string | null;
+/**
+ * Get the PR base SHA from CI environment variables
+ * @returns {string|null} PR base SHA or null if not available
+ */
+export function getPullRequestBaseSha(): string | null;
+/**
+ * Get the PR head ref (branch) from CI environment variables
+ * @returns {string|null} PR head ref or null if not available
+ */
+export function getPullRequestHeadRef(): string | null;
+/**
+ * Get the PR base ref (target branch) from CI environment variables
+ * @returns {string|null} PR base ref or null if not available
+ */
+export function getPullRequestBaseRef(): string | null;
+/**
+ * Check if we're currently in a pull request context
+ * @returns {boolean} True if in a PR context
+ */
+export function isPullRequest(): boolean;
+/**
+ * Get the CI provider name
+ * @returns {string} CI provider name or 'unknown'
+ */
+export function getCIProvider(): string;

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/git.d.ts

@@ -9,6 +9,13 @@ export function generateBuildName(): string;
  * @returns {Promise<string|null>} Commit message or null if not available
  */
 export function getCommitMessage(cwd?: string): Promise<string | null>;
+/**
+ * Detect commit message with override and environment variable support
+ * @param {string} override - Commit message override from CLI
+ * @param {string} cwd - Working directory
+ * @returns {Promise<string|null>} Commit message or null if not available
+ */
+export function detectCommitMessage(override?: string, cwd?: string): Promise<string | null>;
 /**
  * Check if the working directory is a git repository
  * @param {string} cwd - Working directory
@@ -42,3 +49,8 @@ export function detectCommit(override?: string, cwd?: string): Promise<string |
  * @returns {Promise<string>}
  */
 export function generateBuildNameWithGit(override?: string, cwd?: string): Promise<string>;
+/**
+ * Detect pull request number from CI environment
+ * @returns {number|null} Pull request number or null if not in PR context
+ */
+export function detectPullRequestNumber(): number | null;

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;