@vizzly-testing/cli 0.8.0 → 0.9.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 tdd "npm test"
+vizzly tdd run "npm test"
 ```
 
 ### In your test code
@@ -125,29 +125,42 @@ vizzly run "npm test" --parallel-id "ci-run-123"  # For parallel CI builds
 For local visual testing with immediate feedback, use the dedicated `tdd` command:
 
 ```bash
-# First run - creates local baselines
-vizzly tdd "npm test"
+# Start interactive TDD dashboard
+vizzly tdd start
 
-# Make changes and test - fails if visual differences detected
-vizzly tdd "npm test"
+# Run your tests in watch mode
+npm test -- --watch
 
-# Accept changes as new baseline
-vizzly tdd "npm test" --set-baseline
+# View the dashboard at http://localhost:47392
 ```
 
-**Interactive HTML Report:** Each TDD run generates a detailed HTML report with visual comparison tools:
-- **Overlay mode** - Toggle between baseline and current screenshots
-- **Side-by-side mode** - Compare baseline and current images horizontally
-- **Onion skin mode** - Drag to reveal differences interactively
-- **Toggle mode** - Click to switch between baseline and current
+**Interactive Dashboard:** The TDD dashboard provides real-time visual feedback:
+- **Live Updates** - See comparisons as tests run
+- **Visual Diff Modes** - Overlay, side-by-side, onion skin, and toggle views
+- **Baseline Management** - Accept/reject changes directly from the UI
+- **Test Statistics** - Real-time pass/fail metrics
+- **Dark Theme** - Easy on the eyes during long sessions
+
+**TDD Subcommands:**
+
+```bash
+# Start the TDD dashboard server
+vizzly tdd start [options]
+
+# Run tests in single-shot mode
+vizzly tdd run "npm test" [options]
+
+# Stop a running TDD server
+vizzly tdd stop
+```
 
 **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)
+- `--daemon` - Run server in background (start command only)
 
 ### Setup and Status Commands
 ```bash

package/dist/cli.js

@@ -5,6 +5,7 @@ import { init } from './commands/init.js';
 import { uploadCommand, validateUploadOptions } from './commands/upload.js';
 import { runCommand, validateRunOptions } from './commands/run.js';
 import { tddCommand, validateTddOptions } from './commands/tdd.js';
+import { tddStartCommand, tddStopCommand, tddStatusCommand } from './commands/tdd-daemon.js';
 import { statusCommand, validateStatusOptions } from './commands/status.js';
 import { finalizeCommand, validateFinalizeOptions } from './commands/finalize.js';
 import { doctorCommand, validateDoctorOptions } from './commands/doctor.js';
@@ -29,7 +30,30 @@ program.command('upload').description('Upload screenshots to Vizzly').argument('
   }
   await uploadCommand(path, options, globalOptions);
 });
-program.command('tdd').description('Run tests in TDD mode with local visual comparisons').argument('<command>', 'Test command to run').option('--port <port>', 'Port for screenshot server', '47392').option('--branch <branch>', 'Git branch override').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', parseFloat).option('--token <token>', 'API token override').option('--timeout <ms>', 'Server timeout in milliseconds', '30000').option('--baseline-build <id>', 'Use specific build as baseline').option('--baseline-comparison <id>', 'Use specific comparison as baseline').option('--set-baseline', 'Accept current screenshots as new baseline (overwrites existing)').option('--allow-no-token', 'Allow running without API token (no baselines)').action(async (command, options) => {
+
+// TDD command with subcommands
+const tddCmd = program.command('tdd').description('Run tests in TDD mode with local visual comparisons');
+
+// TDD Start - Background server
+tddCmd.command('start').description('Start background TDD server').option('--port <port>', 'Port for screenshot server', '47392').option('--open', 'Open dashboard in browser').option('--baseline-build <id>', 'Use specific build as baseline').option('--baseline-comparison <id>', 'Use specific comparison as baseline').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', parseFloat).option('--timeout <ms>', 'Server timeout in milliseconds', '30000').option('--token <token>', 'API token override').action(async options => {
+  const globalOptions = program.opts();
+  await tddStartCommand(options, globalOptions);
+});
+
+// TDD Stop - Kill background server
+tddCmd.command('stop').description('Stop background TDD server').action(async options => {
+  const globalOptions = program.opts();
+  await tddStopCommand(options, globalOptions);
+});
+
+// TDD Status - Check server status
+tddCmd.command('status').description('Check TDD server status').action(async options => {
+  const globalOptions = program.opts();
+  await tddStatusCommand(options, globalOptions);
+});
+
+// TDD Run - One-off test run (primary workflow)
+tddCmd.command('run <command>').description('Run tests once in TDD mode with local visual comparisons').option('--port <port>', 'Port for screenshot server', '47392').option('--branch <branch>', 'Git branch override').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', parseFloat).option('--token <token>', 'API token override').option('--timeout <ms>', 'Server timeout in milliseconds', '30000').option('--baseline-build <id>', 'Use specific build as baseline').option('--baseline-comparison <id>', 'Use specific comparison as baseline').option('--set-baseline', 'Accept current screenshots as new baseline (overwrites existing)').action(async (command, options) => {
   const globalOptions = program.opts();
 
   // Validate options

