@curl-runner/cli 1.9.0 → 1.11.0

package/src/types/config.ts

@@ -147,6 +147,11 @@ export interface RequestConfig {
     body?: JsonValue;
     responseTime?: string; // Response time validation like "< 1000", "> 500, < 2000"
   };
+  /**
+   * Snapshot configuration for this request.
+   * Use `true` to enable with defaults, or provide detailed config.
+   */
+  snapshot?: SnapshotConfig | boolean;
   sourceOutputConfig?: {
     verbose?: boolean;
     showHeaders?: boolean;
@@ -210,6 +215,16 @@ export interface GlobalConfig {
    * Applied to all requests unless overridden at the request level.
    */
   ssl?: SSLConfig;
+  /**
+   * Watch mode configuration.
+   * Automatically re-runs requests when YAML files change.
+   */
+  watch?: WatchConfig;
+  /**
+   * Snapshot testing configuration.
+   * Saves response snapshots and compares future runs against them.
+   */
+  snapshot?: GlobalSnapshotConfig;
   variables?: Record<string, string>;
   output?: {
     verbose?: boolean;
@@ -247,6 +262,8 @@ export interface ExecutionResult {
     firstByte?: number;
     download?: number;
   };
+  /** Snapshot comparison result (if snapshot testing enabled). */
+  snapshotResult?: SnapshotCompareResult;
 }
 
 export interface ExecutionSummary {
@@ -262,3 +279,84 @@ export interface ExecutionSummary {
  * Values are stored as strings and can be referenced using ${store.variableName} syntax.
  */
 export type ResponseStoreContext = Record<string, string>;
+
+/**
+ * Configuration for watch mode.
+ * Watch mode automatically re-runs requests when YAML files change.
+ */
+export interface WatchConfig {
+  /** Enable watch mode. Default: false */
+  enabled?: boolean;
+  /** Debounce delay in milliseconds. Default: 300 */
+  debounce?: number;
+  /** Clear screen between runs. Default: true */
+  clear?: boolean;
+}
+
+/**
+ * Configuration for snapshot testing.
+ * Snapshots save response data and compare future runs against them.
+ */
+export interface SnapshotConfig {
+  /** Enable snapshot testing for this request. */
+  enabled?: boolean;
+  /** Custom snapshot name (defaults to request name). */
+  name?: string;
+  /** What to include in snapshot. Default: ['body'] */
+  include?: ('body' | 'status' | 'headers')[];
+  /** Paths to exclude from comparison (e.g., 'body.timestamp'). */
+  exclude?: string[];
+  /** Match rules for dynamic values (path -> '*' or 'regex:pattern'). */
+  match?: Record<string, string>;
+}
+
+/**
+ * Global snapshot configuration.
+ */
+export interface GlobalSnapshotConfig extends SnapshotConfig {
+  /** Directory for snapshot files. Default: '__snapshots__' */
+  dir?: string;
+  /** Update mode: 'none' | 'all' | 'failing'. Default: 'none' */
+  updateMode?: 'none' | 'all' | 'failing';
+  /** CI mode: fail if snapshot is missing. Default: false */
+  ci?: boolean;
+}
+
+/**
+ * Stored snapshot data for a single request.
+ */
+export interface Snapshot {
+  status?: number;
+  headers?: Record<string, string>;
+  body?: JsonValue;
+  hash: string;
+  updatedAt: string;
+}
+
+/**
+ * Snapshot file format.
+ */
+export interface SnapshotFile {
+  version: number;
+  snapshots: Record<string, Snapshot>;
+}
+
+/**
+ * Result of comparing a response against a snapshot.
+ */
+export interface SnapshotDiff {
+  path: string;
+  expected: unknown;
+  received: unknown;
+  type: 'added' | 'removed' | 'changed' | 'type_mismatch';
+}
+
+/**
+ * Result of snapshot comparison.
+ */
+export interface SnapshotCompareResult {
+  match: boolean;
+  isNew: boolean;
+  updated: boolean;
+  differences: SnapshotDiff[];
+}

package/src/utils/logger.ts

@@ -1,3 +1,4 @@
+import { SnapshotFormatter } from '../snapshot/snapshot-formatter';
 import type {
   ExecutionResult,
   ExecutionSummary,
@@ -409,6 +410,12 @@ export class Logger {
         this.logValidationErrors(result.error);
       }
 
+      // Show snapshot result
+      if (result.snapshotResult) {
+        console.log();
+        this.logSnapshotResult(result.request.name || 'Request', result.snapshotResult);
+      }
+
       console.log();
       return;
     }
@@ -532,9 +539,27 @@ export class Logger {
       this.logValidationErrors(result.error);
     }
 
+    // Show snapshot result
+    if (result.snapshotResult) {
+      console.log();
+      this.logSnapshotResult(result.request.name || 'Request', result.snapshotResult);
+    }
+
     console.log();
   }
 
+  /**
+   * Logs snapshot comparison result.
+   */
+  private logSnapshotResult(requestName: string, result: ExecutionResult['snapshotResult']): void {
+    if (!result) {
+      return;
+    }
+
+    const formatter = new SnapshotFormatter();
+    console.log(formatter.formatResult(requestName, result));
+  }
+
   logSummary(summary: ExecutionSummary, isGlobal: boolean = false): void {
     // For raw format, don't show summary
     if (this.config.format === 'raw') {
@@ -645,4 +670,28 @@ export class Logger {
         this.color(` (${requestCount} request${requestCount === 1 ? '' : 's'})`, 'dim'),
     );
   }
+
+  logWatch(files: string[]): void {
+    console.log();
+    console.log(
+      `${this.color('Watching for changes...', 'cyan')} ${this.color('(press Ctrl+C to stop)', 'dim')}`,
+    );
+    const fileList = files.length <= 3 ? files.join(', ') : `${files.length} files`;
+    console.log(this.color(`   Files: ${fileList}`, 'dim'));
+    console.log();
+  }
+
+  logWatchReady(): void {
+    console.log();
+    console.log(this.color('Watching for changes...', 'cyan'));
+  }
+
+  logFileChanged(filename: string): void {
+    const timestamp = new Date().toLocaleTimeString('en-US', { hour12: false });
+    console.log(this.color('-'.repeat(50), 'dim'));
+    console.log(
+      `${this.color(`[${timestamp}]`, 'dim')} File changed: ${this.color(filename, 'yellow')}`,
+    );
+    console.log();
+  }
 }

package/src/watcher/file-watcher.test.ts

@@ -0,0 +1,186 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';
+import { FileWatcher, type WatcherOptions } from './file-watcher';
+
+// Mock logger
+const createMockLogger = () => ({
+  logWatch: mock(() => {}),
+  logWatchReady: mock(() => {}),
+  logFileChanged: mock(() => {}),
+  logError: mock(() => {}),
+  logWarning: mock(() => {}),
+});
+
+// Helper to access private method for testing
+const triggerFileChange = (watcher: FileWatcher, filename: string) => {
+  // biome-ignore lint/complexity/useLiteralKeys: accessing private method for testing
+  watcher['handleFileChange'](filename);
+};
+
+describe('FileWatcher', () => {
+  let watcher: FileWatcher;
+  let mockLogger: ReturnType<typeof createMockLogger>;
+  let onRunMock: ReturnType<typeof mock>;
+
+  beforeEach(() => {
+    mockLogger = createMockLogger();
+    onRunMock = mock(() => Promise.resolve());
+  });
+
+  afterEach(() => {
+    if (watcher) {
+      watcher.stop();
+    }
+  });
+
+  test('should debounce rapid file changes', async () => {
+    const options: WatcherOptions = {
+      files: [],
+      config: { debounce: 50 },
+      onRun: onRunMock,
+      logger: mockLogger as unknown as WatcherOptions['logger'],
+    };
+
+    watcher = new FileWatcher(options);
+
+    // Simulate rapid file changes
+    triggerFileChange(watcher, 'test.yaml');
+    triggerFileChange(watcher, 'test.yaml');
+    triggerFileChange(watcher, 'test.yaml');
+
+    // Wait for debounce to settle
+    await Bun.sleep(100);
+
+    // Should only have been called once due to debouncing
+    // Initial run doesn't happen because we didn't call start()
+    expect(onRunMock).toHaveBeenCalledTimes(1);
+  });
+
+  test('should queue runs during execution', async () => {
+    let runCount = 0;
+    const slowOnRun = mock(async () => {
+      runCount++;
+      await Bun.sleep(100);
+    });
+
+    const options: WatcherOptions = {
+      files: [],
+      config: { debounce: 10, clear: false },
+      onRun: slowOnRun,
+      logger: mockLogger as unknown as WatcherOptions['logger'],
+    };
+
+    watcher = new FileWatcher(options);
+
+    // Start first run
+    triggerFileChange(watcher, 'test.yaml');
+    await Bun.sleep(20); // Let debounce fire
+
+    // Change during run (should be queued)
+    triggerFileChange(watcher, 'test.yaml');
+
+    // Wait for both runs to complete
+    await Bun.sleep(300);
+
+    expect(runCount).toBe(2);
+  });
+
+  test('should clear debounce timer on stop', () => {
+    const options: WatcherOptions = {
+      files: [],
+      config: { debounce: 1000 },
+      onRun: onRunMock,
+      logger: mockLogger as unknown as WatcherOptions['logger'],
+    };
+
+    watcher = new FileWatcher(options);
+
+    // Trigger a change to start debounce timer
+    triggerFileChange(watcher, 'test.yaml');
+
+    // Stop should clear the timer
+    watcher.stop();
+
+    // biome-ignore lint/complexity/useLiteralKeys: accessing private field for testing
+    expect(watcher['debounceTimer']).toBeNull();
+    // biome-ignore lint/complexity/useLiteralKeys: accessing private field for testing
+    expect(watcher['watchers']).toHaveLength(0);
+  });
+
+  test('should use default debounce of 300ms', async () => {
+    const options: WatcherOptions = {
+      files: [],
+      config: {}, // No debounce specified
+      onRun: onRunMock,
+      logger: mockLogger as unknown as WatcherOptions['logger'],
+    };
+
+    watcher = new FileWatcher(options);
+
+    const startTime = performance.now();
+    triggerFileChange(watcher, 'test.yaml');
+
+    // Wait less than default debounce
+    await Bun.sleep(100);
+    expect(onRunMock).not.toHaveBeenCalled();
+
+    // Wait for full debounce
+    await Bun.sleep(250);
+    expect(onRunMock).toHaveBeenCalledTimes(1);
+
+    const elapsed = performance.now() - startTime;
+    expect(elapsed).toBeGreaterThanOrEqual(300);
+  });
+
+  test('should handle onRun errors gracefully', async () => {
+    const errorOnRun = mock(async () => {
+      throw new Error('Test error');
+    });
+
+    const options: WatcherOptions = {
+      files: [],
+      config: { debounce: 10 },
+      onRun: errorOnRun,
+      logger: mockLogger as unknown as WatcherOptions['logger'],
+    };
+
+    watcher = new FileWatcher(options);
+
+    // Should not throw
+    triggerFileChange(watcher, 'test.yaml');
+    await Bun.sleep(50);
+
+    expect(mockLogger.logError).toHaveBeenCalledWith('Test error');
+  });
+
+  test('should log file changed with filename', async () => {
+    const options: WatcherOptions = {
+      files: [],
+      config: { debounce: 10, clear: false },
+      onRun: onRunMock,
+      logger: mockLogger as unknown as WatcherOptions['logger'],
+    };
+
+    watcher = new FileWatcher(options);
+
+    triggerFileChange(watcher, 'my-api.yaml');
+    await Bun.sleep(50);
+
+    expect(mockLogger.logFileChanged).toHaveBeenCalledWith('my-api.yaml');
+  });
+
+  test('should call logWatchReady after run completes', async () => {
+    const options: WatcherOptions = {
+      files: [],
+      config: { debounce: 10, clear: false },
+      onRun: onRunMock,
+      logger: mockLogger as unknown as WatcherOptions['logger'],
+    };
+
+    watcher = new FileWatcher(options);
+
+    triggerFileChange(watcher, 'test.yaml');
+    await Bun.sleep(50);
+
+    expect(mockLogger.logWatchReady).toHaveBeenCalled();
+  });
+});

package/src/watcher/file-watcher.ts

@@ -0,0 +1,140 @@
+import { type FSWatcher, watch } from 'node:fs';
+import type { WatchConfig } from '../types/config';
+import type { Logger } from '../utils/logger';
+
+export interface WatcherOptions {
+  files: string[];
+  config: WatchConfig;
+  onRun: () => Promise<void>;
+  logger: Logger;
+}
+
+export class FileWatcher {
+  private watchers: FSWatcher[] = [];
+  private debounceTimer: Timer | null = null;
+  private isRunning = false;
+  private pendingRun = false;
+  private options: WatcherOptions;
+
+  constructor(options: WatcherOptions) {
+    this.options = options;
+  }
+
+  async start(): Promise<void> {
+    const { files, logger } = this.options;
+
+    // Initial run
+    await this.runRequests();
+
+    // Setup watchers for each file
+    for (const file of files) {
+      try {
+        const watcher = watch(file, (event) => {
+          if (event === 'change') {
+            this.handleFileChange(file);
+          }
+        });
+
+        watcher.on('error', (error) => {
+          logger.logWarning(`Watch error on ${file}: ${error.message}`);
+        });
+
+        this.watchers.push(watcher);
+      } catch (error) {
+        logger.logWarning(
+          `Failed to watch ${file}: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    }
+
+    // Log watching status
+    logger.logWatch(files);
+
+    // Handle graceful shutdown
+    this.setupSignalHandlers();
+
+    // Keep process alive
+    await this.keepAlive();
+  }
+
+  private handleFileChange(filename: string): void {
+    const { config, logger } = this.options;
+    const debounce = config.debounce ?? 300;
+
+    // Clear existing debounce timer
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+    }
+
+    // Debounce the run
+    this.debounceTimer = setTimeout(async () => {
+      // If already running, queue for after completion
+      if (this.isRunning) {
+        this.pendingRun = true;
+        return;
+      }
+
+      if (config.clear !== false) {
+        console.clear();
+      }
+
+      logger.logFileChanged(filename);
+      await this.runRequests();
+    }, debounce);
+  }
+
+  private async runRequests(): Promise<void> {
+    const { onRun, logger } = this.options;
+
+    this.isRunning = true;
+
+    try {
+      await onRun();
+    } catch (error) {
+      logger.logError(error instanceof Error ? error.message : String(error));
+    }
+
+    this.isRunning = false;
+
+    // Check for pending runs
+    if (this.pendingRun) {
+      this.pendingRun = false;
+      const { config } = this.options;
+      if (config.clear !== false) {
+        console.clear();
+      }
+      logger.logFileChanged('(queued change)');
+      await this.runRequests();
+    } else {
+      logger.logWatchReady();
+    }
+  }
+
+  private setupSignalHandlers(): void {
+    const cleanup = () => {
+      this.stop();
+      process.exit(0);
+    };
+
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
+  }
+
+  private async keepAlive(): Promise<never> {
+    while (true) {
+      await Bun.sleep(1000);
+    }
+  }
+
+  stop(): void {
+    for (const watcher of this.watchers) {
+      watcher.close();
+    }
+    this.watchers = [];
+
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+  }
+}