@vizzly-testing/cli 0.3.2 → 0.5.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
 
@@ -279,6 +277,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.head_commit.message }}
+    VIZZLY_COMMIT_SHA: ${{ github.event.head_commit.id }}
+    VIZZLY_BRANCH: ${{ github.head_ref || github.ref_name }}
 ```
 
 ### GitLab CI
@@ -321,10 +323,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.head_commit.message }}
+  VIZZLY_COMMIT_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

@@ -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,36 +38,29 @@ 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);
-});
-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) => {
-  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
-    };
+  const {
+    result,
+    cleanup
+  } = await tddCommand(command, options, globalOptions);
 
-    // 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;
+  // 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();
 
   // Validate options
   const validationErrors = validateRunOptions(command, options);
@@ -76,7 +69,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

@@ -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
@@ -55,14 +55,14 @@ 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,
         port: config.server.port,
         timeout: config.server.timeout,
-        tddMode: options.tdd || false,
         branch,
         commit: commit?.substring(0, 7),
         message,
@@ -76,9 +76,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 +113,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 +146,9 @@ 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,
+      pullRequestNumber
     };
 
     // Start test run
@@ -172,13 +183,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

@@ -8,6 +8,7 @@ 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
@@ -17,20 +18,17 @@ export async function tddCommand(testCommand, options = {}, globalOptions = {})
     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 = {
@@ -166,17 +164,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')) {
-      ui.error('Visual differences detected in TDD mode', {}, 1);
+    // 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);
     }
-    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';
 
 /**
@@ -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) {
@@ -68,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', {
@@ -94,21 +98,54 @@ 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) : {},
+      pullRequestNumber,
       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 +175,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
+  };
+};