package/dist/client/index.js

@@ -3,11 +3,14 @@
  * @description Thin client for test runners - minimal API for taking screenshots
  */
 
-import { isVizzlyEnabled, getServerUrl, getBuildId, isTddMode, setVizzlyEnabled } from '../utils/environment-config.js';
+import { getServerUrl, getBuildId, isTddMode, setVizzlyEnabled } from '../utils/environment-config.js';
+import { existsSync, readFileSync } from 'fs';
+import { join, parse, dirname } from 'path';
 
 // Internal client state
 let currentClient = null;
 let isDisabled = false;
+let hasLoggedWarning = false;
 
 /**
  * Check if Vizzly is currently disabled
@@ -15,7 +18,8 @@ let isDisabled = false;
  * @returns {boolean} True if disabled via environment variable or auto-disabled due to failure
  */
 function isVizzlyDisabled() {
-  return !isVizzlyEnabled() || isDisabled;
+  // Don't check isVizzlyEnabled() here - let auto-discovery happen first
+  return isDisabled;
 }
 
 /**
@@ -31,6 +35,37 @@ function disableVizzly(reason = 'disabled') {
   }
 }
 
+/**
+ * Auto-discover local TDD server by checking for server.json
+ * @private
+ * @returns {string|null} Server URL if found
+ */
+function autoDiscoverTddServer() {
+  try {
+    // Look for .vizzly/server.json in current directory and parent directories
+    let currentDir = process.cwd();
+    const root = parse(currentDir).root;
+    while (currentDir !== root) {
+      const serverJsonPath = join(currentDir, '.vizzly', 'server.json');
+      if (existsSync(serverJsonPath)) {
+        try {
+          const serverInfo = JSON.parse(readFileSync(serverJsonPath, 'utf8'));
+          if (serverInfo.port) {
+            const url = `http://localhost:${serverInfo.port}`;
+            return url;
+          }
+        } catch {
+          // Invalid JSON, continue searching
+        }
+      }
+      currentDir = dirname(currentDir);
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Get the current client instance
  * @private
@@ -40,9 +75,19 @@ function getClient() {
     return null;
   }
   if (!currentClient) {
-    // Only try to initialize if VIZZLY_ENABLED is explicitly true
-    const serverUrl = getServerUrl();
-    if (serverUrl && isVizzlyEnabled()) {
+    let serverUrl = getServerUrl();
+
+    // Auto-detect local TDD server and enable Vizzly if TDD server is found
+    if (!serverUrl) {
+      serverUrl = autoDiscoverTddServer();
+      if (serverUrl) {
+        // Automatically enable Vizzly when TDD server is detected
+        setVizzlyEnabled(true);
+      }
+    }
+
+    // If we have a server URL, create the client (regardless of initial enabled state)
+    if (serverUrl) {
       currentClient = createSimpleClient(serverUrl);
     }
   }
@@ -80,22 +125,39 @@ function createSimpleClient(serverUrl) {
             };
           });
 
-          // In TDD mode, if we get 422 (visual difference), throw with clean message
+          // In TDD mode, if we get 422 (visual difference), log but DON'T throw
+          // This allows all screenshots in the test to be captured and compared
           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}`);
+            const diffPercent = comp.diffPercentage ? comp.diffPercentage.toFixed(2) : '0.00';
+
+            // Extract port from serverUrl (e.g., "http://localhost:47392" -> "47392")
+            const urlMatch = serverUrl.match(/:(\d+)/);
+            const port = urlMatch ? urlMatch[1] : '47392';
+            const dashboardUrl = `http://localhost:${port}/dashboard`;
+
+            // Just log warning - don't throw by default in TDD mode
+            // This allows all screenshots to be captured
+            console.warn(`⚠️  Visual diff: ${comp.name} (${diffPercent}%) → ${dashboardUrl}`);
+
+            // Return success so test continues and captures remaining screenshots
+            return {
+              success: true,
+              status: 'failed',
+              name: comp.name,
+              diffPercentage: comp.diffPercentage
+            };
           }
           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')) {
