@vizzly-testing/cli 0.1.0

package/dist/services/test-runner.js

@@ -0,0 +1,210 @@
+/**
+ * Test Runner Service
+ * Orchestrates the test execution flow
+ */
+
+import { BaseService } from './base-service.js';
+import { VizzlyError } from '../errors/vizzly-error.js';
+import { spawn } from 'child_process';
+export class TestRunner extends BaseService {
+  constructor(config, logger, buildManager, serverManager, tddService) {
+    super(config, logger);
+    this.buildManager = buildManager;
+    this.serverManager = serverManager;
+    this.tddService = tddService;
+    this.testProcess = null;
+  }
+  async run(options) {
+    const {
+      testCommand,
+      tdd,
+      allowNoToken
+    } = options;
+    const startTime = Date.now();
+    let buildId = null;
+    if (!testCommand) {
+      throw new VizzlyError('No test command provided', 'TEST_COMMAND_MISSING');
+    }
+
+    // If no token is allowed and not in TDD mode, just run the command without Vizzly integration
+    if (allowNoToken && !this.config.apiKey && !tdd) {
+      const env = {
+        ...process.env,
+        VIZZLY_ENABLED: 'false'
+      };
+      await this.executeTestCommand(testCommand, env);
+      return {
+        testsPassed: 1,
+        testsFailed: 0,
+        screenshotsCaptured: 0
+      };
+    }
+    try {
+      let buildInfo = null;
+      let buildUrl = null;
+      let screenshotCount = 0;
+      if (tdd) {
+        // TDD mode: create local build for fast feedback
+        this.logger.debug('TDD mode: creating local build...');
+        const build = await this.buildManager.createBuild(options);
+        buildId = build.id;
+        this.logger.debug(`TDD build created with ID: ${build.id}`);
+      } else if (options.eager) {
+        // Eager mode: create build immediately via API
+        this.logger.debug('Eager mode: creating build via API...');
+        const apiService = await this.createApiService();
+        if (apiService) {
+          const buildResult = await apiService.createBuild({
+            build: {
+              name: options.buildName || `Test Run ${new Date().toISOString()}`,
+              branch: options.branch || 'main',
+              environment: options.environment || 'test',
+              commit_sha: options.commit,
+              commit_message: options.message
+            }
+          });
+          buildId = buildResult.id;
+          buildUrl = buildResult.url;
+          this.logger.debug(`Eager build created with ID: ${buildId}`);
+          if (buildUrl) {
+            this.logger.info(`Build URL: ${buildUrl}`);
+          }
+
+          // Emit build created event for eager mode
+          this.emit('build-created', {
+            buildId: buildResult.id,
+            url: buildResult.url,
+            name: buildResult.name || options.buildName
+          });
+        } else {
+          this.logger.warn('No API key available for eager build creation, falling back to lazy mode');
+        }
+      } else {
+        // Lazy mode: prepare build info for API creation on first screenshot
+        buildInfo = {
+          buildName: options.buildName || `Test Run ${new Date().toISOString()}`,
+          branch: options.branch || 'main',
+          environment: options.environment || 'test',
+          commitSha: options.commit,
+          commitMessage: options.message
+        };
+      }
+
+      // Start server with appropriate configuration
+      const mode = tdd ? 'tdd' : options.eager ? 'eager' : 'lazy';
+      await this.serverManager.start(buildId, buildInfo, mode);
+
+      // Forward server events
+      if (this.serverManager.server && this.serverManager.server.emitter) {
+        this.serverManager.server.emitter.on('build-created', buildInfo => {
+          // Update local buildId and buildUrl from server
+          buildId = buildInfo.buildId;
+          buildUrl = buildInfo.url;
+          this.emit('build-created', buildInfo);
+        });
+        this.serverManager.server.emitter.on('screenshot-captured', screenshotInfo => {
+          screenshotCount++;
+          this.emit('screenshot-captured', screenshotInfo);
+        });
+      }
+      if (tdd) {
+        this.logger.debug('TDD service ready for comparisons');
+      }
+      const env = {
+        ...process.env,
+        VIZZLY_SERVER_URL: `http://localhost:${this.config.server.port}`,
+        VIZZLY_BUILD_ID: buildId || 'lazy',
+        // Use 'lazy' for API-driven builds
+        VIZZLY_ENABLED: 'true',
+        VIZZLY_SET_BASELINE: options.setBaseline || options['set-baseline'] ? 'true' : 'false'
+      };
+      await this.executeTestCommand(testCommand, env);
+
+      // Finalize builds based on mode
+      const executionTime = Date.now() - startTime;
+      await this.finalizeBuild(buildId, tdd, true, executionTime);
+      return {
+        buildId: buildId,
+        url: buildUrl,
+        testsPassed: 1,
+        testsFailed: 0,
+        screenshotsCaptured: screenshotCount
+      };
+    } catch (error) {
+      this.logger.error('Test run failed:', error);
+
+      // Finalize builds on failure too
+      const executionTime = Date.now() - startTime;
+      await this.finalizeBuild(buildId, tdd, false, executionTime);
+      throw error;
+    } finally {
+      await this.serverManager.stop();
+      if (tdd && this.tddService && typeof this.tddService.stop === 'function') {
+        await this.tddService.stop();
+      }
+    }
+  }
+  async createApiService() {
+    if (!this.config.apiKey) return null;
+    const {
+      ApiService
+    } = await import('./api-service.js');
+    return new ApiService({
+      ...this.config,
+      command: 'run'
+    }, {
+      logger: this.logger
+    });
+  }
+  async finalizeBuild(buildId, isTddMode, success, executionTime) {
+    if (!buildId) {
+      this.logger.debug('No buildId to finalize');
+      return;
+    }
+    try {
+      if (isTddMode) {
+        // TDD mode: use buildManager for local builds
+        if (this.buildManager.getCurrentBuild()) {
+          await this.buildManager.finalizeBuild(buildId, {
+            success
+          });
+          this.logger.debug(`TDD build ${buildId} finalized with success: ${success}`);
+        }
+      } else {
+        // API mode (eager/lazy): use API service to update build status
+        const apiService = await this.createApiService();
+        if (apiService) {
+          await apiService.finalizeBuild(buildId, success, executionTime);
+        }
+      }
+    } catch (error) {
+      // Don't fail the entire run if build finalization fails
+      this.logger.warn(`Failed to finalize build ${buildId}:`, error.message);
+    }
+  }
+  async executeTestCommand(testCommand, env) {
+    return new Promise((resolve, reject) => {
+      // Use shell to execute the full command string
+      this.testProcess = spawn(testCommand, {
+        env,
+        stdio: 'inherit',
+        shell: true
+      });
+      this.testProcess.on('error', error => {
+        reject(new VizzlyError(`Failed to run test command: ${error.message}`), 'TEST_COMMAND_FAILED');
+      });
+      this.testProcess.on('exit', code => {
+        if (code !== 0) {
+          reject(new VizzlyError(`Test command exited with code ${code}`, 'TEST_COMMAND_FAILED'));
+        } else {
+          resolve();
+        }
+      });
+    });
+  }
+  async cancel() {
+    if (this.testProcess) {
+      this.testProcess.kill('SIGTERM');
+    }
+  }
+}

