@vizzly-testing/cli 0.1.0

package/dist/client/index.js

@@ -0,0 +1,237 @@
+/**
+ * @module @vizzly-testing/cli/client
+ * @description Thin client for test runners - minimal API for taking screenshots
+ */
+
+import { isVizzlyEnabled, getServerUrl, getBuildId, isTddMode, setVizzlyEnabled } from '../utils/environment-config.js';
+
+// Internal client state
+let currentClient = null;
+let isDisabled = false;
+
+/**
+ * Check if Vizzly is currently disabled
+ * @private
+ * @returns {boolean} True if disabled via environment variable or auto-disabled due to failure
+ */
+function isVizzlyDisabled() {
+  return !isVizzlyEnabled() || isDisabled;
+}
+
+/**
+ * Disable Vizzly SDK for the current session
+ * @private
+ * @param {string} [reason] - Optional reason for disabling
+ */
+function disableVizzly(reason = 'disabled') {
+  isDisabled = true;
+  currentClient = null;
+  if (reason !== 'disabled') {
+    console.warn(`Vizzly SDK disabled due to ${reason}. Screenshots will be skipped for the remainder of this session.`);
+  }
+}
+
+/**
+ * Get the current client instance
+ * @private
+ */
+function getClient() {
+  if (isVizzlyDisabled()) {
+    return null;
+  }
+  if (!currentClient) {
+    // Only try to initialize if VIZZLY_ENABLED is explicitly true
+    const serverUrl = getServerUrl();
+    if (serverUrl && isVizzlyEnabled()) {
+      currentClient = createSimpleClient(serverUrl);
+    }
+  }
+  return currentClient;
+}
+
+/**
+ * Create a simple HTTP client for screenshots
+ * @private
+ */
+function createSimpleClient(serverUrl) {
+  return {
+    async screenshot(name, imageBuffer, options = {}) {
+      try {
+        const response = await fetch(`${serverUrl}/screenshot`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json'
+          },
+          body: JSON.stringify({
+            buildId: getBuildId(),
+            name,
+            image: imageBuffer.toString('base64'),
+            properties: options.properties || {},
+            threshold: options.threshold || 0,
+            variant: options.variant,
+            fullPage: options.fullPage || false
+          })
+        });
+        if (!response.ok) {
+          const errorData = await response.json().catch(async () => {
+            const errorText = await response.text().catch(() => 'Unknown error');
+            return {
+              error: errorText
+            };
+          });
+
+          // In TDD mode, if we get 422 (visual difference), throw with clean message
+          if (response.status === 422 && errorData.tddMode && errorData.comparison) {
+            const comp = errorData.comparison;
+            throw new Error(`Visual difference detected in "${name}"\n` + `  Baseline: ${comp.baseline}\n` + `  Current:  ${comp.current}\n` + `  Diff:     ${comp.diff}`);
+          }
+          throw new Error(`Screenshot failed: ${response.status} ${response.statusText} - ${errorData.error || 'Unknown error'}`);
+        }
+        return await response.json();
+      } catch (error) {
+        // In TDD mode with visual differences, throw the error to fail the test
+        if (error.message.includes('Visual difference detected')) {
+          // Clean output for TDD mode - don't spam with additional logs
+          throw error;
+        }
+        console.error(`Failed to save screenshot "${name}":`, error.message);
+        console.error(`Vizzly screenshot failed for ${name}: ${error.message}`);
+        if (error.message.includes('fetch') || error.code === 'ECONNREFUSED') {
+          console.error(`Server URL: ${serverUrl}/screenshot`);
+          console.error('This usually means the Vizzly server is not running or not accessible');
+          console.error('Check that the server is started and the port is correct');
+        } else if (error.message.includes('404') || error.message.includes('Not Found')) {
+          console.error(`Server URL: ${serverUrl}/screenshot`);
+          console.error('The screenshot endpoint was not found - check server configuration');
+        }
+
+        // Disable the SDK after first failure to prevent spam
+        disableVizzly('failure');
+
+        // Don't throw - just return silently to not break tests (except TDD mode)
+        return null;
+      }
+    },
+    async flush() {
+      // Simple client doesn't need explicit flushing
+      return Promise.resolve();
+    }
+  };
+}
+
+/**
+ * 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 async function vizzlyScreenshot(name, imageBuffer, options = {}) {
+  if (isVizzlyDisabled()) {
+    return; // Silently skip when disabled
+  }
+  const client = getClient();
+  if (!client) {
+    console.warn('Vizzly client not initialized. Screenshots will be skipped.');
+    return;
+  }
+  return client.screenshot(name, imageBuffer, options);
+}
+
+/**
+ * Wait for all queued screenshots to be processed
+ *
+ * @returns {Promise<void>}
+ *
+ * @example
+ * afterAll(async () => {
+ *   await vizzlyFlush();
+ * });
+ */
+export async function vizzlyFlush() {
+  const client = getClient();
+  if (client) {
+    return client.flush();
+  }
+}
+
+/**
+ * Check if the Vizzly client is initialized and ready
+ *
+ * @returns {boolean} True if client is ready, false otherwise
+ */
+export function isVizzlyReady() {
+  return !isVizzlyDisabled() && getClient() !== null;
+}
+
+/**
+ * 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 = {}) {
+  if (config.serverUrl) {
+    currentClient = createSimpleClient(config.serverUrl);
+  }
+  if (typeof config.enabled === 'boolean') {
+    setVizzlyEnabled(config.enabled);
+    if (!config.enabled) {
+      disableVizzly();
+    } else {
+      isDisabled = false;
+    }
+  }
+}
+
+/**
+ * Enable or disable screenshot capture
+ * @param {boolean} enabled - Whether to enable screenshots
+ */
+export function setEnabled(enabled) {
+  configure({
+    enabled
+  });
+}
+
+/**
+ * Get information about Vizzly client state
+ * @returns {Object} Client information
+ */
+export function getVizzlyInfo() {
+  const client = getClient();
+  return {
+    enabled: !isVizzlyDisabled(),
+    serverUrl: getServerUrl(),
+    ready: !isVizzlyDisabled() && client !== null,
+    buildId: getBuildId(),
+    tddMode: isTddMode(),
+    disabled: isVizzlyDisabled()
+  };
+}

