@vizzly-testing/cli 0.1.0

package/dist/commands/run.js

@@ -0,0 +1,224 @@
+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';
+
+/**
+ * Run command implementation
+ * @param {string} testCommand - Test command to execute
+ * @param {Object} options - Command options
+ * @param {Object} globalOptions - Global CLI options
+ */
+export async function runCommand(testCommand, options = {}, globalOptions = {}) {
+  // Create UI handler
+  const ui = new ConsoleUI({
+    json: globalOptions.json,
+    verbose: globalOptions.verbose,
+    color: !globalOptions.noColor
+  });
+  let testRunner = null;
+  let runResult = null;
+
+  // Ensure cleanup on exit
+  const cleanup = async () => {
+    ui.cleanup();
+    if (testRunner && runResult && runResult.buildId) {
+      try {
+        // Try to finalize build on interruption
+        await testRunner.finalizeBuild(runResult.buildId, false, false, Date.now() - (runResult.startTime || Date.now()));
+      } catch {
+        // Silent fail on cleanup
+      }
+    }
+  };
+  const sigintHandler = async () => {
+    await cleanup();
+    process.exit(1);
+  };
+  const exitHandler = () => ui.cleanup();
+  process.on('SIGINT', sigintHandler);
+  process.on('exit', exitHandler);
+  try {
+    // Load configuration with CLI overrides
+    const allOptions = {
+      ...globalOptions,
+      ...options
+    };
+    const config = await loadConfig(globalOptions.config, allOptions);
+
+    // Validate API token (unless --allow-no-token is set)
+    if (!config.apiKey && !config.allowNoToken) {
+      ui.error('API token required. Use --token, set VIZZLY_TOKEN environment variable, or use --allow-no-token to run without uploading');
+      return;
+    }
+
+    // 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 buildName = await generateBuildNameWithGit(options.buildName);
+    if (globalOptions.verbose) {
+      ui.info('Configuration loaded', {
+        testCommand,
+        port: config.server.port,
+        timeout: config.server.timeout,
+        tddMode: options.tdd || false,
+        branch,
+        commit: commit?.substring(0, 7),
+        message,
+        buildName,
+        environment: config.build.environment,
+        allowNoToken: config.allowNoToken || false
+      });
+    }
+
+    // Create service container and get test runner service
+    ui.startSpinner('Initializing test runner...');
+    const configWithVerbose = {
+      ...config,
+      verbose: globalOptions.verbose
+    };
+    const command = options.tdd ? 'tdd' : 'run';
+    const container = await createServiceContainer(configWithVerbose, command);
+    testRunner = await container.get('testRunner'); // Assign to outer scope variable
+    ui.stopSpinner();
+
+    // Track build URL for display
+    let buildUrl = null;
+
+    // Set up event handlers
+    testRunner.on('progress', progressData => {
+      const {
+        message: progressMessage
+      } = progressData;
+      ui.progress(progressMessage || 'Running tests...');
+    });
+    testRunner.on('test-output', output => {
+      // In non-JSON mode, show test output directly
+      if (!globalOptions.json) {
+        ui.stopSpinner();
+        console.log(output.data);
+      }
+    });
+    testRunner.on('server-ready', serverInfo => {
+      if (globalOptions.verbose) {
+        ui.info(`Screenshot server running on port ${serverInfo.port}`);
+        ui.info('Server details', serverInfo);
+      }
+    });
+    testRunner.on('screenshot-captured', screenshotInfo => {
+      // Use UI for consistent formatting
+      ui.info(`Vizzly: Screenshot captured - ${screenshotInfo.name}`);
+    });
+    testRunner.on('build-created', buildInfo => {
+      buildUrl = buildInfo.url;
+      // Use UI for consistent formatting
+      if (buildUrl) {
+        ui.info(`Vizzly: ${buildUrl}`);
+      }
+    });
+    testRunner.on('error', error => {
+      ui.error('Test runner error occurred', error, 0); // Don't exit immediately, let runner handle it
+    });
+
+    // Prepare run options
+    const runOptions = {
+      testCommand,
+      port: config.server.port,
+      timeout: config.server.timeout,
+      tdd: options.tdd || false,
+      buildName,
+      branch,
+      commit,
+      message,
+      environment: config.build.environment,
+      threshold: config.comparison.threshold,
+      eager: config.eager || false,
+      allowNoToken: config.allowNoToken || false,
+      baselineBuildId: config.baselineBuildId,
+      baselineComparisonId: config.baselineComparisonId,
+      wait: config.wait || options.wait || false
+    };
+
+    // 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');
+
+    // 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}`);
+      }
+    }
+
+    // Output results
+    if (result.buildId) {
+      // Wait for build completion if requested
+      if (runOptions.wait) {
+        ui.info('Waiting for build completion...');
+        ui.startSpinner('Processing comparisons...');
+        const uploader = await container.get('uploader');
+        const buildResult = await uploader.waitForBuild(result.buildId);
+        ui.success('Build processing completed');
+
+        // Exit with appropriate code based on comparison results
+        if (buildResult.failedComparisons > 0) {
+          ui.error(`${buildResult.failedComparisons} visual comparisons failed`, {}, 1);
+        }
+      }
+    }
+    ui.cleanup();
+  } catch (error) {
+    ui.error('Test run failed', error);
+  } finally {
+    // Remove event listeners to prevent memory leaks
+    process.removeListener('SIGINT', sigintHandler);
+    process.removeListener('exit', exitHandler);
+  }
+}
+
+/**
+ * Validate run options
+ * @param {string} testCommand - Test command to execute
+ * @param {Object} options - Command options
+ */
+export function validateRunOptions(testCommand, options) {
+  const errors = [];
+  if (!testCommand || testCommand.trim() === '') {
+    errors.push('Test command is required');
+  }
+  if (options.port) {
+    const port = parseInt(options.port, 10);
+    if (isNaN(port) || port < 1 || port > 65535) {
+      errors.push('Port must be a valid number between 1 and 65535');
+    }
+  }
+  if (options.timeout) {
+    const timeout = parseInt(options.timeout, 10);
+    if (isNaN(timeout) || timeout < 1000) {
+      errors.push('Timeout must be at least 1000 milliseconds');
+    }
+  }
+  if (options.batchSize !== undefined) {
+    const n = parseInt(options.batchSize, 10);
+    if (!Number.isFinite(n) || n <= 0) {
+      errors.push('Batch size must be a positive integer');
+    }
+  }
+  if (options.uploadTimeout !== undefined) {
+    const n = parseInt(options.uploadTimeout, 10);
+    if (!Number.isFinite(n) || n <= 0) {
+      errors.push('Upload timeout must be a positive integer (milliseconds)');
+    }
+  }
+  return errors;
+}