+        if (error.message.toLowerCase().includes('visual diff')) {
           // 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}`);
+        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');
@@ -157,7 +219,11 @@ export async function vizzlyScreenshot(name, imageBuffer, options = {}) {
   }
   const client = getClient();
   if (!client) {
-    console.warn('Vizzly client not initialized. Screenshots will be skipped.');
+    if (!hasLoggedWarning) {
+      console.warn('Vizzly client not initialized. Screenshots will be skipped.');
+      hasLoggedWarning = true;
+      disableVizzly();
+    }
     return;
   }
   return client.screenshot(name, imageBuffer, options);

package/dist/commands/init.js

@@ -40,30 +40,36 @@ export class InitCommand {
     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
+  // apiKey: 'your-token-here',
+
+  // Server configuration (for run command)
   server: {
     port: 47392,
+    timeout: 30000,
     screenshotPath: '/screenshot'
   },
-  
-  // Comparison configuration
-  comparison: {
-    threshold: 0.1,
-    ignoreAntialiasing: true
+
+  // Build configuration
+  build: {
+    name: 'Build {timestamp}',
+    environment: 'test'
   },
-  
-  // Upload configuration
+
+  // Upload configuration (for upload command)
   upload: {
-    concurrency: 5,
+    screenshotsDir: './screenshots',
+    batchSize: 10,
     timeout: 30000
+  },
+
+  // Comparison configuration
+  comparison: {
+    threshold: 0.1
+  },
+
+  // TDD configuration
+  tdd: {
+    openReport: false // Whether to auto-open HTML report in browser
   }
 };
 `;

package/dist/commands/tdd-daemon.js

@@ -0,0 +1,312 @@
+import { writeFileSync, readFileSync, existsSync, unlinkSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { spawn } from 'child_process';
+import { ConsoleUI } from '../utils/console-ui.js';
+import { tddCommand } from './tdd.js';
+
+/**
+ * Start TDD server in daemon mode
+ * @param {Object} options - Command options
+ * @param {Object} globalOptions - Global CLI options
+ */
+export async function tddStartCommand(options = {}, globalOptions = {}) {
+  const ui = new ConsoleUI({
+    json: globalOptions.json,
+    verbose: globalOptions.verbose,
+    color: !globalOptions.noColor
+  });
+
+  // Check if server already running
+  if (await isServerRunning(options.port || 47392)) {
+    const port = options.port || 47392;
+    ui.info(`TDD server already running at http://localhost:${port}`);
+    ui.info(`Dashboard: http://localhost:${port}/dashboard`);
+    if (options.open) {
+      openDashboard(port);
+    }
+    return;
+  }
+  try {
+    // Ensure .vizzly directory exists
+    const vizzlyDir = join(process.cwd(), '.vizzly');
+    if (!existsSync(vizzlyDir)) {
+      mkdirSync(vizzlyDir, {
+        recursive: true
+      });
+    }
+    const port = options.port || 47392;
+
+    // Use existing tddCommand but with daemon mode - this will start and keep running
+    const {
+      cleanup
+    } = await tddCommand(null,
+    // No test command - server only
+    {
+      ...options,
+      daemon: true // Flag to indicate daemon mode
+    }, globalOptions);
+
+    // The server is now running in this process
+    // Store our PID for the stop command
+    const pidFile = join(vizzlyDir, 'server.pid');
+    writeFileSync(pidFile, process.pid.toString());
+    const serverInfo = {
+      pid: process.pid,
+      port: port,
+      startTime: Date.now()
+    };
+    writeFileSync(join(vizzlyDir, 'server.json'), JSON.stringify(serverInfo, null, 2));
+    ui.success(`TDD server started at http://localhost:${port}`);
+    ui.info('');
+    ui.info('Dashboard URLs:');
+    ui.info(`  Comparisons: http://localhost:${port}/`);
+    ui.info(`  Stats:       http://localhost:${port}/stats`);
+    ui.info('');
+    ui.info('Next steps:');
+    ui.info('  1. Run your tests (any test runner)');
+    ui.info('  2. Open the dashboard in your browser');
+    ui.info('  3. Manage baselines in the Stats view');
+    ui.info('');
+    ui.info('Stop server: npx vizzly tdd stop');
+    if (options.open) {
+      openDashboard(port);
+    }
+
+    // Set up graceful shutdown
+    const handleShutdown = async signal => {
+      ui.info(`\nReceived ${signal}, shutting down gracefully...`);
+      try {
+        // Clean up PID files
+        if (existsSync(pidFile)) unlinkSync(pidFile);
+        const serverFile = join(vizzlyDir, 'server.json');
+        if (existsSync(serverFile)) unlinkSync(serverFile);
+
+        // Use the cleanup function from tddCommand
+        await cleanup();
+        ui.success('TDD server stopped');
+      } catch (error) {
+        ui.error('Error during shutdown:', error);
+      }
+      process.exit(0);
+    };
+
+    // Register signal handlers
+    process.on('SIGINT', () => handleShutdown('SIGINT'));
+    process.on('SIGTERM', () => handleShutdown('SIGTERM'));
+
+    // Keep process alive
+    process.stdin.resume();
+  } catch (error) {
+    ui.error('Failed to start TDD daemon', error);
+    process.exit(1);
+  }
+}
+
+/**
+ * Stop TDD daemon server
+ * @param {Object} options - Command options
+ * @param {Object} globalOptions - Global CLI options
+ */
+export async function tddStopCommand(options = {}, globalOptions = {}) {
+  const ui = new ConsoleUI({
+    json: globalOptions.json,
+    verbose: globalOptions.verbose,
+    color: !globalOptions.noColor
+  });
+  const vizzlyDir = join(process.cwd(), '.vizzly');
+  const pidFile = join(vizzlyDir, 'server.pid');
+  const serverFile = join(vizzlyDir, 'server.json');
+
+  // First try to find process by PID file
+  let pid = null;
+  if (existsSync(pidFile)) {
+    try {
+      pid = parseInt(readFileSync(pidFile, 'utf8').trim(), 10);
+    } catch {
+      // Invalid PID file
+    }
+  }
+
+  // If no PID file or invalid, try to find by port using lsof
+  const port = options.port || 47392;
+  if (!pid) {
+    try {
+      const lsofProcess = spawn('lsof', ['-ti', `:${port}`], {
+        stdio: 'pipe'
+      });
+      let lsofOutput = '';
+      lsofProcess.stdout.on('data', data => {
+        lsofOutput += data.toString();
+      });
+      await new Promise(resolve => {
+        lsofProcess.on('close', code => {
+          if (code === 0 && lsofOutput.trim()) {
+            const foundPid = parseInt(lsofOutput.trim().split('\n')[0], 10);
+            if (foundPid && !isNaN(foundPid)) {
+              pid = foundPid;
+            }
+          }
+          resolve();
+        });
+        lsofProcess.on('error', () => {
+          // lsof not available, that's ok
+          resolve();
+        });
+      });
+    } catch {
+      // lsof failed, that's ok too
+    }
+  }
+  if (!pid) {
+    ui.warning('No TDD server running');
+
+    // Clean up any stale files
+    if (existsSync(pidFile)) unlinkSync(pidFile);
+    if (existsSync(serverFile)) unlinkSync(serverFile);
+    return;
+  }
+  try {
+    // Try to kill the process gracefully
+    process.kill(pid, 'SIGTERM');
+    ui.info(`Stopping TDD server (PID: ${pid})...`);
+
+    // Give it a moment to shut down gracefully
+    await new Promise(resolve => setTimeout(resolve, 2000));
+
+    // Check if it's still running
+    try {
+      process.kill(pid, 0); // Just check if process exists
+      // If we get here, process is still running, force kill it
+      process.kill(pid, 'SIGKILL');
+      ui.info('Force killed TDD server');
+    } catch {
+      // Process is gone, which is what we want
+    }
+
+    // Clean up files
+    if (existsSync(pidFile)) unlinkSync(pidFile);
+    if (existsSync(serverFile)) unlinkSync(serverFile);
+    ui.success('TDD server stopped');
+  } catch (error) {
+    if (error.code === 'ESRCH') {
+      // Process not found - clean up stale files
+      ui.warning('TDD server was not running (cleaning up stale files)');
+      if (existsSync(pidFile)) unlinkSync(pidFile);
+      if (existsSync(serverFile)) unlinkSync(serverFile);
+    } else {
+      ui.error('Error stopping TDD server', error);
+    }
+  }
+}
+
+/**
+ * Check TDD daemon server status
+ * @param {Object} options - Command options
+ * @param {Object} globalOptions - Global CLI options
+ */
+export async function tddStatusCommand(options, globalOptions = {}) {
+  const ui = new ConsoleUI({
+    json: globalOptions.json,
+    verbose: globalOptions.verbose,
+    color: !globalOptions.noColor
+  });
+  const vizzlyDir = join(process.cwd(), '.vizzly');
+  const pidFile = join(vizzlyDir, 'server.pid');
+  const serverFile = join(vizzlyDir, 'server.json');
+  if (!existsSync(pidFile)) {
+    ui.info('TDD server not running');
+    return;
+  }
+  try {
+    const pid = parseInt(readFileSync(pidFile, 'utf8').trim(), 10);
+
+    // Check if process is actually running
+    process.kill(pid, 0); // Signal 0 just checks if process exists
+
+    let serverInfo = {
+      port: 47392
+    };
+    if (existsSync(serverFile)) {
+      serverInfo = JSON.parse(readFileSync(serverFile, 'utf8'));
+    }
+
+    // Try to check health endpoint
+    const health = await checkServerHealth(serverInfo.port);
+    if (health.running) {
+      ui.success(`TDD server running (PID: ${pid})`);
+      ui.info(`Server: http://localhost:${serverInfo.port}`);
+      ui.info(`Dashboard: http://localhost:${serverInfo.port}/dashboard`);
+      if (serverInfo.startTime) {
+        const uptime = Math.floor((Date.now() - serverInfo.startTime) / 1000);
+        ui.info(`Uptime: ${uptime} seconds`);
+      }
+    } else {
+      ui.warning('TDD server process exists but not responding to health checks');
+    }
+  } catch (error) {
+    if (error.code === 'ESRCH') {
+      ui.warning('TDD server process not found (cleaning up stale files)');
+      unlinkSync(pidFile);
+      if (existsSync(serverFile)) {
+        unlinkSync(serverFile);
+      }
+    } else {
+      ui.error('Error checking TDD server status', error);
+    }
+  }
+}
+
+/**
+ * Check if server is running on given port
+ * @private
+ */
+async function isServerRunning(port = 47392) {
+  try {
+    const health = await checkServerHealth(port);
+    return health.running;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check server health endpoint
+ * @private
+ */
+async function checkServerHealth(port = 47392) {
+  try {
+    const response = await fetch(`http://localhost:${port}/health`);
+    const data = await response.json();
+    return {
+      running: response.ok,
+      port: data.port,
+      uptime: data.uptime
+    };
+  } catch {
+    return {
+      running: false
+    };
+  }
+}
+
+/**
+ * Open dashboard in default browser
+ * @private
+ */
+function openDashboard(port = 47392) {
+  const url = `http://localhost:${port}/dashboard`;
+
+  // Cross-platform open command
+  let openCmd;
+  if (process.platform === 'darwin') {
+    openCmd = 'open';
+  } else if (process.platform === 'win32') {
+    openCmd = 'start';
+  } else {
+    openCmd = 'xdg-open';
+  }
+  spawn(openCmd, [url], {
+    detached: true,
+    stdio: 'ignore'
+  }).unref();
+}