@vizzly-testing/cli 0.4.0 → 0.6.0

package/README.md

@@ -123,13 +123,19 @@ For local visual testing with immediate feedback, use the dedicated `tdd` comman
 # First run - creates local baselines
 vizzly tdd "npm test"
 
-# Make changes and test - fails if visual differences detected  
+# Make changes and test - fails if visual differences detected
 vizzly tdd "npm test"
 
 # Accept changes as new baseline
 vizzly tdd "npm test" --set-baseline
 ```
 
+**Interactive HTML Report:** Each TDD run generates a detailed HTML report with visual comparison tools:
+- **Overlay mode** - Toggle between baseline and current screenshots
+- **Side-by-side mode** - Compare baseline and current images horizontally
+- **Onion skin mode** - Drag to reveal differences interactively
+- **Toggle mode** - Click to switch between baseline and current
+
 **TDD Command Options:**
 - `--set-baseline` - Accept current screenshots as new baseline
 - `--baseline-build <id>` - Use specific build as baseline (requires API token)
@@ -203,25 +209,25 @@ export default {
   // API configuration
   // Set VIZZLY_TOKEN environment variable or uncomment and set here:
   // apiToken: 'your-token-here',
-  
+
   // Screenshot configuration
   screenshots: {
     directory: './screenshots',
     formats: ['png']
   },
-  
+
   // Server configuration
   server: {
     port: 47392,
     screenshotPath: '/screenshot'
   },
-  
+
   // Comparison configuration
   comparison: {
     threshold: 0.1,
     ignoreAntialiasing: true
   },
-  
+
   // Upload configuration
   upload: {
     concurrency: 5,
@@ -277,6 +283,10 @@ For CI/CD pipelines, use the `--wait` flag to wait for visual comparison results
   run: npx vizzly run "npm test" --wait
   env:
     VIZZLY_TOKEN: ${{ secrets.VIZZLY_TOKEN }}
+    # Optional: Provide correct git information from GitHub context
+    VIZZLY_COMMIT_MESSAGE: ${{ github.event.pull_request.head.commit.message || github.event.head_commit.message }}
+    VIZZLY_COMMIT_SHA: ${{ github.event.pull_request.head.sha || github.event.head_commit.id }}
+    VIZZLY_BRANCH: ${{ github.head_ref || github.ref_name }}
 ```
 
 ### GitLab CI
@@ -319,10 +329,30 @@ Check if Vizzly is enabled in the current environment.
 
 ## Environment Variables
 
+### Core Configuration
 - `VIZZLY_TOKEN`: API authentication token. Example: `export VIZZLY_TOKEN=your-token`.
 - `VIZZLY_API_URL`: Override API base URL. Default: `https://vizzly.dev`.
 - `VIZZLY_LOG_LEVEL`: Logger level. One of `debug`, `info`, `warn`, `error`. Example: `export VIZZLY_LOG_LEVEL=debug`.
 
+### Git Information Override
+For enhanced CI/CD integration, you can override git detection with these environment variables:
+
+- `VIZZLY_COMMIT_SHA`: Override detected commit SHA. Useful in CI environments.
+- `VIZZLY_COMMIT_MESSAGE`: Override detected commit message. Useful in CI environments.
+- `VIZZLY_BRANCH`: Override detected branch name. Useful in CI environments.
+- `VIZZLY_PR_NUMBER`: Override detected pull request number. Useful for PR-specific builds.
+
+**Example for GitHub Actions:**
+```yaml
+env:
+  VIZZLY_COMMIT_MESSAGE: ${{ github.event.pull_request.head.commit.message || github.event.head_commit.message }}
+  VIZZLY_COMMIT_SHA: ${{ github.event.pull_request.head.sha || github.event.head_commit.id }}
+  VIZZLY_BRANCH: ${{ github.head_ref || github.ref_name }}
+  VIZZLY_PR_NUMBER: ${{ github.event.pull_request.number }}
+```
+
+These variables take highest priority over both CLI arguments and automatic git detection.
+
 ## Contributing
 
 We welcome contributions! Whether you're fixing bugs, adding features, or improving documentation, your help makes Vizzly better for everyone.

package/dist/cli.js

@@ -38,10 +38,26 @@ program.command('tdd').description('Run tests in TDD mode with local visual comp
     validationErrors.forEach(error => console.error(`  - ${error}`));
     process.exit(1);
   }