package/dist/commands/doctor.js

@@ -0,0 +1,158 @@
+import { URL } from 'url';
+import { loadConfig } from '../utils/config-loader.js';
+import { ConsoleUI } from '../utils/console-ui.js';
+import { ApiService } from '../services/api-service.js';
+import { ConfigError } from '../errors/vizzly-error.js';
+import { getApiToken } from '../utils/environment-config.js';
+
+/**
+ * Doctor command implementation - Run diagnostics to check environment
+ * @param {Object} options - Command options
+ * @param {Object} globalOptions - Global CLI options
+ */
+export async function doctorCommand(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
+
+  const diagnostics = {
+    environment: {
+      nodeVersion: null,
+      nodeVersionValid: null
+    },
+    configuration: {
+      apiUrl: null,
+      apiUrlValid: null,
+      threshold: null,
+      thresholdValid: null,
+      port: null
+    },
+    connectivity: {
+      checked: false,
+      ok: null,
+      error: null
+    }
+  };
+  let hasErrors = false;
+  try {
+    // Determine if we'll attempt remote checks (API connectivity)
+    const willCheckConnectivity = Boolean(options.api || getApiToken());
+
+    // Announce preflight, indicating local-only when no token/connectivity is planned
+    ui.info(`Running Vizzly preflight${willCheckConnectivity ? '' : ' (local checks only)'}...`);
+
+    // Node.js version check (require >= 20)
+    const nodeVersion = process.version;
+    const nodeMajor = parseInt(nodeVersion.slice(1).split('.')[0], 10);
+    diagnostics.environment.nodeVersion = nodeVersion;
+    diagnostics.environment.nodeVersionValid = nodeMajor >= 20;
+    if (nodeMajor >= 20) {
+      ui.success(`Node.js version: ${nodeVersion} (supported)`);
+    } else {
+      hasErrors = true;
+      ui.error('Node.js version must be >= 20', {}, 0);
+    }
+
+    // Load configuration (apply global CLI overrides like --config only)
+    const config = await loadConfig(globalOptions.config);
+
+    // Validate apiUrl
+    diagnostics.configuration.apiUrl = config.apiUrl;
+    try {
+      const url = new URL(config.apiUrl);
+      if (!['http:', 'https:'].includes(url.protocol)) {
+        throw new ConfigError('URL must use http or https');
+      }
+      diagnostics.configuration.apiUrlValid = true;
+      ui.success(`API URL: ${config.apiUrl}`);
+    } catch (e) {
+      diagnostics.configuration.apiUrlValid = false;
+      hasErrors = true;
+      ui.error('Invalid apiUrl in configuration (set VIZZLY_API_URL or config file)', e, 0);
+    }
+
+    // Validate threshold (0..1 inclusive)
+    const threshold = Number(config?.comparison?.threshold);
+    diagnostics.configuration.threshold = threshold;
+    const thresholdValid = Number.isFinite(threshold) && threshold >= 0 && threshold <= 1;
+    diagnostics.configuration.thresholdValid = thresholdValid;
+    if (thresholdValid) {
+      ui.success(`Threshold: ${threshold}`);
+    } else {
+      hasErrors = true;
+      ui.error('Invalid threshold (expected number between 0 and 1)', {}, 0);
+    }
+
+    // Report effective port without binding
+    const port = config?.server?.port ?? 47392;
+    diagnostics.configuration.port = port;
+    ui.info(`Effective port: ${port}`);
+
+    // Optional: API connectivity check when --api is provided or VIZZLY_TOKEN is present
+    const autoApi = Boolean(getApiToken());
+    if (options.api || autoApi) {
+      diagnostics.connectivity.checked = true;
+      if (!config.apiKey) {
+        diagnostics.connectivity.ok = false;
+        diagnostics.connectivity.error = 'Missing API token (VIZZLY_TOKEN)';
+        hasErrors = true;
+        ui.error('Missing API token for connectivity check', {}, 0);
+      } else {
+        ui.progress('Checking API connectivity...');
+        try {
+          const api = new ApiService({
+            baseUrl: config.apiUrl,
+            token: config.apiKey,
+            command: 'doctor'
+          });
+          // Minimal, read-only call
+          await api.getBuilds({
+            limit: 1
+          });
+          diagnostics.connectivity.ok = true;
+          ui.success('API connectivity OK');
+        } catch (err) {
+          diagnostics.connectivity.ok = false;
+          diagnostics.connectivity.error = err?.message || String(err);
+          hasErrors = true;
+          ui.error('API connectivity failed', err, 0);
+        }
+      }
+    }
+
+    // Summary
+    if (hasErrors) {
+      ui.warning('Preflight completed with issues.');
+    } else {
+      ui.success('Preflight passed.');
+    }
+
+    // Emit structured data in json/verbose modes
+    if (globalOptions.json || globalOptions.verbose) {
+      ui.data({
+        passed: !hasErrors,
+        diagnostics,
+        timestamp: new Date().toISOString()
+      });
+    }
+  } catch (error) {
+    hasErrors = true;
+    ui.error('Failed to run preflight', error, 0);
+  } finally {
+    ui.cleanup();
+    if (hasErrors) process.exit(1);
+  }
+}
+
+/**
+ * Validate doctor options (no specific validation needed)
+ * @param {Object} options - Command options
+ */
+export function validateDoctorOptions() {
+  return []; // No specific validation for now
+}