package/dist/commands/status.js

@@ -0,0 +1,164 @@
+import { loadConfig } from '../utils/config-loader.js';
+import { ConsoleUI } from '../utils/console-ui.js';
+import { createServiceContainer } from '../container/index.js';
+import { getApiUrl } from '../utils/environment-config.js';
+
+/**
+ * Status command implementation
+ * @param {string} buildId - Build ID to check status for
+ * @param {Object} options - Command options
+ * @param {Object} globalOptions - Global CLI options
+ */
+export async function statusCommand(buildId, options = {}, globalOptions = {}) {
+  // Create UI handler
+  const ui = new ConsoleUI({
+    json: globalOptions.json,
+    verbose: globalOptions.verbose,
+    color: !globalOptions.noColor
+  });
+
+  // Note: ConsoleUI handles cleanup via global process listeners
+
+  try {
+    ui.info(`Checking status for build: ${buildId}`);
+
+    // Load configuration with CLI overrides
+    const allOptions = {
+      ...globalOptions,
+      ...options
+    };
+    const config = await loadConfig(globalOptions.config, allOptions);
+
+    // Validate API token
+    if (!config.apiKey) {
+      ui.error('API token required. Use --token or set VIZZLY_TOKEN environment variable');
+      return;
+    }
+
+    // Get API service
+    ui.startSpinner('Fetching build status...');
+    const container = await createServiceContainer(config, 'status');
+    const apiService = await container.get('apiService');
+
+    // Get build details via unified ApiService
+    const buildStatus = await apiService.getBuild(buildId);
+    ui.stopSpinner();
+
+    // Extract build data from API response
+    const build = buildStatus.build || buildStatus;
+
+    // Display build summary
+    ui.success(`Build: ${build.name || build.id}`);
+    ui.info(`Status: ${build.status.toUpperCase()}`);
+    ui.info(`Environment: ${build.environment}`);
+    if (build.branch) {
+      ui.info(`Branch: ${build.branch}`);
+    }
+    if (build.commit_sha) {
+      ui.info(`Commit: ${build.commit_sha.substring(0, 8)} - ${build.commit_message || 'No message'}`);
+    }
+
+    // Show screenshot and comparison stats
+    ui.info(`Screenshots: ${build.screenshot_count || 0} total`);
+    ui.info(`Comparisons: ${build.total_comparisons || 0} total (${build.new_comparisons || 0} new, ${build.changed_comparisons || 0} changed, ${build.identical_comparisons || 0} identical)`);
+    if (build.approval_status) {
+      ui.info(`Approval Status: ${build.approval_status}`);
+    }
+
+    // Show timing information
+    if (build.created_at) {
+      ui.info(`Created: ${new Date(build.created_at).toLocaleString()}`);
+    }
+    if (build.completed_at) {
+      ui.info(`Completed: ${new Date(build.completed_at).toLocaleString()}`);
+    } else if (build.status !== 'completed' && build.status !== 'failed') {
+      ui.info(`Started: ${new Date(build.started_at || build.created_at).toLocaleString()}`);
+    }
+    if (build.execution_time_ms) {
+      ui.info(`Execution Time: ${Math.round(build.execution_time_ms / 1000)}s`);
+    }
+
+    // Show build URL if we can construct it
+    const baseUrl = config.baseUrl || getApiUrl();
+    if (baseUrl && build.project_id) {
+      const buildUrl = baseUrl.replace('/api', '') + `/projects/${build.project_id}/builds/${build.id}`;
+      ui.info(`View Build: ${buildUrl}`);
+    }
+
+    // Output JSON data for --json mode
+    if (globalOptions.json) {
+      const statusData = {
+        buildId: build.id,
+        status: build.status,
+        name: build.name,
+        createdAt: build.created_at,
+        updatedAt: build.updated_at,
+        completedAt: build.completed_at,
+        environment: build.environment,
+        branch: build.branch,
+        commit: build.commit_sha,
+        commitMessage: build.commit_message,
+        screenshotsTotal: build.screenshot_count || 0,
+        comparisonsTotal: build.total_comparisons || 0,
+        newComparisons: build.new_comparisons || 0,
+        changedComparisons: build.changed_comparisons || 0,
+        identicalComparisons: build.identical_comparisons || 0,
+        approvalStatus: build.approval_status,
+        executionTime: build.execution_time_ms,
+        isBaseline: build.is_baseline,
+        userAgent: build.user_agent
+      };
+      ui.data(statusData);
+    }
+
+    // Show additional info in verbose mode
+    if (globalOptions.verbose) {
+      ui.info('\n--- Additional Details ---');
+      if (build.approved_screenshots > 0 || build.rejected_screenshots > 0 || build.pending_screenshots > 0) {
+        ui.info(`Screenshot Approvals: ${build.approved_screenshots || 0} approved, ${build.rejected_screenshots || 0} rejected, ${build.pending_screenshots || 0} pending`);
+      }
+      if (build.avg_diff_percentage !== null) {
+        ui.info(`Average Diff: ${(build.avg_diff_percentage * 100).toFixed(2)}%`);
+      }
+      if (build.github_pull_request_number) {
+        ui.info(`GitHub PR: #${build.github_pull_request_number}`);
+      }
+      if (build.is_baseline) {
+        ui.info('This build is marked as a baseline');
+      }
+      ui.info(`User Agent: ${build.user_agent || 'Unknown'}`);
+      ui.info(`Build ID: ${build.id}`);
+      ui.info(`Project ID: ${build.project_id}`);
+    }
+
+    // Show progress if build is still processing
+    if (build.status === 'processing' || build.status === 'pending') {
+      const totalJobs = build.completed_jobs + build.failed_jobs + build.processing_screenshots;
+      if (totalJobs > 0) {
+        const progress = (build.completed_jobs + build.failed_jobs) / totalJobs;
+        ui.info(`Progress: ${Math.round(progress * 100)}% complete`);
+      }
+    }
+    ui.cleanup();
+
+    // Exit with appropriate code based on build status
+    if (build.status === 'failed' || build.failed_jobs > 0) {
+      process.exit(1);
+    }
+  } catch (error) {
+    ui.error('Failed to get build status', error);
+  }
+}
+
+/**
+ * Validate status options
+ * @param {string} buildId - Build ID to check
+ * @param {Object} options - Command options
+ */
+export function validateStatusOptions(buildId) {
+  const errors = [];
+  if (!buildId || buildId.trim() === '') {
+    errors.push('Build ID is required');
+  }
+  return errors;
+}