package/dist/services/uploader.js

@@ -0,0 +1,413 @@
+/**
+ * Vizzly Screenshot Uploader
+ * Handles screenshot uploads to the Vizzly platform
+ */
+
+import { glob } from 'glob';
+import { readFile, stat } from 'fs/promises';
+import { basename } from 'path';
+import crypto from 'crypto';
+import { createUploaderLogger } from '../utils/logger-factory.js';
+import { ApiService } from './api-service.js';
+import { getDefaultBranch } from '../utils/git.js';
+import { UploadError, TimeoutError, ValidationError } from '../errors/vizzly-error.js';
+const DEFAULT_BATCH_SIZE = 10;
+const DEFAULT_SHA_CHECK_BATCH_SIZE = 100;
+const DEFAULT_TIMEOUT = 30000; // 30 seconds
+
+/**
+ * Create a new uploader instance
+ */
+export function createUploader({
+  apiKey,
+  apiUrl,
+  userAgent,
+  command,
+  upload: uploadConfig = {}
+}, options = {}) {
+  const logger = options.logger || createUploaderLogger(options);
+  const signal = options.signal || new AbortController().signal;
+  const api = new ApiService({
+    baseUrl: apiUrl,
+    token: apiKey,
+    command: command || 'upload',
+    userAgent,
+    allowNoToken: true
+  });
+
+  // Resolve tunable parameters from options or config
+  const batchSize = Number(options.batchSize ?? uploadConfig?.batchSize ?? DEFAULT_BATCH_SIZE);
+  const TIMEOUT_MS = Number(options.timeout ?? uploadConfig?.timeout ?? DEFAULT_TIMEOUT);
+
+  /**
+   * Upload screenshots to Vizzly
+   */
+  async function upload({
+    screenshotsDir,
+    buildName,
+    branch,
+    commit,
+    message,
+    environment = 'production',
+    threshold,
+    onProgress = () => {}
+  }) {
+    try {
+      // Validate required config
+      if (!apiKey) {
+        throw new ValidationError('API key is required', {
+          config: {
+            apiKey,
+            apiUrl
+          }
+        });
+      }
+      if (!screenshotsDir) {
+        throw new ValidationError('Screenshots directory is required');
+      }
+      const stats = await stat(screenshotsDir);
+      if (!stats.isDirectory()) {
+        throw new ValidationError(`${screenshotsDir} is not a directory`);
+      }
+
+      // Find screenshots
+      const files = await findScreenshots(screenshotsDir);
+      if (files.length === 0) {
+        throw new UploadError('No screenshot files found', {
+          directory: screenshotsDir,
+          pattern: '**/*.png'
+        });
+      }
+      onProgress({
+        phase: 'scanning',
+        total: files.length
+      });
+
+      // Process files to get metadata
+      const fileMetadata = await processFiles(files, signal, current => onProgress({
+        phase: 'processing',
+        current,
+        total: files.length
+      }));
+
+      // Check which files need uploading
+      const {
+        toUpload,
+        existing
+      } = await checkExistingFiles(fileMetadata, api, signal);
+      onProgress({
+        phase: 'deduplication',
+        toUpload: toUpload.length,
+        existing: existing.length,
+        total: files.length
+      });
+
+      // Create build and upload files
+      const result = await uploadFiles({
+        toUpload,
+        existing,
+        buildInfo: {
+          name: buildName || `Upload ${new Date().toISOString()}`,
+          branch: branch || (await getDefaultBranch()) || 'main',
+          commitSha: commit,
+          commitMessage: message,
+          environment,
+          threshold
+        },
+        api,
+        signal,
+        batchSize: batchSize,
+        onProgress: current => onProgress({
+          phase: 'uploading',
+          current,
+          total: toUpload.length
+        })
+      });
+      onProgress({
+        phase: 'completed',
+        buildId: result.buildId,
+        url: result.url
+      });
+      return {
+        success: true,
+        buildId: result.buildId,
+        url: result.url,
+        stats: {
+          total: files.length,
+          uploaded: toUpload.length,
+          skipped: existing.length
+        }
+      };
+    } catch (error) {
+      logger.error('Upload failed:', error);
+
+      // Re-throw if already a VizzlyError
+      if (error.name && error.name.includes('Error') && error.code) {
+        throw error;
+      }
+
+      // Wrap unknown errors
+      throw new UploadError(`Upload failed: ${error.message}`, {
+        originalError: error.message,
+        stack: error.stack
+      });
+    }
+  }
+
+  /**
+   * Wait for a build to complete
+   */
+  async function waitForBuild(buildId, timeout = TIMEOUT_MS) {
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeout) {
+      if (signal.aborted) {
+        throw new UploadError('Operation cancelled', {
+          buildId
+        });
+      }
+      let resp;
+      try {
+        resp = await api.request(`/api/sdk/builds/${buildId}`, {
+          signal
+        });
+      } catch (err) {
+        const match = String(err?.message || '').match(/API request failed: (\d+)/);
+        const code = match ? match[1] : 'unknown';
+        throw new UploadError(`Failed to check build status: ${code}`);
+      }
+      const build = resp?.build ?? resp;
+      if (build.status === 'completed') {
+        // Extract comparison data for the response
+        const result = {
+          status: 'completed',
+          build
+        };
+
+        // Add comparison summary if available
+        if (typeof build.comparisonsTotal === 'number') {
+          result.comparisons = build.comparisonsTotal;
+          result.passedComparisons = build.comparisonsPassed || 0;
+          result.failedComparisons = build.comparisonsFailed || 0;
+        } else {
+          // Ensure failedComparisons is always a number, even when comparison data is missing
+          // This prevents the run command exit code check from failing
+          result.passedComparisons = 0;
+          result.failedComparisons = 0;
+        }
+
+        // Add build URL if available
+        if (build.url) {
+          result.url = build.url;
+        }
+        return result;
+      }
+      if (build.status === 'failed') {
+        throw new UploadError(`Build failed: ${build.error || 'Unknown error'}`);
+      }
+      await new Promise(resolve => setTimeout(resolve, 2000));
+    }
+    throw new TimeoutError(`Build timed out after ${timeout}ms`, {
+      buildId,
+      timeout,
+      elapsed: Date.now() - startTime
+    });
+  }
+  return {
+    upload,
+    waitForBuild
+  };
+}
+
+/**
+ * Find all PNG screenshots in a directory
+ */
+async function findScreenshots(directory) {
+  const pattern = `${directory}/**/*.png`;
+  return glob(pattern, {
+    absolute: true
+  });
+}
+
+/**
+ * Process files to extract metadata and compute hashes
+ */
+async function* processFilesGenerator(files, signal) {
+  for (const filePath of files) {
+    if (signal.aborted) throw new UploadError('Operation cancelled');
+    const buffer = await readFile(filePath);
+    const sha256 = crypto.createHash('sha256').update(buffer).digest('hex');
+    yield {
+      path: filePath,
+      filename: basename(filePath),
+      buffer,
+      sha256
+    };
+  }
+}
+async function processFiles(files, signal, onProgress) {
+  const results = [];
+  let count = 0;
+  for await (const file of processFilesGenerator(files, signal)) {
+    results.push(file);
+    count++;
+    if (count % 10 === 0 || count === files.length) {
+      onProgress(count);
+    }
+  }
+  return results;
+}
+
+/**
+ * Check which files already exist on the server
+ */
+async function checkExistingFiles(fileMetadata, api, signal) {
+  const allShas = fileMetadata.map(f => f.sha256);
+  const existingShas = new Set();
+
+  // Check in batches
+  for (let i = 0; i < allShas.length; i += DEFAULT_SHA_CHECK_BATCH_SIZE) {
+    if (signal.aborted) throw new UploadError('Operation cancelled');
+    const batch = allShas.slice(i, i + DEFAULT_SHA_CHECK_BATCH_SIZE);
+    try {
+      const res = await api.request('/api/sdk/check-shas', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+          shas: batch
+        }),
+        signal
+      });
+      const {
+        existing = []
+      } = res || {};
+      existing.forEach(sha => existingShas.add(sha));
+    } catch (error) {
+      // Continue without deduplication on error
+      console.debug('SHA check failed, continuing without deduplication:', error.message);
+    }
+  }
+  return {
+    toUpload: fileMetadata.filter(f => !existingShas.has(f.sha256)),
+    existing: fileMetadata.filter(f => existingShas.has(f.sha256))
+  };
+}
+
+/**
+ * Upload files to Vizzly
+ */
+async function uploadFiles({
+  toUpload,
+  existing,
+  buildInfo,
+  api,
+  signal,
+  batchSize,
+  onProgress
+}) {
+  let buildId = null;
+  let result = null;
+
+  // If all files exist, just create a build
+  if (toUpload.length === 0) {
+    return createBuildWithExisting({
+      existing,
+      buildInfo,
+      api,
+      signal
+    });
+  }
+
+  // Upload in batches
+  for (let i = 0; i < toUpload.length; i += batchSize) {
+    if (signal.aborted) throw new UploadError('Operation cancelled');
+    const batch = toUpload.slice(i, i + batchSize);
+    const isFirstBatch = i === 0;
+    const form = new FormData();
+    if (isFirstBatch) {
+      // First batch creates the build
+      form.append('build_name', buildInfo.name);
+      form.append('branch', buildInfo.branch);
+      form.append('environment', buildInfo.environment);
+      if (buildInfo.commitSha) form.append('commit_sha', buildInfo.commitSha);
+      if (buildInfo.commitMessage) form.append('commit_message', buildInfo.commitMessage);
+      if (buildInfo.threshold !== undefined) form.append('threshold', buildInfo.threshold.toString());
+
+      // Include existing SHAs
+      if (existing.length > 0) {
+        form.append('existing_shas', JSON.stringify(existing.map(f => f.sha256)));
+      }
+    } else {
+      // Subsequent batches add to existing build
+      form.append('build_id', buildId);
+    }
+
+    // Add files
+    for (const file of batch) {
+      const blob = new Blob([file.buffer], {
+        type: 'image/png'
+      });
+      form.append('screenshots', blob, file.filename);
+    }
+    try {
+      result = await api.request('/api/sdk/upload', {
+        method: 'POST',
+        body: form,
+        signal,
+        headers: {}
+      });
+    } catch (err) {
+      throw new UploadError(`Upload failed: ${err.message}`, {
+        batch: i / batchSize + 1
+      });
+    }
+    if (isFirstBatch && result.build?.id) {
+      buildId = result.build.id;
+    }
+    onProgress(i + batch.length);
+  }
+  return {
+    buildId: result.build?.id || buildId,
+    url: result.build?.url || result.url
+  };
+}
+
+/**
+ * Create a build with only existing files
+ */
+async function createBuildWithExisting({
+  existing,
+  buildInfo,
+  api,
+  signal
+}) {
+  const form = new FormData();
+  form.append('build_name', buildInfo.name);
+  form.append('branch', buildInfo.branch);
+  form.append('environment', buildInfo.environment);
+  form.append('existing_shas', JSON.stringify(existing.map(f => f.sha256)));
+  if (buildInfo.commitSha) form.append('commit_sha', buildInfo.commitSha);
+  if (buildInfo.commitMessage) form.append('commit_message', buildInfo.commitMessage);
+  if (buildInfo.threshold !== undefined) form.append('threshold', buildInfo.threshold.toString());
+  let result;
+  try {
+    result = await api.request('/api/sdk/upload', {
+      method: 'POST',
+      body: form,
+      signal,
+      headers: {}
+    });
+  } catch (err) {
+    throw new UploadError(`Failed to create build: ${err.message}`);
+  }
+  return {
+    buildId: result.build?.id,
+    url: result.build?.url || result.url
+  };
+}
+
+/**
+ * Uploader class for handling screenshot uploads
+ */
+// Legacy Uploader class removed — all functionality lives in createUploader.

