@vizzly-testing/cli 0.16.0 → 0.16.2

package/dist/sdk/index.js

@@ -22,7 +22,7 @@ import { VizzlyError } from '../errors/vizzly-error.js';
 /**
  * Create a new Vizzly instance with custom configuration
  *
- * @param {import('../types').VizzlyConfig} [config] - Configuration options
+ * @param {Object} [config] - Configuration options
  * @returns {Promise<VizzlySDK>} Configured Vizzly SDK instance
  *
  * @example
@@ -147,7 +147,7 @@ export function createVizzly(config = {}, options = {}) {
  */
 export class VizzlySDK extends EventEmitter {
   /**
-   * @param {import('../types').VizzlyConfig} config - Configuration
+   * @param {Object} config - Configuration
    * @param {Object} services - Service instances
    */
   constructor(config, services) {
@@ -223,7 +223,7 @@ export class VizzlySDK extends EventEmitter {
    * Capture a screenshot
    * @param {string} name - Screenshot name
    * @param {Buffer|string} imageBuffer - Image data as a Buffer, or a file path to an image
-   * @param {import('../types').ScreenshotOptions} [options] - Options
+   * @param {Object} [options] - Options
    * @returns {Promise<void>}
    * @throws {VizzlyError} When server is not running
    * @throws {VizzlyError} When file path is provided but file doesn't exist
@@ -288,8 +288,8 @@ export class VizzlySDK extends EventEmitter {
 
   /**
    * Upload all captured screenshots
-   * @param {import('../types').UploadOptions} [options] - Upload options
-   * @returns {Promise<import('../types').UploadResult>} Upload result
+   * @param {Object} [options] - Upload options
+   * @returns {Promise<Object>} Upload result
    */
   async upload(options = {}) {
     if (!this.services?.uploader) {
@@ -332,7 +332,7 @@ export class VizzlySDK extends EventEmitter {
    * Run local comparison in TDD mode
    * @param {string} name - Screenshot name
    * @param {Buffer|string} imageBuffer - Current image as a Buffer, or a file path to an image
-   * @returns {Promise<import('../types').ComparisonResult>} Comparison result
+   * @returns {Promise<Object>} Comparison result
    * @throws {VizzlyError} When file path is provided but file doesn't exist
    * @throws {VizzlyError} When file cannot be read due to permissions or I/O errors
    */

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

@@ -1,14 +1,11 @@
 import { Buffer } from 'buffer';
 import { writeFileSync, readFileSync, existsSync } from 'fs';
 import { join, resolve } from 'path';
-import honeydiff from '@vizzly-testing/honeydiff';
+import { getDimensionsSync } from '@vizzly-testing/honeydiff';
 import * as output from '../../utils/output.js';
 import { TddService } from '../../services/tdd-service.js';
 import { sanitizeScreenshotName, validateScreenshotProperties } from '../../utils/security.js';
 import { detectImageInputType } from '../../utils/image-input-detector.js';
-let {
-  getDimensionsSync
-} = honeydiff;
 
 /**
  * Group comparisons by screenshot name with variant structure
@@ -142,9 +139,19 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
       // This ensures we update the correct variant even with same name
       const existingIndex = reportData.comparisons.findIndex(c => c.id === newComparison.id);
       if (existingIndex >= 0) {
-        reportData.comparisons[existingIndex] = newComparison;
+        // Preserve initialStatus from the original comparison
+        // This keeps sort order stable when status changes (e.g., after approval)
+        let initialStatus = reportData.comparisons[existingIndex].initialStatus;
+        reportData.comparisons[existingIndex] = {
+          ...newComparison,
+          initialStatus: initialStatus || newComparison.status
+        };
       } else {
-        reportData.comparisons.push(newComparison);
+        // New comparison - set initialStatus to current status
+        reportData.comparisons.push({
+          ...newComparison,
+          initialStatus: newComparison.status
+        });
       }
 
       // Generate grouped structure from flat comparisons

package/dist/services/test-runner.js

@@ -94,14 +94,6 @@ export class TestRunner extends EventEmitter {
 
       // Start server with appropriate handler
       await this.serverManager.start(buildId, tdd, options.setBaseline);
-
-      // Forward server events
-      if (this.serverManager.server?.emitter) {
-        this.serverManager.server.emitter.on('screenshot-captured', screenshotInfo => {
-          screenshotCount++;
-          this.emit('screenshot-captured', screenshotInfo);
-        });
-      }
       const env = {
         ...process.env,
         VIZZLY_SERVER_URL: `http://localhost:${this.config.server.port}`,

package/dist/services/uploader.js

@@ -24,7 +24,7 @@ export function createUploader({
   userAgent,
   command,
   upload: uploadConfig = {}
-}, options = {}) {
+} = {}, options = {}) {
   let signal = options.signal || new AbortController().signal;
   const api = new ApiService({
     baseUrl: apiUrl,

package/dist/types/client.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Vizzly Client Type Definitions
+ * Lightweight client for test runners
+ * @module @vizzly-testing/cli/client
+ */
+
+/**
+ * Take a screenshot for visual regression testing
+ *
+ * @param name - Unique name for the screenshot
+ * @param imageBuffer - PNG image data as a Buffer, or a file path to an image
+ * @param options - Optional configuration
+ *
+ * @example
+ * // Basic usage with Buffer
+ * import { vizzlyScreenshot } from '@vizzly-testing/cli/client';
+ *
+ * const screenshot = await page.screenshot();
+ * await vizzlyScreenshot('homepage', screenshot);
+ *
+ * @example
+ * // Basic usage with file path
+ * await vizzlyScreenshot('homepage', './screenshots/homepage.png');
+ *
+ * @example
+ * // With properties and threshold
+ * await vizzlyScreenshot('checkout-form', screenshot, {
+ *   properties: { browser: 'chrome', viewport: '1920x1080' },
+ *   threshold: 5
+ * });
+ */
+export function vizzlyScreenshot(
+  name: string,
+  imageBuffer: Buffer | string,
+  options?: {
+    properties?: Record<string, unknown>;
+    threshold?: number;
+    fullPage?: boolean;
+  }
+): Promise<void>;
+
+/**
+ * Wait for all queued screenshots to be processed
+ *
+ * @example
+ * afterAll(async () => {
+ *   await vizzlyFlush();
+ * });
+ */
+export function vizzlyFlush(): Promise<void>;
+
+/**
+ * Check if the Vizzly client is initialized and ready
+ *
+ * @returns True if client is ready, false otherwise
+ */
+export function isVizzlyReady(): boolean;
+
+/**
+ * Configure the client with custom settings
+ *
+ * @param config - Configuration options
+ */
+export function configure(config?: {
+  serverUrl?: string;
+  enabled?: boolean;
+}): void;
+
+/**
+ * Enable or disable screenshot capture
+ *
+ * @param enabled - Whether to enable screenshots
+ */
+export function setEnabled(enabled: boolean): void;
+
+/**
+ * Get information about Vizzly client state
+ *
+ * @returns Client information
+ */
+export function getVizzlyInfo(): {
+  enabled: boolean;
+  serverUrl: string | null;
+  ready: boolean;
+  buildId: string | null;
+  tddMode: boolean;
+  disabled: boolean;
+};

package/dist/types/config.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Vizzly Config Type Definitions
+ * Configuration helpers
+ * @module @vizzly-testing/cli/config
+ */
+
+export { VizzlyConfig } from './index';
+
+/**
+ * Define Vizzly configuration with type hints
+ *
+ * Use this in your vizzly.config.js for better IDE support:
+ *
+ * @example
+ * import { defineConfig } from '@vizzly-testing/cli/config';
+ *
+ * export default defineConfig({
+ *   apiKey: process.env.VIZZLY_TOKEN,
+ *   server: {
+ *     port: 47392
+ *   },
+ *   comparison: {
+ *     threshold: 0.1
+ *   }
+ * });
+ */
+export function defineConfig(
+  config: import('./index').VizzlyConfig
+): import('./index').VizzlyConfig;

package/dist/types/index.d.ts

@@ -1,9 +1,426 @@
-export { createVizzly } from "./sdk/index.js";
-export { createUploader } from "./services/uploader.js";
-export { createTDDService } from "./services/tdd-service.js";
-export { createServices } from "./services/index.js";
-export { loadConfig } from "./utils/config-loader.js";
-export * as output from "./utils/output.js";
-export { defineConfig } from "./utils/config-helpers.js";
-export { UploadError } from "./errors/vizzly-error.js";
-export { vizzlyScreenshot, configure, setEnabled } from "./client/index.js";
+/**
+ * Vizzly CLI Type Definitions
+ * @module @vizzly-testing/cli
+ */
+
+import { EventEmitter } from 'events';
+
+// ============================================================================
+// Configuration Types
+// ============================================================================
+
+export interface ServerConfig {
+  port?: number;
+  timeout?: number;
+}
+
+export interface BuildConfig {
+  name?: string;
+  environment?: string;
+  branch?: string;
+  commit?: string;
+  message?: string;
+}
+
+export interface UploadConfig {
+  screenshotsDir?: string | string[];
+  batchSize?: number;
+  timeout?: number;
+}
+
+export interface ComparisonConfig {
+  threshold?: number;
+}
+
+export interface TddConfig {
+  openReport?: boolean;
+}
+
+export interface VizzlyConfig {
+  apiKey?: string;
+  apiUrl?: string;
+  server?: ServerConfig;
+  build?: BuildConfig;
+  upload?: UploadConfig;
+  comparison?: ComparisonConfig;
+  tdd?: TddConfig;
+  plugins?: string[];
+  parallelId?: string;
+  baselineBuildId?: string;
+  baselineComparisonId?: string;
+  eager?: boolean;
+  wait?: boolean;
+  allowNoToken?: boolean;
+  /** Allow additional plugin-specific configuration */
+  [key: string]: unknown;
+}
+
+// ============================================================================
+// Screenshot Types
+// ============================================================================
+
+export interface ScreenshotOptions {
+  properties?: Record<string, unknown>;
+  threshold?: number;
+  fullPage?: boolean;
+  buildId?: string;
+}
+
+export interface ScreenshotResult {
+  success: boolean;
+  status?: 'passed' | 'failed' | 'new';
+  name?: string;
+  diffPercentage?: number;
+}
+
+// ============================================================================
+// Comparison Types
+// ============================================================================
+
+export interface ComparisonResult {
+  id: string;
+  name: string;
+  status: 'passed' | 'failed' | 'new' | 'error' | 'baseline-updated';
+  baseline: string;
+  current: string;
+  diff: string | null;
+  properties: Record<string, unknown>;
+  signature: string;
+  threshold?: number;
+  diffPercentage?: number;
+  diffCount?: number;
+  error?: string;
+}
+
+export interface TddResults {
+  total: number;
+  passed: number;
+  failed: number;
+  new: number;
+  errors: number;
+  comparisons: ComparisonResult[];
+  baseline: BaselineData | null;
+}
+
+export interface BaselineData {
+  buildId: string;
+  buildName: string;
+  environment?: string;
+  branch?: string;
+  threshold: number;
+  createdAt?: string;
+  screenshots: BaselineScreenshot[];
+}
+
+export interface BaselineScreenshot {
+  name: string;
+  originalName?: string;
+  sha256?: string;
+  id?: string;
+  properties: Record<string, unknown>;
+  path: string;
+  signature: string;
+}
+
+// ============================================================================
+// Upload Types
+// ============================================================================
+
+export interface UploadOptions {
+  screenshotsDir?: string;
+  buildName?: string;
+  branch?: string;
+  commit?: string;
+  message?: string;
+  environment?: string;
+  threshold?: number;
+  pullRequestNumber?: string;
+  parallelId?: string;
+  onProgress?: (progress: UploadProgress) => void;
+}
+
+export interface UploadProgress {
+  phase:
+    | 'scanning'
+    | 'processing'
+    | 'deduplication'
+    | 'uploading'
+    | 'completed';
+  message: string;
+  total?: number;
+  current?: number;
+  toUpload?: number;
+  existing?: number;
+  buildId?: string;
+  url?: string;
+}
+
+export interface UploadResult {
+  success: boolean;
+  buildId: string;
+  url: string | null;
+  stats: {
+    total: number;
+    uploaded: number;
+    skipped: number;
+  };
+}
+
+export interface BuildResult {
+  status: 'completed' | 'failed' | 'pending';
+  build: unknown;
+  comparisons?: number;
+  passedComparisons?: number;
+  failedComparisons?: number;
+  url?: string;
+}
+
+// ============================================================================
+// Error Types
+// ============================================================================
+
+export class VizzlyError extends Error {
+  code: string;
+  context: Record<string, unknown>;
+  timestamp: string;
+  constructor(
+    message: string,
+    code?: string,
+    context?: Record<string, unknown>
+  );
+  getUserMessage(): string;
+  toJSON(): {
+    name: string;
+    code: string;
+    message: string;
+    context: Record<string, unknown>;
+    timestamp: string;
+    stack?: string;
+  };
+}
+
+export class ConfigError extends VizzlyError {
+  constructor(message: string, context?: Record<string, unknown>);
+}
+
+export class AuthError extends VizzlyError {
+  constructor(message: string, context?: Record<string, unknown>);
+}
+
+export class NetworkError extends VizzlyError {
+  constructor(message: string, context?: Record<string, unknown>);
+}
+
+export class UploadError extends VizzlyError {
+  constructor(message: string, context?: Record<string, unknown>);
+}
+
+export class ScreenshotError extends VizzlyError {
+  constructor(message: string, context?: Record<string, unknown>);
+}
+
+export class BuildError extends VizzlyError {
+  constructor(message: string, context?: Record<string, unknown>);
+}
+
+export class TimeoutError extends VizzlyError {
+  duration: number;
+  constructor(
+    message: string,
+    duration?: number,
+    context?: Record<string, unknown>
+  );
+}
+
+export class ValidationError extends VizzlyError {
+  errors: string[];
+  constructor(
+    message: string,
+    errors?: string[],
+    context?: Record<string, unknown>
+  );
+}
+
+// ============================================================================
+// SDK Types
+// ============================================================================
+
+export interface VizzlySDKInstance extends EventEmitter {
+  config: VizzlyConfig;
+
+  /** Start the Vizzly server */
+  start(): Promise<{ port: number; url: string }>;
+
+  /** Stop the Vizzly server */
+  stop(): Promise<void>;
+
+  /** Get current configuration */
+  getConfig(): VizzlyConfig;
+
+  /** Capture a screenshot */
+  screenshot(
+    name: string,
+    imageBuffer: Buffer | string,
+    options?: ScreenshotOptions
+  ): Promise<void>;
+
+  /** Upload all captured screenshots */
+  upload(options?: UploadOptions): Promise<UploadResult>;
+
+  /** Run local comparison in TDD mode */
+  compare(
+    name: string,
+    imageBuffer: Buffer | string
+  ): Promise<ComparisonResult>;
+}
+
+export class VizzlySDK extends EventEmitter implements VizzlySDKInstance {
+  config: VizzlyConfig;
+
+  constructor(config: VizzlyConfig, services: unknown);
+
+  start(): Promise<{ port: number; url: string }>;
+  stop(): Promise<void>;
+  getConfig(): VizzlyConfig;
+  screenshot(
+    name: string,
+    imageBuffer: Buffer | string,
+    options?: ScreenshotOptions
+  ): Promise<void>;
+  upload(options?: UploadOptions): Promise<UploadResult>;
+  compare(
+    name: string,
+    imageBuffer: Buffer | string
+  ): Promise<ComparisonResult>;
+}
+
+// ============================================================================
+// Service Types
+// ============================================================================
+
+export interface Uploader {
+  upload(options: UploadOptions): Promise<UploadResult>;
+  waitForBuild(buildId: string, timeout?: number): Promise<BuildResult>;
+}
+
+export interface TddService {
+  downloadBaselines(
+    environment?: string,
+    branch?: string,
+    buildId?: string,
+    comparisonId?: string
+  ): Promise<BaselineData | null>;
+
+  loadBaseline(): Promise<BaselineData | null>;
+
+  compareScreenshot(
+    name: string,
+    imageBuffer: Buffer,
+    properties?: Record<string, unknown>
+  ): Promise<ComparisonResult>;
+
+  getResults(): TddResults;
+  printResults(): Promise<TddResults>;
+  updateBaselines(): number;
+  acceptBaseline(idOrComparison: string | ComparisonResult): Promise<{
+    name: string;
+    status: string;
+    message: string;
+  }>;
+}
+
+export interface Services {
+  apiService: unknown;
+  authService: unknown;
+  configService: unknown;
+  projectService: unknown;
+  uploader: Uploader;
+  buildManager: unknown;
+  serverManager: unknown;
+  tddService: TddService;
+  testRunner: unknown;
+}
+
+// ============================================================================
+// Output Utilities
+// ============================================================================
+
+export interface OutputUtils {
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
+  success(message: string): void;
+  debug(category: string, ...args: unknown[]): void;
+  configure(options: { verbose?: boolean }): void;
+}
+
+// ============================================================================
+// Main Exports
+// ============================================================================
+
+/** Create a new Vizzly SDK instance */
+export function createVizzly(
+  config?: VizzlyConfig,
+  options?: { verbose?: boolean }
+): Promise<VizzlySDKInstance>;
+
+/** Take a screenshot for visual regression testing */
+export function vizzlyScreenshot(
+  name: string,
+  imageBuffer: Buffer | string,
+  options?: {
+    properties?: Record<string, unknown>;
+    threshold?: number;
+    fullPage?: boolean;
+  }
+): Promise<void>;
+
+/** Configure the Vizzly client */
+export function configure(config?: {
+  serverUrl?: string;
+  enabled?: boolean;
+}): void;
+
+/** Enable or disable screenshot capture */
+export function setEnabled(enabled: boolean): void;
+
+/** Create an uploader instance */
+export function createUploader(
+  config?: {
+    apiKey?: string;
+    apiUrl?: string;
+    userAgent?: string;
+    command?: string;
+    upload?: UploadConfig;
+  },
+  options?: {
+    signal?: AbortSignal;
+    batchSize?: number;
+    timeout?: number;
+  }
+): Uploader;
+
+/** Create a TDD service instance */
+export function createTDDService(
+  config: VizzlyConfig,
+  options?: {
+    workingDir?: string;
+    setBaseline?: boolean;
+    authService?: unknown;
+  }
+): TddService;
+
+/** Create all services with dependencies */
+export function createServices(
+  config: VizzlyConfig,
+  command?: string
+): Services;
+
+/** Load configuration from file and environment */
+export function loadConfig(options?: { cwd?: string }): Promise<VizzlyConfig>;
+
+/** Define Vizzly configuration with type hints */
+export function defineConfig(config: VizzlyConfig): VizzlyConfig;
+
+/** Output utilities namespace */
+export const output: OutputUtils;