@vizzly-testing/cli 0.3.1 → 0.4.0

package/README.md

@@ -55,7 +55,7 @@ vizzly upload ./screenshots --build-name "Release v1.2.3"
 vizzly run "npm test"
 
 # Use TDD mode for local development
-vizzly run "npm test" --tdd
+vizzly tdd "npm test"
 ```
 
 ### In your test code
@@ -81,15 +81,14 @@ await vizzlyScreenshot('homepage', screenshot, {
 ```bash
 vizzly upload <directory>           # Upload screenshots from directory
 vizzly upload ./screenshots --wait  # Wait for processing
+vizzly upload ./screenshots --upload-all  # Upload all without deduplication
 ```
 
 ### Run Tests with Integration
 ```bash
 vizzly run "npm test"               # Run with Vizzly integration
-vizzly run "npm test" --tdd         # Local TDD mode
 vizzly run "pytest" --port 3002     # Custom port
 vizzly run "npm test" --wait        # Wait for build completion
-vizzly run "npm test" --eager       # Create build immediately
 vizzly run "npm test" --allow-no-token  # Run without API token
 ```
 
@@ -108,19 +107,36 @@ vizzly run "npm test" --allow-no-token  # Run without API token
 
 **Processing Options:**
 - `--wait` - Wait for build completion and exit with appropriate code
-- `--eager` - Create build immediately (default: lazy creation)
 - `--threshold <number>` - Comparison threshold (0-1, default: 0.01)
-- `--batch-size <n>` - Upload batch size used with `--wait`
 - `--upload-timeout <ms>` - Upload wait timeout in ms
+- `--upload-all` - Upload all screenshots without SHA deduplication
 
 **Development & Testing:**
-- `--tdd` - Enable TDD mode with local comparisons
 - `--allow-no-token` - Allow running without API token (useful for local development)
 - `--token <token>` - API token override
 
-**Baseline Configuration:**
-- `--baseline-build <id>` - Use specific build as baseline for comparisons
-- `--baseline-comparison <id>` - Use specific comparison as baseline
+## TDD Command
+
+For local visual testing with immediate feedback, use the dedicated `tdd` command:
+
+```bash
+# First run - creates local baselines
+vizzly tdd "npm test"
+
+# Make changes and test - fails if visual differences detected  
+vizzly tdd "npm test"
+
+# Accept changes as new baseline
+vizzly tdd "npm test" --set-baseline
+```
+
+**TDD Command Options:**
+- `--set-baseline` - Accept current screenshots as new baseline
+- `--baseline-build <id>` - Use specific build as baseline (requires API token)
+- `--baseline-comparison <id>` - Use specific comparison as baseline (requires API token)
+- `--threshold <number>` - Comparison threshold (0-1, default: 0.1)
+- `--port <port>` - Server port (default: 47392)
+- `--timeout <ms>` - Server timeout (default: 30000)
 
 ### Setup and Status Commands
 ```bash