package/dist/commands/init.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import fs from 'fs/promises';
+import path from 'path';
+import { VizzlyError } from '../errors/vizzly-error.js';
+import { createComponentLogger } from '../utils/logger-factory.js';
+
+/**
+ * Simple configuration setup for Vizzly CLI
+ */
+export class InitCommand {
+  constructor(logger) {
+    this.logger = logger || createComponentLogger('INIT', {
+      level: 'info'
+    });
+  }
+  async run(options = {}) {
+    this.logger.info('🎯 Initializing Vizzly configuration...\n');
+    try {
+      // Check for existing config
+      const configPath = path.join(process.cwd(), 'vizzly.config.js');
+      const hasConfig = await this.fileExists(configPath);
+      if (hasConfig && !options.force) {
+        this.logger.info('❌ A vizzly.config.js file already exists. Use --force to overwrite.');
+        return;
+      }
+
+      // Generate config file with defaults
+      await this.generateConfigFile(configPath);
+
+      // Show next steps
+      this.showNextSteps();
+      this.logger.info('\n✅ Vizzly CLI setup complete!');
+    } catch (error) {
+      throw new VizzlyError('Failed to initialize Vizzly configuration', 'INIT_FAILED', {
+        error: error.message
+      });
+    }
+  }
+  async generateConfigFile(configPath) {
+    const configContent = `export default {
+  // API configuration
+  // Set VIZZLY_TOKEN environment variable or uncomment and set here:
+  // apiToken: 'your-token-here',
+  
+  // Screenshot configuration
+  screenshots: {
+    directory: './screenshots',
+    formats: ['png']
+  },
+  
+  // Server configuration
+  server: {
+    port: 47392,
+    screenshotPath: '/screenshot'
+  },
+  
+  // Comparison configuration
+  comparison: {
+    threshold: 0.1,
+    ignoreAntialiasing: true
+  },
+  
+  // Upload configuration
+  upload: {
+    concurrency: 5,
+    timeout: 30000
+  }
+};
+`;
+    await fs.writeFile(configPath, configContent, 'utf8');
+    this.logger.info(`📄 Created vizzly.config.js`);
+  }
+  showNextSteps() {
+    this.logger.info('\n📚 Next steps:');
+    this.logger.info('   1. Set your API token:');
+    this.logger.info('      export VIZZLY_TOKEN="your-api-key"');
+    this.logger.info('   2. Run your tests with Vizzly:');
+    this.logger.info('      npx vizzly run "npm test"');
+    this.logger.info('   3. Upload screenshots:');
+    this.logger.info('      npx vizzly upload ./screenshots');
+  }
+  async fileExists(filePath) {
+    try {
+      await fs.access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+// Export factory function for CLI
+export function createInitCommand(options) {
+  const command = new InitCommand(options.logger);
+  return () => command.run(options);
+}
+
+// Simple export for direct CLI usage
+export async function init(options = {}) {
+  const command = new InitCommand();
+  return await command.run(options);
+}