@curl-runner/cli 1.10.0 → 1.12.0

package/src/snapshot/snapshot-manager.ts

@@ -0,0 +1,342 @@
+import * as path from 'node:path';
+import type {
+  ExecutionResult,
+  GlobalSnapshotConfig,
+  JsonValue,
+  Snapshot,
+  SnapshotCompareResult,
+  SnapshotConfig,
+  SnapshotFile,
+} from '../types/config';
+import { SnapshotDiffer } from './snapshot-differ';
+
+const SNAPSHOT_VERSION = 1;
+const DEFAULT_SNAPSHOT_DIR = '__snapshots__';
+
+/**
+ * Manages snapshot files: reading, writing, comparing, and updating.
+ */
+export class SnapshotManager {
+  private snapshotDir: string;
+  private globalConfig: GlobalSnapshotConfig;
+  private writeLocks: Map<string, Promise<void>> = new Map();
+
+  constructor(globalConfig: GlobalSnapshotConfig = {}) {
+    this.globalConfig = globalConfig;
+    this.snapshotDir = globalConfig.dir || DEFAULT_SNAPSHOT_DIR;
+  }
+
+  /**
+   * Gets the snapshot file path for a YAML file.
+   */
+  getSnapshotPath(yamlPath: string): string {
+    const dir = path.dirname(yamlPath);
+    const basename = path.basename(yamlPath, path.extname(yamlPath));
+    return path.join(dir, this.snapshotDir, `${basename}.snap.json`);
+  }
+
+  /**
+   * Loads snapshot file for a YAML file.
+   */
+  async load(yamlPath: string): Promise<SnapshotFile | null> {
+    const snapshotPath = this.getSnapshotPath(yamlPath);
+    try {
+      const file = Bun.file(snapshotPath);
+      if (!(await file.exists())) {
+        return null;
+      }
+      const content = await file.text();
+      return JSON.parse(content) as SnapshotFile;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Saves snapshot file with write queue for parallel safety.
+   */
+  async save(yamlPath: string, data: SnapshotFile): Promise<void> {
+    const snapshotPath = this.getSnapshotPath(yamlPath);
+
+    // Queue writes to prevent race conditions
+    const existingLock = this.writeLocks.get(snapshotPath);
+    const writePromise = (async () => {
+      if (existingLock) {
+        await existingLock;
+      }
+
+      // Ensure directory exists
+      const dir = path.dirname(snapshotPath);
+      const fs = await import('node:fs/promises');
+      await fs.mkdir(dir, { recursive: true });
+
+      // Write with pretty formatting
+      const content = JSON.stringify(data, null, 2);
+      await Bun.write(snapshotPath, content);
+    })();
+
+    this.writeLocks.set(snapshotPath, writePromise);
+    await writePromise;
+    this.writeLocks.delete(snapshotPath);
+  }
+
+  /**
+   * Gets a single snapshot by request name.
+   */
+  async get(yamlPath: string, requestName: string): Promise<Snapshot | null> {
+    const file = await this.load(yamlPath);
+    return file?.snapshots[requestName] || null;
+  }
+
+  /**
+   * Creates a snapshot from execution result.
+   */
+  createSnapshot(result: ExecutionResult, config: SnapshotConfig): Snapshot {
+    const include = config.include || ['body'];
+    const snapshot: Snapshot = {
+      hash: '',
+      updatedAt: new Date().toISOString(),
+    };
+
+    if (include.includes('status') && result.status !== undefined) {
+      snapshot.status = result.status;
+    }
+
+    if (include.includes('headers') && result.headers) {
+      // Normalize headers: lowercase keys, sorted
+      snapshot.headers = this.normalizeHeaders(result.headers);
+    }
+
+    if (include.includes('body') && result.body !== undefined) {
+      snapshot.body = result.body;
+    }
+
+    // Generate hash from content
+    snapshot.hash = this.hash(snapshot);
+
+    return snapshot;
+  }
+
+  /**
+   * Normalizes headers for consistent comparison.
+   */
+  private normalizeHeaders(headers: Record<string, string>): Record<string, string> {
+    const normalized: Record<string, string> = {};
+    const sortedKeys = Object.keys(headers).sort();
+    for (const key of sortedKeys) {
+      normalized[key.toLowerCase()] = headers[key];
+    }
+    return normalized;
+  }
+
+  /**
+   * Generates a hash for snapshot content.
+   */
+  hash(content: unknown): string {
+    const str = JSON.stringify(content);
+    const hasher = new Bun.CryptoHasher('md5');
+    hasher.update(str);
+    return hasher.digest('hex').slice(0, 8);
+  }
+
+  /**
+   * Compares execution result against stored snapshot and optionally updates.
+   */
+  async compareAndUpdate(
+    yamlPath: string,
+    requestName: string,
+    result: ExecutionResult,
+    config: SnapshotConfig,
+  ): Promise<SnapshotCompareResult> {
+    const snapshotName = config.name || requestName;
+    const existingSnapshot = await this.get(yamlPath, snapshotName);
+    const newSnapshot = this.createSnapshot(result, config);
+
+    // No existing snapshot
+    if (!existingSnapshot) {
+      if (this.globalConfig.ci) {
+        // CI mode: fail on missing snapshot
+        return {
+          match: false,
+          isNew: true,
+          updated: false,
+          differences: [
+            {
+              path: '',
+              expected: 'snapshot',
+              received: 'none',
+              type: 'removed',
+            },
+          ],
+        };
+      }
+
+      // Create new snapshot
+      await this.updateSnapshot(yamlPath, snapshotName, newSnapshot);
+      return {
+        match: true,
+        isNew: true,
+        updated: true,
+        differences: [],
+      };
+    }
+
+    // Compare snapshots
+    const differ = new SnapshotDiffer(config);
+    const diffResult = differ.compare(existingSnapshot, newSnapshot);
+
+    if (diffResult.match) {
+      return {
+        match: true,
+        isNew: false,
+        updated: false,
+        differences: [],
+      };
+    }
+
+    // Handle update modes
+    const updateMode = this.globalConfig.updateMode || 'none';
+    if (updateMode === 'all' || updateMode === 'failing') {
+      await this.updateSnapshot(yamlPath, snapshotName, newSnapshot);
+      return {
+        match: true,
+        isNew: false,
+        updated: true,
+        differences: diffResult.differences,
+      };
+    }
+
+    return {
+      match: false,
+      isNew: false,
+      updated: false,
+      differences: diffResult.differences,
+    };
+  }
+
+  /**
+   * Updates a single snapshot in the file.
+   */
+  private async updateSnapshot(
+    yamlPath: string,
+    snapshotName: string,
+    snapshot: Snapshot,
+  ): Promise<void> {
+    let file = await this.load(yamlPath);
+    if (!file) {
+      file = {
+        version: SNAPSHOT_VERSION,
+        snapshots: {},
+      };
+    }
+
+    file.snapshots[snapshotName] = snapshot;
+    await this.save(yamlPath, file);
+  }
+
+  /**
+   * Merges request-level config with global config.
+   */
+  static mergeConfig(
+    globalConfig: GlobalSnapshotConfig | undefined,
+    requestConfig: SnapshotConfig | boolean | undefined,
+  ): SnapshotConfig | null {
+    // Not enabled
+    if (!requestConfig && !globalConfig?.enabled) {
+      return null;
+    }
+
+    // Simple boolean enable
+    if (requestConfig === true) {
+      return {
+        enabled: true,
+        include: globalConfig?.include || ['body'],
+        exclude: globalConfig?.exclude || [],
+        match: globalConfig?.match || {},
+      };
+    }
+
+    // Detailed config
+    if (typeof requestConfig === 'object' && requestConfig.enabled !== false) {
+      return {
+        enabled: true,
+        name: requestConfig.name,
+        include: requestConfig.include || globalConfig?.include || ['body'],
+        exclude: [...(globalConfig?.exclude || []), ...(requestConfig.exclude || [])],
+        match: { ...(globalConfig?.match || {}), ...(requestConfig.match || {}) },
+      };
+    }
+
+    // Global enabled but request not specified
+    if (globalConfig?.enabled && requestConfig === undefined) {
+      return {
+        enabled: true,
+        include: globalConfig.include || ['body'],
+        exclude: globalConfig.exclude || [],
+        match: globalConfig.match || {},
+      };
+    }
+
+    return null;
+  }
+}
+
+/**
+ * Extracts body content for snapshot, applying exclusions.
+ */
+export function filterSnapshotBody(body: JsonValue, exclude: string[]): JsonValue {
+  if (body === null || typeof body !== 'object') {
+    return body;
+  }
+
+  const bodyExcludes = exclude.filter((p) => p.startsWith('body.')).map((p) => p.slice(5)); // Remove 'body.' prefix
+
+  if (bodyExcludes.length === 0) {
+    return body;
+  }
+
+  return filterObject(body, bodyExcludes, '');
+}
+
+function filterObject(obj: JsonValue, excludes: string[], currentPath: string): JsonValue {
+  if (obj === null || typeof obj !== 'object') {
+    return obj;
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map((item, index) => {
+      const itemPath = currentPath ? `${currentPath}[${index}]` : `[${index}]`;
+      return filterObject(item, excludes, itemPath);
+    });
+  }
+
+  const result: Record<string, JsonValue> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const fullPath = currentPath ? `${currentPath}.${key}` : key;
+
+    // Check if this path should be excluded
+    const shouldExclude = excludes.some((pattern) => {
+      // Exact match
+      if (pattern === fullPath) {
+        return true;
+      }
+      // Wildcard match (e.g., '*.timestamp' matches 'user.timestamp')
+      if (pattern.startsWith('*.')) {
+        const suffix = pattern.slice(2);
+        return fullPath.endsWith(`.${suffix}`) || fullPath === suffix;
+      }
+      // Array wildcard (e.g., '[*].id')
+      if (pattern.includes('[*]')) {
+        const regex = new RegExp(`^${pattern.replace(/\[\*\]/g, '\\[\\d+\\]')}$`);
+        return regex.test(fullPath);
+      }
+      return false;
+    });
+
+    if (!shouldExclude) {
+      result[key] = filterObject(value, excludes, fullPath);
+    }
+  }
+
+  return result;
+}

package/src/types/config.ts

@@ -57,6 +57,87 @@ export type FormDataConfig = Record<string, FormFieldValue>;
  */
 export type StoreConfig = Record<string, string>;
 
+/**
+ * Operators for conditional expressions.
+ */
+export type ConditionOperator =
+  | '=='
+  | '!='
+  | '>'
+  | '<'
+  | '>='
+  | '<='
+  | 'contains'
+  | 'matches'
+  | 'exists'
+  | 'not-exists';
+
+/**
+ * A single condition expression comparing a store value against an expected value.
+ *
+ * Examples:
+ * - `{ left: "store.status", operator: "==", right: 200 }`
+ * - `{ left: "store.userId", operator: "exists" }`
+ * - `{ left: "store.body.type", operator: "contains", right: "user" }`
+ */
+export interface ConditionExpression {
+  /** Left operand - typically a store path like "store.status" or "store.body.id" */
+  left: string;
+  /** Comparison operator */
+  operator: ConditionOperator;
+  /** Right operand - the value to compare against. Optional for exists/not-exists. */
+  right?: string | number | boolean;
+  /** Case-sensitive comparison for string operators. Default: false (case-insensitive) */
+  caseSensitive?: boolean;
+}
+
+/**
+ * Configuration for conditional request execution.
+ * Supports single conditions, AND (all), and OR (any) compound conditions.
+ *
+ * Examples:
+ * ```yaml
+ * # Single condition
+ * when:
+ *   left: store.status
+ *   operator: "=="
+ *   right: 200
+ *
+ * # AND condition (all must be true)
+ * when:
+ *   all:
+ *     - left: store.status
+ *       operator: "=="
+ *       right: 200
+ *     - left: store.userId
+ *       operator: exists
+ *
+ * # OR condition (any must be true)
+ * when:
+ *   any:
+ *     - left: store.type
+ *       operator: "=="
+ *       right: "admin"
+ *     - left: store.type
+ *       operator: "=="
+ *       right: "superuser"
+ * ```
+ */
+export interface WhenCondition {
+  /** All conditions must be true (AND logic) */
+  all?: ConditionExpression[];
+  /** Any condition must be true (OR logic) */
+  any?: ConditionExpression[];
+  /** Single condition - left operand */
+  left?: string;
+  /** Single condition - operator */
+  operator?: ConditionOperator;
+  /** Single condition - right operand */
+  right?: string | number | boolean;
+  /** Case-sensitive comparison for string operators. Default: false */
+  caseSensitive?: boolean;
+}
+
 /**
  * SSL/TLS certificate configuration options.
  *
@@ -140,6 +221,30 @@ export interface RequestConfig {
    *   contentType: headers.content-type
    */
   store?: StoreConfig;
+  /**
+   * Conditional execution - skip/run request based on previous results.
+   * Only works in sequential execution mode.
+   *
+   * @example
+   * # Object syntax
+   * when:
+   *   left: store.status
+   *   operator: "=="
+   *   right: 200
+   *
+   * # String shorthand
+   * when: "store.status == 200"
+   *
+   * # Compound conditions
+   * when:
+   *   all:
+   *     - left: store.userId
+   *       operator: exists
+   *     - left: store.status
+   *       operator: "<"
+   *       right: 400
+   */
+  when?: WhenCondition | string;
   expect?: {
     failure?: boolean; // If true, expect the request to fail (for negative testing)
     status?: number | number[];
@@ -147,6 +252,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;
@@ -215,6 +325,11 @@ export interface GlobalConfig {
    * 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;
@@ -252,12 +367,19 @@ export interface ExecutionResult {
     firstByte?: number;
     download?: number;
   };
+  /** Snapshot comparison result (if snapshot testing enabled). */
+  snapshotResult?: SnapshotCompareResult;
+  /** Whether this request was skipped due to a `when` condition. */
+  skipped?: boolean;
+  /** Reason the request was skipped (condition that failed). */
+  skipReason?: string;
 }
 
 export interface ExecutionSummary {
   total: number;
   successful: number;
   failed: number;
+  skipped: number;
   duration: number;
   results: ExecutionResult[];
 }
@@ -280,3 +402,71 @@ export interface WatchConfig {
   /** 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[];
+}