@@ -176,25 +192,7 @@ VIZZLY_TOKEN=your-token vizzly doctor --api
 vizzly doctor --json
 ```
 
-## TDD Mode
-
-TDD mode enables fast local development by comparing screenshots locally without uploading to Vizzly:
-
-```bash
-# First run - creates local baselines (no token needed)
-npx vizzly tdd "npm test"
-
-# Make changes and test - fails if visual differences detected
-npx vizzly tdd "npm test"
-
-# Accept changes as new baseline
-npx vizzly tdd "npm test" --set-baseline
-```
-
-- **🐻 Auto-baseline creation**: Creates baselines locally when none exist
-- **🐻 No token required**: Works entirely offline for local development  
-- **🐻 Tests fail on differences**: Immediate feedback when visuals change
-- **🐻 Accept changes**: Use `--set-baseline` to update baselines
+The dedicated `tdd` command provides fast local development with immediate visual feedback. See the [TDD Mode Guide](./docs/tdd-mode.md) for complete details on local visual testing.
 
 ## Configuration
 

package/dist/cli.js

@@ -16,7 +16,7 @@ program.command('init').description('Initialize Vizzly in your project').option(
     ...options
   });
 });
-program.command('upload').description('Upload screenshots to Vizzly').argument('<path>', 'Path to screenshots directory or file').option('-b, --build-name <name>', 'Build name for grouping').option('-m, --metadata <json>', 'Additional metadata as JSON').option('--batch-size <n>', 'Upload batch size', v => parseInt(v, 10)).option('--upload-timeout <ms>', 'Upload timeout in milliseconds', v => parseInt(v, 10)).option('--branch <branch>', 'Git branch').option('--commit <sha>', 'Git commit SHA').option('--message <msg>', 'Commit message').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', parseFloat).option('--token <token>', 'API token override').option('--wait', 'Wait for build completion').action(async (path, options) => {
+program.command('upload').description('Upload screenshots to Vizzly').argument('<path>', 'Path to screenshots directory or file').option('-b, --build-name <name>', 'Build name for grouping').option('-m, --metadata <json>', 'Additional metadata as JSON').option('--batch-size <n>', 'Upload batch size', v => parseInt(v, 10)).option('--upload-timeout <ms>', 'Upload timeout in milliseconds', v => parseInt(v, 10)).option('--branch <branch>', 'Git branch').option('--commit <sha>', 'Git commit SHA').option('--message <msg>', 'Commit message').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', parseFloat).option('--token <token>', 'API token override').option('--wait', 'Wait for build completion').option('--upload-all', 'Upload all screenshots without SHA deduplication').action(async (path, options) => {
   const globalOptions = program.opts();
 
   // Validate options
@@ -38,37 +38,14 @@ program.command('tdd').description('Run tests in TDD mode with local visual comp
     validationErrors.forEach(error => console.error(`  - ${error}`));
     process.exit(1);
   }
-  await tddCommand(command, options, globalOptions);
+  const result = await tddCommand(command, options, globalOptions);
+  if (result && !result.success && result.exitCode > 0) {
+    process.exit(result.exitCode);
+  }
 });
-program.command('run').description('Run tests with Vizzly integration').argument('<command>', 'Test command to run').option('--tdd', 'Enable TDD mode with auto-reload').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('--threshold <number>', 'Comparison threshold', parseFloat).option('--token <token>', 'API token override').option('--wait', 'Wait for build completion').option('--timeout <ms>', 'Server timeout in milliseconds', '30000').option('--eager', 'Create build immediately (default: lazy)').option('--allow-no-token', 'Allow running without API token').option('--baseline-build <id>', 'Use specific build as baseline').option('--baseline-comparison <id>', 'Use specific comparison as baseline').action(async (command, options) => {
+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();
 
-  // Forward --tdd flag to TDD command (shortcut)
-  if (options.tdd) {
-    // Forward to tdd command with appropriate options
-    const tddOptions = {
-      port: options.port,
-      branch: options.branch,
-      environment: options.environment,
-      threshold: options.threshold,
-      token: options.token,
-      timeout: options.timeout,
-      baselineBuild: options.baselineBuild,
-      baselineComparison: options.baselineComparison,
-      allowNoToken: options.allowNoToken
-    };
-
-    // Validate options using TDD validator
-    const validationErrors = validateTddOptions(command, tddOptions);
-    if (validationErrors.length > 0) {
-      console.error('Validation errors:');
-      validationErrors.forEach(error => console.error(`  - ${error}`));
-      process.exit(1);
-    }
-    await tddCommand(command, tddOptions, globalOptions);
-    return;
-  }
-
   // Validate options
   const validationErrors = validateRunOptions(command, options);
   if (validationErrors.length > 0) {
@@ -76,7 +53,18 @@ program.command('run').description('Run tests with Vizzly integration').argument
     validationErrors.forEach(error => console.error(`  - ${error}`));
     process.exit(1);
   }
-  await runCommand(command, options, globalOptions);
+  try {
+    const result = await runCommand(command, options, globalOptions);
+    if (result && !result.success && result.exitCode > 0) {
+      process.exit(result.exitCode);
+    }
+  } catch (error) {
+    console.error('Command failed:', error.message);
+    if (globalOptions.verbose) {
+      console.error('Stack trace:', error.stack);
+    }
+    process.exit(1);
+  }
 });
 program.command('status').description('Check the status of a build').argument('<build-id>', 'Build ID to check status for').action(async (buildId, options) => {
   const globalOptions = program.opts();

package/dist/client/index.js

@@ -66,7 +66,7 @@ function createSimpleClient(serverUrl) {
             buildId: getBuildId(),
             name,
             image: imageBuffer.toString('base64'),
-            properties: options.properties || {},
+            properties: options,
             threshold: options.threshold || 0,
             variant: options.variant,
             fullPage: options.fullPage || false

package/dist/commands/run.js

@@ -62,7 +62,6 @@ export async function runCommand(testCommand, options = {}, globalOptions = {})
         testCommand,
         port: config.server.port,
         timeout: config.server.timeout,
-        tddMode: options.tdd || false,
         branch,
         commit: commit?.substring(0, 7),
         message,
@@ -76,9 +75,10 @@ export async function runCommand(testCommand, options = {}, globalOptions = {})
     ui.startSpinner('Initializing test runner...');
     const configWithVerbose = {
       ...config,
-      verbose: globalOptions.verbose
+      verbose: globalOptions.verbose,
+      uploadAll: options.uploadAll || false
     };
-    const command = options.tdd ? 'tdd' : 'run';
+    const command = 'run';
     const container = await createServiceContainer(configWithVerbose, command);
     testRunner = await container.get('testRunner'); // Assign to outer scope variable
     ui.stopSpinner();
@@ -112,21 +112,31 @@ export async function runCommand(testCommand, options = {}, globalOptions = {})
     });
     testRunner.on('build-created', buildInfo => {
       buildUrl = buildInfo.url;
+      // Debug: Log build creation details
+      if (globalOptions.verbose) {
+        ui.info(`Build created: ${buildInfo.buildId} - ${buildInfo.name}`);
+      }
       // Use UI for consistent formatting
       if (buildUrl) {
         ui.info(`Vizzly: ${buildUrl}`);
       }
     });
+    testRunner.on('build-failed', buildError => {
+      ui.error('Failed to create build', buildError);
+    });
     testRunner.on('error', error => {
+      ui.stopSpinner(); // Stop spinner to ensure error is visible
       ui.error('Test runner error occurred', error, 0); // Don't exit immediately, let runner handle it
     });
+    testRunner.on('build-finalize-failed', errorInfo => {
+      ui.warning(`Failed to finalize build ${errorInfo.buildId}: ${errorInfo.error}`);
+    });
 
     // Prepare run options
     const runOptions = {
       testCommand,
       port: config.server.port,
       timeout: config.server.timeout,
-      tdd: options.tdd || false,
       buildName,
       branch,
       commit,
@@ -135,9 +145,8 @@ export async function runCommand(testCommand, options = {}, globalOptions = {})
       threshold: config.comparison.threshold,
       eager: config.eager || false,
       allowNoToken: config.allowNoToken || false,
-      baselineBuildId: config.baselineBuildId,
-      baselineComparisonId: config.baselineComparisonId,
-      wait: config.wait || options.wait || false
+      wait: config.wait || options.wait || false,
+      uploadAll: options.uploadAll || false
     };
 
     // Start test run
@@ -172,13 +181,29 @@ export async function runCommand(testCommand, options = {}, globalOptions = {})
 
         // Exit with appropriate code based on comparison results
         if (buildResult.failedComparisons > 0) {
-          ui.error(`${buildResult.failedComparisons} visual comparisons failed`, {}, 1);
+          ui.error(`${buildResult.failedComparisons} visual comparisons failed`, {}, 0);
+          // Return error status without calling process.exit in tests
+          return {
+            success: false,
+            exitCode: 1
+          };
         }
       }
     }
     ui.cleanup();
   } catch (error) {
-    ui.error('Test run failed', error);
+    ui.stopSpinner(); // Ensure spinner is stopped before showing error
+
+    // Provide more context about where the error occurred
+    let errorContext = 'Test run failed';
+    if (error.message && error.message.includes('build')) {
+      errorContext = 'Build creation failed';
+    } else if (error.message && error.message.includes('screenshot')) {
+      errorContext = 'Screenshot processing failed';
+    } else if (error.message && error.message.includes('server')) {
+      errorContext = 'Server startup failed';
+    }
+    ui.error(errorContext, error);
   } finally {
     // Remove event listeners to prevent memory leaks
     process.removeListener('SIGINT', sigintHandler);

package/dist/commands/tdd.js

@@ -168,7 +168,12 @@ export async function tddCommand(testCommand, options = {}, globalOptions = {})
 
     // 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.error('Visual differences detected in TDD mode', {}, 0);
+      // Return error status without calling process.exit in tests
+      return {
+        success: false,
+        exitCode: 1
+      };
     }
     ui.cleanup();
   } catch (error) {

package/dist/commands/upload.js

@@ -49,6 +49,9 @@ export async function uploadCommand(screenshotsPath, options = {}, globalOptions
 
   // Note: ConsoleUI handles cleanup via global process listeners
 
+  let buildId = null;
+  let config = null;
+  const uploadStartTime = Date.now();
   try {
     ui.info('Starting upload process...');
 
@@ -57,7 +60,7 @@ export async function uploadCommand(screenshotsPath, options = {}, globalOptions
       ...globalOptions,
       ...options
     };
-    const config = await loadConfig(globalOptions.config, allOptions);
+    config = await loadConfig(globalOptions.config, allOptions);
 
     // Validate API token
     if (!config.apiKey) {
@@ -94,21 +97,53 @@ export async function uploadCommand(screenshotsPath, options = {}, globalOptions
       message,
       environment: config.build.environment,
       threshold: config.comparison.threshold,
+      uploadAll: options.uploadAll || false,
       metadata: options.metadata ? JSON.parse(options.metadata) : {},
       onProgress: progressData => {
         const {
           message: progressMessage,
           current,
           total,
-          phase
+          phase,
+          buildId: progressBuildId
         } = progressData;
-        ui.progress(progressMessage || `${phase || 'Processing'}: ${current || 0}/${total || 0}`, current, total);
+
+        // Track buildId when it becomes available
+        if (progressBuildId) {
+          buildId = progressBuildId;
+        }
+        let displayMessage = progressMessage;
+        if (!displayMessage && phase) {
+          if (current !== undefined && total !== undefined) {
+            displayMessage = `${phase}: ${current}/${total}`;
+          } else {
+            displayMessage = phase;
+          }
+        }
+        ui.progress(displayMessage || 'Processing...', current, total);
       }
     };
 
     // Start upload
     ui.progress('Starting upload...');
     const result = await uploader.upload(uploadOptions);
+    buildId = result.buildId; // Ensure we have the buildId
+
+    // Mark build as completed
+    if (result.buildId) {
+      ui.progress('Finalizing build...');
+      try {
+        const apiService = new ApiService({
+          baseUrl: config.apiUrl,
+          token: config.apiKey,
+          command: 'upload'
+        });
+        const executionTime = Date.now() - uploadStartTime;
+        await apiService.finalizeBuild(result.buildId, true, executionTime);
+      } catch (error) {
+        ui.warning(`Failed to finalize build: ${error.message}`);
+      }
+    }
     ui.success('Upload completed successfully');
 
     // Show Vizzly summary
@@ -138,6 +173,20 @@ export async function uploadCommand(screenshotsPath, options = {}, globalOptions
     }
     ui.cleanup();
   } catch (error) {
+    // Mark build as failed if we have a buildId and config
+    if (buildId && config) {
+      try {
+        const apiService = new ApiService({
+          baseUrl: config.apiUrl,
+          token: config.apiKey,
+          command: 'upload'
+        });
+        const executionTime = Date.now() - uploadStartTime;
+        await apiService.finalizeBuild(buildId, false, executionTime);
+      } catch {
+        // Silent fail on cleanup
+      }
+    }
     ui.error('Upload failed', error);
   }
 }

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

@@ -0,0 +1,83 @@
+import { Buffer } from 'buffer';
+import { createServiceLogger } from '../../utils/logger-factory.js';
+const logger = createServiceLogger('API-HANDLER');
+export const createApiHandler = apiService => {
+  let vizzlyDisabled = false;
+  let screenshotCount = 0;
+  const handleScreenshot = async (buildId, name, image, properties = {}) => {
+    if (vizzlyDisabled) {
+      logger.debug(`Screenshot captured (Vizzly disabled): ${name}`);
+      return {
+        statusCode: 200,
+        body: {
+          success: true,
+          disabled: true,
+          count: ++screenshotCount,
+          message: `Vizzly disabled - ${screenshotCount} screenshots captured but not uploaded`
+        }
+      };
+    }
+    if (!buildId) {
+      return {
+        statusCode: 400,
+        body: {
+          error: 'Build ID is required for screenshot upload'
+        }
+      };
+    }
+    if (!apiService) {
+      return {
+        statusCode: 500,
+        body: {
+          error: 'API service not available'
+        }
+      };
+    }
+    try {
+      const imageBuffer = Buffer.from(image, 'base64');
+      const result = await apiService.uploadScreenshot(buildId, name, imageBuffer, properties ?? {});
+      if (result.skipped) {
+        logger.debug(`Screenshot already exists, skipped: ${name}`);
+      } else {
+        logger.debug(`Screenshot uploaded: ${name}`);
+      }
+      if (!result.skipped) {
+        screenshotCount++;
+      }
+      return {
+        statusCode: 200,
+        body: {
+          success: true,
+          name,
+          skipped: result.skipped,
+          count: screenshotCount
+        }
+      };
+    } catch (uploadError) {
+      logger.error(`❌ Failed to upload screenshot ${name}:`, uploadError.message);
+      vizzlyDisabled = true;
+      const disabledMessage = '⚠️  Vizzly disabled due to upload error - continuing tests without visual testing';
+      logger.warn(disabledMessage);
+      return {
+        statusCode: 200,
+        body: {
+          success: true,
+          name,
+          disabled: true,
+          message: disabledMessage
+        }
+      };
+    }
+  };
+  const getScreenshotCount = () => screenshotCount;
+  const cleanup = () => {
+    vizzlyDisabled = false;
+    screenshotCount = 0;
+    logger.debug('API handler cleanup completed');
+  };
+  return {
+    handleScreenshot,
+    getScreenshotCount,
+    cleanup
+  };
+};

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

@@ -0,0 +1,138 @@
+import { Buffer } from 'buffer';
+import { createServiceLogger } from '../../utils/logger-factory.js';
+import { TddService } from '../../services/tdd-service.js';
+import { colors } from '../../utils/colors.js';
+const logger = createServiceLogger('TDD-HANDLER');
+export const createTddHandler = (config, workingDir, baselineBuild, baselineComparison) => {
+  const tddService = new TddService(config, workingDir);
+  const builds = new Map();
+  const initialize = async () => {
+    logger.info('🔄 TDD mode enabled - setting up local comparison...');
+    const baseline = await tddService.loadBaseline();
+    if (!baseline) {
+      if (config.apiKey) {
+        logger.info('📥 No local baseline found, downloading from Vizzly...');
+        await tddService.downloadBaselines(baselineBuild, baselineComparison);
+      } else {
+        logger.info('📝 No local baseline found and no API token - all screenshots will be marked as new');
+      }
+    } else {
+      logger.info(`✅ Using existing baseline: ${colors.cyan(baseline.buildName)}`);
+    }
+  };
+  const registerBuild = buildId => {
+    builds.set(buildId, {
+      id: buildId,
+      name: `TDD Build ${buildId}`,
+      branch: 'current',
+      environment: 'test',
+      screenshots: [],
+      createdAt: Date.now()
+    });
+    logger.debug(`Registered TDD build: ${buildId}`);
+  };
+  const handleScreenshot = async (buildId, name, image, properties = {}) => {
+    const build = builds.get(buildId);
+    if (!build) {
+      throw new Error(`Build ${buildId} not found`);
+    }
+    const screenshot = {
+      name,
+      imageData: image,
+      properties,
+      timestamp: Date.now()
+    };
+    build.screenshots.push(screenshot);
+    const imageBuffer = Buffer.from(image, 'base64');
+    const comparison = await tddService.compareScreenshot(name, imageBuffer, properties);
+    if (comparison.status === 'failed') {
+      return {
+        statusCode: 422,
+        body: {
+          error: 'Visual difference detected',
+          details: `Screenshot '${name}' differs from baseline`,
+          comparison: {
+            name: comparison.name,
+            status: comparison.status,
+            baseline: comparison.baseline,
+            current: comparison.current,
+            diff: comparison.diff
+          },
+          tddMode: true
+        }
+      };
+    }
+    if (comparison.status === 'baseline-updated') {
+      return {
+        statusCode: 200,
+        body: {
+          status: 'success',
+          message: `Baseline updated for ${name}`,
+          comparison: {
+            name: comparison.name,
+            status: comparison.status,
+            baseline: comparison.baseline,
+            current: comparison.current
+          },
+          tddMode: true
+        }
+      };
+    }
+    if (comparison.status === 'error') {
+      return {
+        statusCode: 500,
+        body: {
+          error: `Comparison failed: ${comparison.error}`,
+          tddMode: true
+        }
+      };
+    }
+    logger.debug(`✅ TDD: ${comparison.status.toUpperCase()} ${name}`);
+    return {
+      statusCode: 200,
+      body: {
+        success: true,
+        comparison: {
+          name: comparison.name,
+          status: comparison.status
+        },
+        tddMode: true
+      }
+    };
+  };
+  const getScreenshotCount = buildId => {
+    const build = builds.get(buildId);
+    return build ? build.screenshots.length : 0;
+  };
+  const finishBuild = async buildId => {
+    const build = builds.get(buildId);
+    if (!build) {
+      throw new Error(`Build ${buildId} not found`);
+    }
+    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();
+    builds.delete(buildId);
+    return {
+      id: buildId,
+      name: build.name,
+      tddMode: true,
+      results,
+      url: null,
+      passed: results.failed === 0 && results.errors === 0
+    };
+  };
+  const cleanup = () => {
+    builds.clear();
+    logger.debug('TDD handler cleanup completed');
+  };
+  return {
+    initialize,
+    registerBuild,
+    handleScreenshot,
+    getScreenshotCount,
+    finishBuild,
+    cleanup
+  };
+};