package/dist/types/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/types/client/index.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Take a screenshot for visual regression testing
+ *
+ * @param {string} name - Unique name for the screenshot
+ * @param {Buffer} imageBuffer - PNG image data as a Buffer
+ * @param {Object} [options] - Optional configuration
+ * @param {Record<string, any>} [options.properties] - Additional properties to attach to the screenshot
+ * @param {number} [options.threshold=0] - Pixel difference threshold (0-100)
+ * @param {string} [options.variant] - Variant name for organizing screenshots
+ * @param {boolean} [options.fullPage=false] - Whether this is a full page screenshot
+ *
+ * @returns {Promise<void>}
+ *
+ * @example
+ * // Basic usage
+ * import { vizzlyScreenshot } from '@vizzly-testing/cli/client';
+ *
+ * const screenshot = await page.screenshot();
+ * await vizzlyScreenshot('homepage', screenshot);
+ *
+ * @example
+ * // With properties and threshold
+ * await vizzlyScreenshot('checkout-form', screenshot, {
+ *   properties: {
+ *     browser: 'chrome',
+ *     viewport: '1920x1080'
+ *   },
+ *   threshold: 5
+ * });
+ *
+ * @throws {VizzlyError} When screenshot capture fails or client is not initialized
+ */
+export function vizzlyScreenshot(name: string, imageBuffer: Buffer, options?: {
+    properties?: Record<string, any>;
+    threshold?: number;
+    variant?: string;
+    fullPage?: boolean;
+}): Promise<void>;
+/**
+ * Wait for all queued screenshots to be processed
+ *
+ * @returns {Promise<void>}
+ *
+ * @example
+ * afterAll(async () => {
+ *   await vizzlyFlush();
+ * });
+ */
+export function vizzlyFlush(): Promise<void>;
+/**
+ * Check if the Vizzly client is initialized and ready
+ *
+ * @returns {boolean} True if client is ready, false otherwise
+ */
+export function isVizzlyReady(): boolean;
+/**
+ * Configure the client with custom settings
+ *
+ * @param {Object} config - Configuration options
+ * @param {string} [config.serverUrl] - Server URL override
+ * @param {boolean} [config.enabled] - Enable/disable screenshots
+ */
+export function configure(config?: {
+    serverUrl?: string;
+    enabled?: boolean;
+}): void;
+/**
+ * Enable or disable screenshot capture
+ * @param {boolean} enabled - Whether to enable screenshots
+ */
+export function setEnabled(enabled: boolean): void;
+/**
+ * Get information about Vizzly client state
+ * @returns {Object} Client information
+ */
+export function getVizzlyInfo(): any;

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

@@ -0,0 +1,11 @@
+/**
+ * Doctor command implementation - Run diagnostics to check environment
+ * @param {Object} options - Command options
+ * @param {Object} globalOptions - Global CLI options
+ */
+export function doctorCommand(options?: any, globalOptions?: any): Promise<void>;
+/**
+ * Validate doctor options (no specific validation needed)
+ * @param {Object} options - Command options
+ */
+export function validateDoctorOptions(): any[];