-  const result = await tddCommand(command, options, globalOptions);
+  const {
+    result,
+    cleanup
+  } = await tddCommand(command, options, globalOptions);
+
+  // Set up cleanup on process signals
+  const handleCleanup = async () => {
+    await cleanup();
+  };
+  process.once('SIGINT', () => {
+    handleCleanup().then(() => process.exit(1));
+  });
+  process.once('SIGTERM', () => {
+    handleCleanup().then(() => process.exit(1));
+  });
   if (result && !result.success && result.exitCode > 0) {
+    await cleanup();
     process.exit(result.exitCode);
   }
+  await cleanup();
 });
 program.command('run').description('Run tests with Vizzly integration').argument('<command>', 'Test command to run').option('--port <port>', 'Port for screenshot server', '47392').option('-b, --build-name <name>', 'Custom build name').option('--branch <branch>', 'Git branch override').option('--commit <sha>', 'Git commit SHA').option('--message <msg>', 'Commit message').option('--environment <env>', 'Environment name', 'test').option('--token <token>', 'API token override').option('--wait', 'Wait for build completion').option('--timeout <ms>', 'Server timeout in milliseconds', '30000').option('--allow-no-token', 'Allow running without API token').option('--upload-all', 'Upload all screenshots without SHA deduplication').action(async (command, options) => {
   const globalOptions = program.opts();

package/dist/commands/run.js

@@ -1,7 +1,7 @@
 import { loadConfig } from '../utils/config-loader.js';
 import { ConsoleUI } from '../utils/console-ui.js';
 import { createServiceContainer } from '../container/index.js';
-import { detectBranch, detectCommit, getCommitMessage, generateBuildNameWithGit } from '../utils/git.js';
+import { detectBranch, detectCommit, detectCommitMessage, detectPullRequestNumber, generateBuildNameWithGit } from '../utils/git.js';
 
 /**
  * Run command implementation
@@ -17,15 +17,28 @@ export async function runCommand(testCommand, options = {}, globalOptions = {})
     color: !globalOptions.noColor
   });
   let testRunner = null;
-  let runResult = null;
+  let buildId = null;
+  let startTime = null;
+  let isTddMode = false;
 
   // Ensure cleanup on exit
   const cleanup = async () => {
     ui.cleanup();
-    if (testRunner && runResult && runResult.buildId) {
+
+    // Cancel test runner (kills process and stops server)
+    if (testRunner) {
+      try {
+        await testRunner.cancel();
+      } catch {
+        // Silent fail
+      }
+    }
+
+    // Finalize build if we have one
+    if (testRunner && buildId) {
       try {
-        // Try to finalize build on interruption
-        await testRunner.finalizeBuild(runResult.buildId, false, false, Date.now() - (runResult.startTime || Date.now()));
+        const executionTime = Date.now() - (startTime || Date.now());
+        await testRunner.finalizeBuild(buildId, isTddMode, false, executionTime);
       } catch {
         // Silent fail on cleanup
       }
@@ -55,8 +68,9 @@ export async function runCommand(testCommand, options = {}, globalOptions = {})
     // Collect git metadata and build info
     const branch = await detectBranch(options.branch);
     const commit = await detectCommit(options.commit);
-    const message = options.message || (await getCommitMessage());
+    const message = options.message || (await detectCommitMessage());
     const buildName = await generateBuildNameWithGit(options.buildName);
+    const pullRequestNumber = detectPullRequestNumber();
     if (globalOptions.verbose) {
       ui.info('Configuration loaded', {
         testCommand,
@@ -112,6 +126,7 @@ export async function runCommand(testCommand, options = {}, globalOptions = {})
     });
     testRunner.on('build-created', buildInfo => {
       buildUrl = buildInfo.url;
+      buildId = buildInfo.buildId;
       // Debug: Log build creation details
       if (globalOptions.verbose) {
         ui.info(`Build created: ${buildInfo.buildId} - ${buildInfo.name}`);
@@ -146,26 +161,52 @@ export async function runCommand(testCommand, options = {}, globalOptions = {})
       eager: config.eager || false,
       allowNoToken: config.allowNoToken || false,
       wait: config.wait || options.wait || false,
-      uploadAll: options.uploadAll || false
+      uploadAll: options.uploadAll || false,
+      pullRequestNumber
     };
 
     // Start test run
     ui.info('Starting test execution...');
-    runResult = {
-      startTime: Date.now()
-    };
-    const result = await testRunner.run(runOptions);
-    runResult = {
-      ...runResult,
-      ...result
-    };
-    ui.success('Test run completed successfully');
+    startTime = Date.now();
+    isTddMode = runOptions.tdd || false;
+    let result;
+    try {
+      result = await testRunner.run(runOptions);
 
-    // Show Vizzly summary
-    if (result.buildId) {
-      console.log(`🐻 Vizzly: Captured ${result.screenshotsCaptured} screenshots in build ${result.buildId}`);
-      if (result.url) {
-        console.log(`🔗 Vizzly: View results at ${result.url}`);
+      // Store buildId for cleanup purposes
+      if (result.buildId) {
+        buildId = result.buildId;
+      }
+      ui.success('Test run completed successfully');
+
+      // Show Vizzly summary
+      if (result.buildId) {
+        console.log(`🐻 Vizzly: Captured ${result.screenshotsCaptured} screenshots in build ${result.buildId}`);
+        if (result.url) {
+          console.log(`🔗 Vizzly: View results at ${result.url}`);
+        }
+      }
+    } catch (error) {
+      // Test execution failed - build should already be finalized by test runner
+      ui.stopSpinner();
+
+      // Check if it's a test command failure (as opposed to setup failure)
+      if (error.code === 'TEST_COMMAND_FAILED' || error.code === 'TEST_COMMAND_INTERRUPTED') {
+        // Extract exit code from error message if available
+        const exitCodeMatch = error.message.match(/exited with code (\d+)/);
+        const exitCode = exitCodeMatch ? parseInt(exitCodeMatch[1], 10) : 1;
+        ui.error('Test run failed');
+        return {
+          success: false,
+          exitCode
+        };
+      } else {
+        // Setup or other error
+        ui.error('Test run failed', error);
+        return {
+          success: false,
+          exitCode: 1
+        };
       }
     }
 

package/dist/commands/tdd.js

@@ -8,29 +8,26 @@ import { detectBranch, detectCommit } from '../utils/git.js';
  * @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 async function tddCommand(testCommand, options = {}, globalOptions = {}) {
-  // Create UI handler
   const ui = new ConsoleUI({
     json: globalOptions.json,
     verbose: globalOptions.verbose,
     color: !globalOptions.noColor
   });
   let testRunner = null;
+  let isCleanedUp = false;
 
-  // Ensure cleanup on exit - store listeners for proper cleanup
+  // Create cleanup function that can be called by the caller
   const cleanup = async () => {
+    if (isCleanedUp) return;
+    isCleanedUp = true;
     ui.cleanup();
-    // The test runner's finally block will handle server cleanup
-    // We just need to ensure UI cleanup happens
-  };
-  const sigintHandler = async () => {
-    await cleanup();
-    process.exit(1);
+    if (testRunner?.cancel) {
+      await testRunner.cancel();
+    }
   };
-  const exitHandler = () => ui.cleanup();
-  process.on('SIGINT', sigintHandler);
-  process.on('exit', exitHandler);
   try {
     // Load configuration with CLI overrides
     const allOptions = {
@@ -45,11 +42,6 @@ export async function tddCommand(testCommand, options = {}, globalOptions = {})
       ui.warning('No API token detected - running in local-only mode');
     }
 
-    // Handle --set-baseline flag
-    if (options.setBaseline) {
-      ui.info('🐻 Baseline update mode - current screenshots will become new baselines');
-    }
-
     // Collect git metadata
     const branch = await detectBranch(options.branch);
     const commit = await detectCommit(options.commit);
@@ -119,19 +111,20 @@ export async function tddCommand(testCommand, options = {}, globalOptions = {})
     });
 
     // Show informational messages about baseline behavior
-    if (config.apiKey) {
-      ui.info('API token available - will fetch baselines for local comparison');
+    if (options.setBaseline) {
+      ui.info('🐻 Baseline update mode - will ignore existing baselines and create new ones');
+    } else if (config.baselineBuildId || config.baselineComparisonId) {
+      ui.info('API token available - will fetch remote baselines for local comparison');
+    } else if (config.apiKey) {
+      ui.info('API token available - will use existing local baselines or create new ones');
     } else {
       ui.warning('Running without API token - all screenshots will be marked as new');
     }
-
-    // Prepare TDD run options (no uploads, local comparisons only)
     const runOptions = {
       testCommand,
       port: config.server.port,
       timeout: config.server.timeout,
       tdd: true,
-      // Enable TDD mode
       setBaseline: options.setBaseline || false,
       // Pass through baseline update mode
       branch,
@@ -144,8 +137,6 @@ export async function tddCommand(testCommand, options = {}, globalOptions = {})
       baselineComparisonId: config.baselineComparisonId,
       wait: false // No build to wait for in TDD mode
     };
-
-    // Start TDD test run (local comparisons only)
     ui.info('Starting TDD test execution...');
     const result = await testRunner.run(runOptions);
 
@@ -166,22 +157,31 @@ export async function tddCommand(testCommand, options = {}, globalOptions = {})
     }
     ui.success('TDD test run completed');
 
-    // Exit with appropriate code based on comparison results
-    if (result.failed || result.comparisons && result.comparisons.some(c => c.status === 'failed')) {
+    // Determine success based on comparison results
+    const hasFailures = result.failed || result.comparisons && result.comparisons.some(c => c.status === 'failed');
+    if (hasFailures) {
       ui.error('Visual differences detected in TDD mode', {}, 0);
-      // Return error status without calling process.exit in tests
-      return {
-        success: false,
-        exitCode: 1
-      };
     }
-    ui.cleanup();
+
+    // Return result and cleanup function
+    return {
+      result: {
+        success: !hasFailures,
+        exitCode: hasFailures ? 1 : 0,
+        ...result
+      },
+      cleanup
+    };
   } catch (error) {
     ui.error('TDD test run failed', error);
-  } finally {
-    // Remove event listeners to prevent memory leaks
-    process.removeListener('SIGINT', sigintHandler);
-    process.removeListener('exit', exitHandler);
+    return {
+      result: {
+        success: false,
+        exitCode: 1,
+        error: error.message
+      },
+      cleanup
+    };
   }
 }
 

package/dist/commands/upload.js

@@ -1,7 +1,7 @@
 import { loadConfig } from '../utils/config-loader.js';
 import { ConsoleUI } from '../utils/console-ui.js';
 import { createServiceContainer } from '../container/index.js';
-import { detectBranch, detectCommit, getCommitMessage, generateBuildNameWithGit } from '../utils/git.js';
+import { detectBranch, detectCommit, detectCommitMessage, detectPullRequestNumber, generateBuildNameWithGit } from '../utils/git.js';
 import { ApiService } from '../services/api-service.js';
 
 /**
@@ -71,8 +71,9 @@ export async function uploadCommand(screenshotsPath, options = {}, globalOptions
     // Collect git metadata if not provided
     const branch = await detectBranch(options.branch);
     const commit = await detectCommit(options.commit);
-    const message = options.message || (await getCommitMessage());
+    const message = options.message || (await detectCommitMessage());
     const buildName = await generateBuildNameWithGit(options.buildName);
+    const pullRequestNumber = detectPullRequestNumber();
     ui.info(`Uploading screenshots from: ${screenshotsPath}`);
     if (globalOptions.verbose) {
       ui.info('Configuration loaded', {
@@ -99,6 +100,7 @@ export async function uploadCommand(screenshotsPath, options = {}, globalOptions
       threshold: config.comparison.threshold,
       uploadAll: options.uploadAll || false,
       metadata: options.metadata ? JSON.parse(options.metadata) : {},
+      pullRequestNumber,
       onProgress: progressData => {
         const {
           message: progressMessage,

package/dist/server/handlers/tdd-handler.js

@@ -2,17 +2,32 @@ import { Buffer } from 'buffer';
 import { createServiceLogger } from '../../utils/logger-factory.js';
 import { TddService } from '../../services/tdd-service.js';
 import { colors } from '../../utils/colors.js';
+import { sanitizeScreenshotName, validateScreenshotProperties } from '../../utils/security.js';
 const logger = createServiceLogger('TDD-HANDLER');
-export const createTddHandler = (config, workingDir, baselineBuild, baselineComparison) => {
-  const tddService = new TddService(config, workingDir);
+export const createTddHandler = (config, workingDir, baselineBuild, baselineComparison, setBaseline = false) => {
+  const tddService = new TddService(config, workingDir, setBaseline);
   const builds = new Map();
   const initialize = async () => {
     logger.info('🔄 TDD mode enabled - setting up local comparison...');
+
+    // In baseline update mode, skip all baseline loading/downloading
+    if (setBaseline) {
+      logger.info('📁 Ready for new baseline creation - all screenshots will be treated as new baselines');
+      return;
+    }
+
+    // Check if we have baseline override flags that should force a fresh download
+    const shouldForceDownload = (baselineBuild || baselineComparison) && config.apiKey;
+    if (shouldForceDownload) {
+      logger.info('📥 Baseline override specified, downloading fresh baselines from Vizzly...');
+      await tddService.downloadBaselines(config.build?.environment || 'test', config.build?.branch || null, baselineBuild, baselineComparison);
+      return;
+    }
     const baseline = await tddService.loadBaseline();
     if (!baseline) {
       if (config.apiKey) {
         logger.info('📥 No local baseline found, downloading from Vizzly...');
-        await tddService.downloadBaselines(baselineBuild, baselineComparison);
+        await tddService.downloadBaselines(config.build?.environment || 'test', config.build?.branch || null, baselineBuild, baselineComparison);
       } else {
         logger.info('📝 No local baseline found and no API token - all screenshots will be marked as new');
       }
@@ -36,15 +51,72 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
     if (!build) {
       throw new Error(`Build ${buildId} not found`);
     }
+
+    // Validate and sanitize screenshot name
+    let sanitizedName;
+    try {
+      sanitizedName = sanitizeScreenshotName(name);
+    } catch (error) {
+      return {
+        statusCode: 400,
+        body: {
+          error: 'Invalid screenshot name',
+          details: error.message,
+          tddMode: true
+        }
+      };
+    }
+
+    // Validate and sanitize properties
+    let validatedProperties;
+    try {
+      validatedProperties = validateScreenshotProperties(properties);
+    } catch (error) {
+      return {
+        statusCode: 400,
+        body: {
+          error: 'Invalid screenshot properties',
+          details: error.message,
+          tddMode: true
+        }
+      };
+    }
+
+    // Create unique screenshot name based on properties
+    let uniqueName = sanitizedName;
+    const relevantProps = [];
+
+    // Add browser to name if provided (already validated)
+    if (validatedProperties.browser) {
+      relevantProps.push(validatedProperties.browser);
+    }
+
+    // Add viewport info if provided (already validated)
+    if (validatedProperties.viewport && validatedProperties.viewport.width && validatedProperties.viewport.height) {
+      relevantProps.push(`${validatedProperties.viewport.width}x${validatedProperties.viewport.height}`);
+    }
+
+    // Combine base name with relevant properties and sanitize the result
+    if (relevantProps.length > 0) {
+      let proposedUniqueName = `${sanitizedName}-${relevantProps.join('-')}`;
+      try {
+        uniqueName = sanitizeScreenshotName(proposedUniqueName);
+      } catch (error) {
+        // If the combined name is invalid, fall back to the base sanitized name
+        uniqueName = sanitizedName;
+        logger.warn(`Combined screenshot name invalid (${error.message}), using base name: ${uniqueName}`);
+      }
+    }
     const screenshot = {
-      name,
+      name: uniqueName,
+      originalName: name,
       imageData: image,
-      properties,
+      properties: validatedProperties,
       timestamp: Date.now()
     };
     build.screenshots.push(screenshot);
     const imageBuffer = Buffer.from(image, 'base64');
-    const comparison = await tddService.compareScreenshot(name, imageBuffer, properties);
+    const comparison = await tddService.compareScreenshot(uniqueName, imageBuffer, validatedProperties);
     if (comparison.status === 'failed') {
       return {
         statusCode: 422,
@@ -56,7 +128,9 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
             status: comparison.status,
             baseline: comparison.baseline,
             current: comparison.current,
-            diff: comparison.diff
+            diff: comparison.diff,
+            diffPercentage: comparison.diffPercentage,
+            threshold: comparison.threshold
           },
           tddMode: true
         }
@@ -112,7 +186,7 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
     if (build.screenshots.length === 0) {
       throw new Error('No screenshots to process. Make sure your tests are calling the Vizzly screenshot function.');
     }
-    const results = tddService.printResults();
+    const results = await tddService.printResults();
     builds.delete(buildId);
     return {
       id: buildId,