@curl-runner/cli 1.10.0 → 1.12.0

package/src/snapshot/snapshot-differ.ts

@@ -0,0 +1,296 @@
+import type { JsonValue, Snapshot, SnapshotConfig, SnapshotDiff } from '../types/config';
+
+interface DiffResult {
+  match: boolean;
+  differences: SnapshotDiff[];
+}
+
+/**
+ * Compares snapshots with support for exclusions, wildcards, and regex patterns.
+ */
+export class SnapshotDiffer {
+  private excludePaths: Set<string>;
+  private matchRules: Map<string, string>;
+
+  constructor(config: SnapshotConfig) {
+    this.excludePaths = new Set(config.exclude || []);
+    this.matchRules = new Map(Object.entries(config.match || {}));
+  }
+
+  /**
+   * Compares two snapshots and returns differences.
+   */
+  compare(expected: Snapshot, received: Snapshot): DiffResult {
+    const differences: SnapshotDiff[] = [];
+
+    // Compare status
+    if (expected.status !== undefined || received.status !== undefined) {
+      if (expected.status !== received.status && !this.isExcluded('status')) {
+        differences.push({
+          path: 'status',
+          expected: expected.status,
+          received: received.status,
+          type: 'changed',
+        });
+      }
+    }
+
+    // Compare headers
+    if (expected.headers || received.headers) {
+      const headerDiffs = this.compareObjects(
+        expected.headers || {},
+        received.headers || {},
+        'headers',
+      );
+      differences.push(...headerDiffs);
+    }
+
+    // Compare body
+    if (expected.body !== undefined || received.body !== undefined) {
+      const bodyDiffs = this.deepCompare(expected.body, received.body, 'body');
+      differences.push(...bodyDiffs);
+    }
+
+    return {
+      match: differences.length === 0,
+      differences,
+    };
+  }
+
+  /**
+   * Deep comparison of two values with path tracking.
+   */
+  deepCompare(expected: unknown, received: unknown, path: string): SnapshotDiff[] {
+    // Check if path is excluded
+    if (this.isExcluded(path)) {
+      return [];
+    }
+
+    // Check match rules (wildcards, regex)
+    if (this.matchesRule(path, received)) {
+      return [];
+    }
+
+    // Both null/undefined
+    if (expected === null && received === null) {
+      return [];
+    }
+    if (expected === undefined && received === undefined) {
+      return [];
+    }
+
+    // Type mismatch
+    const expectedType = this.getType(expected);
+    const receivedType = this.getType(received);
+    if (expectedType !== receivedType) {
+      return [
+        {
+          path,
+          expected,
+          received,
+          type: 'type_mismatch',
+        },
+      ];
+    }
+
+    // Primitives
+    if (expectedType !== 'object' && expectedType !== 'array') {
+      if (expected !== received) {
+        return [
+          {
+            path,
+            expected,
+            received,
+            type: 'changed',
+          },
+        ];
+      }
+      return [];
+    }
+
+    // Arrays
+    if (expectedType === 'array') {
+      return this.compareArrays(expected as JsonValue[], received as JsonValue[], path);
+    }
+
+    // Objects
+    return this.compareObjects(
+      expected as Record<string, unknown>,
+      received as Record<string, unknown>,
+      path,
+    );
+  }
+
+  /**
+   * Compares two arrays.
+   */
+  private compareArrays(
+    expected: JsonValue[],
+    received: JsonValue[],
+    path: string,
+  ): SnapshotDiff[] {
+    const differences: SnapshotDiff[] = [];
+
+    // Check length difference
+    const maxLen = Math.max(expected.length, received.length);
+
+    for (let i = 0; i < maxLen; i++) {
+      const itemPath = `${path}[${i}]`;
+
+      if (i >= expected.length) {
+        // Added item
+        if (!this.isExcluded(itemPath)) {
+          differences.push({
+            path: itemPath,
+            expected: undefined,
+            received: received[i],
+            type: 'added',
+          });
+        }
+      } else if (i >= received.length) {
+        // Removed item
+        if (!this.isExcluded(itemPath)) {
+          differences.push({
+            path: itemPath,
+            expected: expected[i],
+            received: undefined,
+            type: 'removed',
+          });
+        }
+      } else {
+        // Compare items
+        const itemDiffs = this.deepCompare(expected[i], received[i], itemPath);
+        differences.push(...itemDiffs);
+      }
+    }
+
+    return differences;
+  }
+
+  /**
+   * Compares two objects.
+   */
+  private compareObjects(
+    expected: Record<string, unknown>,
+    received: Record<string, unknown>,
+    path: string,
+  ): SnapshotDiff[] {
+    const differences: SnapshotDiff[] = [];
+    const allKeys = new Set([...Object.keys(expected), ...Object.keys(received)]);
+
+    for (const key of allKeys) {
+      const keyPath = path ? `${path}.${key}` : key;
+      const hasExpected = key in expected;
+      const hasReceived = key in received;
+
+      if (!hasExpected && hasReceived) {
+        // Added key
+        if (!this.isExcluded(keyPath)) {
+          differences.push({
+            path: keyPath,
+            expected: undefined,
+            received: received[key],
+            type: 'added',
+          });
+        }
+      } else if (hasExpected && !hasReceived) {
+        // Removed key
+        if (!this.isExcluded(keyPath)) {
+          differences.push({
+            path: keyPath,
+            expected: expected[key],
+            received: undefined,
+            type: 'removed',
+          });
+        }
+      } else {
+        // Compare values
+        const keyDiffs = this.deepCompare(expected[key], received[key], keyPath);
+        differences.push(...keyDiffs);
+      }
+    }
+
+    return differences;
+  }
+
+  /**
+   * Checks if a path should be excluded from comparison.
+   */
+  isExcluded(path: string): boolean {
+    // Exact match
+    if (this.excludePaths.has(path)) {
+      return true;
+    }
+
+    for (const pattern of this.excludePaths) {
+      // Wildcard prefix (e.g., '*.timestamp')
+      if (pattern.startsWith('*.')) {
+        const suffix = pattern.slice(2);
+        if (path.endsWith(`.${suffix}`)) {
+          return true;
+        }
+        // Also match root level (e.g., 'timestamp' matches '*.timestamp')
+        const lastPart = path.split('.').pop();
+        if (lastPart === suffix) {
+          return true;
+        }
+      }
+
+      // Array wildcard (e.g., 'body[*].id')
+      if (pattern.includes('[*]')) {
+        const regex = new RegExp(
+          `^${pattern.replace(/\[\*\]/g, '\\[\\d+\\]').replace(/\./g, '\\.')}$`,
+        );
+        if (regex.test(path)) {
+          return true;
+        }
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Checks if a value matches a custom rule for its path.
+   */
+  matchesRule(path: string, value: unknown): boolean {
+    const rule = this.matchRules.get(path);
+    if (!rule) {
+      return false;
+    }
+
+    // Wildcard: accept any value
+    if (rule === '*') {
+      return true;
+    }
+
+    // Regex pattern
+    if (rule.startsWith('regex:')) {
+      const pattern = rule.slice(6);
+      try {
+        const regex = new RegExp(pattern);
+        return regex.test(String(value));
+      } catch {
+        return false;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Gets the type of a value for comparison.
+   */
+  private getType(value: unknown): string {
+    if (value === null) {
+      return 'null';
+    }
+    if (value === undefined) {
+      return 'undefined';
+    }
+    if (Array.isArray(value)) {
+      return 'array';
+    }
+    return typeof value;
+  }
+}

package/src/snapshot/snapshot-formatter.ts

@@ -0,0 +1,170 @@
+import type { SnapshotCompareResult, SnapshotDiff } from '../types/config';
+
+const COLORS = {
+  reset: '\x1b[0m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+  dim: '\x1b[2m',
+  bright: '\x1b[1m',
+};
+
+/**
+ * Formats snapshot comparison results for terminal output.
+ */
+export class SnapshotFormatter {
+  private color(text: string, color: keyof typeof COLORS): string {
+    return `${COLORS[color]}${text}${COLORS.reset}`;
+  }
+
+  /**
+   * Formats the snapshot result for display.
+   */
+  formatResult(requestName: string, result: SnapshotCompareResult): string {
+    const lines: string[] = [];
+
+    if (result.isNew && result.updated) {
+      lines.push(
+        `  ${this.color('NEW', 'cyan')} Snapshot created for "${this.color(requestName, 'bright')}"`,
+      );
+      return lines.join('\n');
+    }
+
+    if (result.updated) {
+      lines.push(
+        `  ${this.color('UPDATED', 'yellow')} Snapshot updated for "${this.color(requestName, 'bright')}"`,
+      );
+      return lines.join('\n');
+    }
+
+    if (result.match) {
+      lines.push(
+        `  ${this.color('PASS', 'green')} Snapshot matches for "${this.color(requestName, 'bright')}"`,
+      );
+      return lines.join('\n');
+    }
+
+    // Mismatch
+    lines.push(
+      `  ${this.color('FAIL', 'red')} Snapshot mismatch for "${this.color(requestName, 'bright')}"`,
+    );
+    lines.push('');
+    lines.push(this.formatDiff(result.differences));
+    lines.push('');
+    lines.push(this.color('  Run with --update-snapshots (-u) to update', 'dim'));
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Formats differences for display.
+   */
+  formatDiff(differences: SnapshotDiff[]): string {
+    const lines: string[] = [];
+    lines.push(`  ${this.color('- Expected', 'red')}`);
+    lines.push(`  ${this.color('+ Received', 'green')}`);
+    lines.push('');
+
+    for (const diff of differences) {
+      lines.push(this.formatDifference(diff));
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Formats a single difference.
+   */
+  private formatDifference(diff: SnapshotDiff): string {
+    const lines: string[] = [];
+    const path = diff.path || '(root)';
+
+    switch (diff.type) {
+      case 'added':
+        lines.push(`  ${this.color(path, 'cyan')}:`);
+        lines.push(`    ${this.color(`+ ${this.stringify(diff.received)}`, 'green')}`);
+        break;
+
+      case 'removed':
+        lines.push(`  ${this.color(path, 'cyan')}:`);
+        lines.push(`    ${this.color(`- ${this.stringify(diff.expected)}`, 'red')}`);
+        break;
+
+      case 'changed':
+        lines.push(`  ${this.color(path, 'cyan')}:`);
+        lines.push(`    ${this.color(`- ${this.stringify(diff.expected)}`, 'red')}`);
+        lines.push(`    ${this.color(`+ ${this.stringify(diff.received)}`, 'green')}`);
+        break;
+
+      case 'type_mismatch':
+        lines.push(`  ${this.color(path, 'cyan')} (type mismatch):`);
+        lines.push(
+          `    ${this.color(`- ${this.stringify(diff.expected)} (${typeof diff.expected})`, 'red')}`,
+        );
+        lines.push(
+          `    ${this.color(`+ ${this.stringify(diff.received)} (${typeof diff.received})`, 'green')}`,
+        );
+        break;
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Converts value to display string.
+   */
+  private stringify(value: unknown): string {
+    if (value === undefined) {
+      return 'undefined';
+    }
+    if (value === null) {
+      return 'null';
+    }
+    if (typeof value === 'string') {
+      return `"${value}"`;
+    }
+    if (typeof value === 'object') {
+      const str = JSON.stringify(value);
+      // Truncate long values
+      if (str.length > 80) {
+        return `${str.slice(0, 77)}...`;
+      }
+      return str;
+    }
+    return String(value);
+  }
+
+  /**
+   * Formats summary statistics.
+   */
+  formatSummary(stats: SnapshotStats): string {
+    const parts: string[] = [];
+
+    if (stats.passed > 0) {
+      parts.push(this.color(`${stats.passed} passed`, 'green'));
+    }
+    if (stats.failed > 0) {
+      parts.push(this.color(`${stats.failed} failed`, 'red'));
+    }
+    if (stats.updated > 0) {
+      parts.push(this.color(`${stats.updated} updated`, 'yellow'));
+    }
+    if (stats.created > 0) {
+      parts.push(this.color(`${stats.created} created`, 'cyan'));
+    }
+
+    if (parts.length === 0) {
+      return '';
+    }
+
+    return `Snapshots: ${parts.join(', ')}`;
+  }
+}
+
+export interface SnapshotStats {
+  passed: number;
+  failed: number;
+  updated: number;
+  created: number;
+}

package/src/snapshot/snapshot-manager.test.ts

@@ -0,0 +1,204 @@
+import { describe, expect, test } from 'bun:test';
+import type { ExecutionResult } from '../types/config';
+import { filterSnapshotBody, SnapshotManager } from './snapshot-manager';
+
+describe('SnapshotManager', () => {
+  describe('getSnapshotPath', () => {
+    test('should generate correct snapshot path', () => {
+      const manager = new SnapshotManager({});
+      expect(manager.getSnapshotPath('tests/api.yaml')).toBe('tests/__snapshots__/api.snap.json');
+    });
+
+    test('should use custom directory', () => {
+      const manager = new SnapshotManager({ dir: '.snapshots' });
+      expect(manager.getSnapshotPath('api.yaml')).toBe('.snapshots/api.snap.json');
+    });
+
+    test('should handle nested paths', () => {
+      const manager = new SnapshotManager({});
+      expect(manager.getSnapshotPath('tests/integration/users.yaml')).toBe(
+        'tests/integration/__snapshots__/users.snap.json',
+      );
+    });
+  });
+
+  describe('createSnapshot', () => {
+    const mockResult: ExecutionResult = {
+      request: { url: 'https://api.example.com' },
+      success: true,
+      status: 200,
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Request-Id': 'abc123',
+      },
+      body: {
+        id: 1,
+        name: 'Test',
+        timestamp: '2024-01-01',
+      },
+    };
+
+    test('should create snapshot with body only by default', () => {
+      const manager = new SnapshotManager({});
+      const snapshot = manager.createSnapshot(mockResult, { include: ['body'] });
+
+      expect(snapshot.body).toEqual(mockResult.body);
+      expect(snapshot.status).toBeUndefined();
+      expect(snapshot.headers).toBeUndefined();
+      expect(snapshot.hash).toBeDefined();
+      expect(snapshot.updatedAt).toBeDefined();
+    });
+
+    test('should create snapshot with status', () => {
+      const manager = new SnapshotManager({});
+      const snapshot = manager.createSnapshot(mockResult, { include: ['status'] });
+
+      expect(snapshot.status).toBe(200);
+      expect(snapshot.body).toBeUndefined();
+    });
+
+    test('should create snapshot with headers (normalized)', () => {
+      const manager = new SnapshotManager({});
+      const snapshot = manager.createSnapshot(mockResult, { include: ['headers'] });
+
+      expect(snapshot.headers).toEqual({
+        'content-type': 'application/json',
+        'x-request-id': 'abc123',
+      });
+    });
+
+    test('should create snapshot with all components', () => {
+      const manager = new SnapshotManager({});
+      const snapshot = manager.createSnapshot(mockResult, {
+        include: ['status', 'headers', 'body'],
+      });
+
+      expect(snapshot.status).toBe(200);
+      expect(snapshot.headers).toBeDefined();
+      expect(snapshot.body).toBeDefined();
+    });
+  });
+
+  describe('hash', () => {
+    test('should generate consistent hashes', () => {
+      const manager = new SnapshotManager({});
+      const content = { id: 1, name: 'test' };
+
+      const hash1 = manager.hash(content);
+      const hash2 = manager.hash(content);
+
+      expect(hash1).toBe(hash2);
+    });
+
+    test('should generate different hashes for different content', () => {
+      const manager = new SnapshotManager({});
+
+      const hash1 = manager.hash({ id: 1 });
+      const hash2 = manager.hash({ id: 2 });
+
+      expect(hash1).not.toBe(hash2);
+    });
+  });
+
+  describe('mergeConfig', () => {
+    test('should return null if not enabled', () => {
+      const config = SnapshotManager.mergeConfig({}, undefined);
+      expect(config).toBeNull();
+    });
+
+    test('should handle boolean true', () => {
+      const config = SnapshotManager.mergeConfig({}, true);
+      expect(config).toEqual({
+        enabled: true,
+        include: ['body'],
+        exclude: [],
+        match: {},
+      });
+    });
+
+    test('should merge global and request excludes', () => {
+      const config = SnapshotManager.mergeConfig(
+        { exclude: ['*.timestamp'] },
+        { enabled: true, exclude: ['body.id'] },
+      );
+      expect(config?.exclude).toEqual(['*.timestamp', 'body.id']);
+    });
+
+    test('should override include from request config', () => {
+      const config = SnapshotManager.mergeConfig(
+        { include: ['body'] },
+        { enabled: true, include: ['status', 'body'] },
+      );
+      expect(config?.include).toEqual(['status', 'body']);
+    });
+
+    test('should use global enabled', () => {
+      const config = SnapshotManager.mergeConfig({ enabled: true }, undefined);
+      expect(config?.enabled).toBe(true);
+    });
+  });
+});
+
+describe('filterSnapshotBody', () => {
+  test('should return primitive values unchanged', () => {
+    expect(filterSnapshotBody('string', [])).toBe('string');
+    expect(filterSnapshotBody(123, [])).toBe(123);
+    expect(filterSnapshotBody(null, [])).toBe(null);
+  });
+
+  test('should return body unchanged if no excludes', () => {
+    const body = { id: 1, name: 'test' };
+    expect(filterSnapshotBody(body, [])).toEqual(body);
+  });
+
+  test('should filter exact paths', () => {
+    const body = { id: 1, timestamp: '2024-01-01', name: 'test' };
+    const result = filterSnapshotBody(body, ['body.timestamp']);
+    expect(result).toEqual({ id: 1, name: 'test' });
+  });
+
+  test('should filter wildcard paths', () => {
+    const body = {
+      user: { id: 1, createdAt: '2024-01-01' },
+      post: { id: 2, createdAt: '2024-01-02' },
+    };
+    const result = filterSnapshotBody(body, ['body.*.createdAt']);
+    expect(result).toEqual({
+      user: { id: 1 },
+      post: { id: 2 },
+    });
+  });
+
+  test('should filter array wildcards', () => {
+    const body = {
+      items: [
+        { id: 1, updatedAt: '2024-01-01' },
+        { id: 2, updatedAt: '2024-01-02' },
+      ],
+    };
+    const result = filterSnapshotBody(body, ['body.items[*].updatedAt']);
+    expect(result).toEqual({
+      items: [{ id: 1 }, { id: 2 }],
+    });
+  });
+
+  test('should handle nested objects', () => {
+    const body = {
+      data: {
+        user: {
+          id: 1,
+          meta: { lastLogin: '2024-01-01' },
+        },
+      },
+    };
+    const result = filterSnapshotBody(body, ['body.data.user.meta.lastLogin']);
+    expect(result).toEqual({
+      data: {
+        user: {
+          id: 1,
+          meta: {},
+        },
+      },
+    });
+  });
+});