package/dist/commands/tdd.js

@@ -0,0 +1,212 @@
+import { loadConfig } from '../utils/config-loader.js';
+import { ConsoleUI } from '../utils/console-ui.js';
+import { createServiceContainer } from '../container/index.js';
+import { detectBranch, detectCommit } from '../utils/git.js';
+
+/**
+ * TDD command implementation
+ * @param {string} testCommand - Test command to execute
+ * @param {Object} options - Command options
+ * @param {Object} globalOptions - Global CLI options
+ */
+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;
+
+  // Ensure cleanup on exit - store listeners for proper cleanup
+  const cleanup = async () => {
+    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);
+  };
+  const exitHandler = () => ui.cleanup();
+  process.on('SIGINT', sigintHandler);
+  process.on('exit', exitHandler);
+  try {
+    // Load configuration with CLI overrides
+    const allOptions = {
+      ...globalOptions,
+      ...options
+    };
+    const config = await loadConfig(globalOptions.config, allOptions);
+
+    // Auto-detect missing token and allow no-token mode for TDD
+    if (!config.apiKey) {
+      config.allowNoToken = true;
+      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);
+    if (globalOptions.verbose) {
+      ui.info('TDD Configuration loaded', {
+        testCommand,
+        port: config.server.port,
+        timeout: config.server.timeout,
+        branch,
+        commit: commit?.substring(0, 7),
+        environment: config.build.environment,
+        threshold: config.comparison.threshold,
+        baselineBuildId: config.baselineBuildId,
+        baselineComparisonId: config.baselineComparisonId
+      });
+    }
+
+    // Create service container and get services
+    ui.startSpinner('Initializing TDD mode...');
+    const configWithVerbose = {
+      ...config,
+      verbose: globalOptions.verbose
+    };
+    const container = await createServiceContainer(configWithVerbose, 'tdd');
+    testRunner = await container.get('testRunner');
+    ui.stopSpinner();
+
+    // Set up event handlers for user feedback
+    testRunner.on('progress', progressData => {
+      const {
+        message: progressMessage
+      } = progressData;
+      ui.progress(progressMessage || 'Running TDD tests...');
+    });
+    testRunner.on('test-output', output => {
+      // In non-JSON mode, show test output directly
+      if (!globalOptions.json) {
+        ui.stopSpinner();
+        console.log(output.data);
+      }
+    });
+    testRunner.on('server-ready', serverInfo => {
+      if (globalOptions.verbose) {
+        ui.info(`TDD screenshot server running on port ${serverInfo.port}`);
+        ui.info('Server details', serverInfo);
+      }
+    });
+    testRunner.on('screenshot-captured', screenshotInfo => {
+      ui.info(`Vizzly TDD: Screenshot captured - ${screenshotInfo.name}`);
+    });
+    testRunner.on('comparison-result', comparisonInfo => {
+      const {
+        name,
+        status,
+        pixelDifference
+      } = comparisonInfo;
+      if (status === 'passed') {
+        ui.info(`✅ ${name}: Visual comparison passed`);
+      } else if (status === 'failed') {
+        ui.warning(`❌ ${name}: Visual comparison failed (${pixelDifference}% difference)`);
+      } else if (status === 'new') {
+        ui.warning(`🆕 ${name}: New screenshot (no baseline)`);
+      }
+    });
+    testRunner.on('error', error => {
+      ui.error('TDD test runner error occurred', error, 0); // Don't exit immediately
+    });
+
+    // Show informational messages about baseline behavior
+    if (config.apiKey) {
+      ui.info('API token available - will fetch baselines for local comparison');
+    } 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,
+      commit,
+      environment: config.build.environment,
+      threshold: config.comparison.threshold,
+      allowNoToken: config.allowNoToken || false,
+      // Pass through the allow-no-token setting
+      baselineBuildId: config.baselineBuildId,
+      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);
+
+    // Show TDD summary
+    const {
+      screenshotsCaptured,
+      comparisons
+    } = result;
+    console.log(`🐻 Vizzly TDD: Processed ${screenshotsCaptured} screenshots`);
+    if (comparisons && comparisons.length > 0) {
+      const passed = comparisons.filter(c => c.status === 'passed').length;
+      const failed = comparisons.filter(c => c.status === 'failed').length;
+      const newScreenshots = comparisons.filter(c => c.status === 'new').length;
+      console.log(`📊 Results: ${passed} passed, ${failed} failed, ${newScreenshots} new`);
+      if (failed > 0) {
+        console.log(`🔍 Check diff images in .vizzly/diffs/ directory`);
+      }
+    }
+    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')) {
+      ui.error('Visual differences detected in TDD mode', {}, 1);
+    }
+    ui.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);
+  }
+}
+
+/**
+ * Validate TDD options
+ * @param {string} testCommand - Test command to execute
+ * @param {Object} options - Command options
+ */
+export function validateTddOptions(testCommand, options) {
+  const errors = [];
+  if (!testCommand || testCommand.trim() === '') {
+    errors.push('Test command is required');
+  }
+  if (options.port) {
+    const port = parseInt(options.port, 10);
+    if (isNaN(port) || port < 1 || port > 65535) {
+      errors.push('Port must be a valid number between 1 and 65535');
+    }
+  }
+  if (options.timeout) {
+    const timeout = parseInt(options.timeout, 10);
+    if (isNaN(timeout) || timeout < 1000) {
+      errors.push('Timeout must be at least 1000 milliseconds');
+    }
+  }
+  if (options.threshold !== undefined) {
+    const threshold = parseFloat(options.threshold);
+    if (isNaN(threshold) || threshold < 0 || threshold > 1) {
+      errors.push('Threshold must be a number between 0 and 1');
+    }
+  }
+  return errors;
+}