@curl-runner/cli 1.10.0 → 1.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@curl-runner/cli",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "description": "A powerful CLI tool for HTTP request management using YAML configuration",
   "type": "module",
   "main": "./dist/cli.js",

package/src/cli.ts

@@ -166,6 +166,38 @@ class CurlRunnerCLI {
       };
     }
 
+    // Snapshot configuration
+    if (process.env.CURL_RUNNER_SNAPSHOT) {
+      envConfig.snapshot = {
+        ...envConfig.snapshot,
+        enabled: process.env.CURL_RUNNER_SNAPSHOT.toLowerCase() === 'true',
+      };
+    }
+
+    if (process.env.CURL_RUNNER_SNAPSHOT_UPDATE) {
+      const mode = process.env.CURL_RUNNER_SNAPSHOT_UPDATE.toLowerCase();
+      if (['none', 'all', 'failing'].includes(mode)) {
+        envConfig.snapshot = {
+          ...envConfig.snapshot,
+          updateMode: mode as 'none' | 'all' | 'failing',
+        };
+      }
+    }
+
+    if (process.env.CURL_RUNNER_SNAPSHOT_DIR) {
+      envConfig.snapshot = {
+        ...envConfig.snapshot,
+        dir: process.env.CURL_RUNNER_SNAPSHOT_DIR,
+      };
+    }
+
+    if (process.env.CURL_RUNNER_SNAPSHOT_CI) {
+      envConfig.snapshot = {
+        ...envConfig.snapshot,
+        ci: process.env.CURL_RUNNER_SNAPSHOT_CI.toLowerCase() === 'true',
+      };
+    }
+
     return envConfig;
   }
 
@@ -311,6 +343,33 @@ class CurlRunnerCLI {
         };
       }
 
+      // Apply snapshot options
+      if (options.snapshot !== undefined) {
+        globalConfig.snapshot = {
+          ...globalConfig.snapshot,
+          enabled: options.snapshot as boolean,
+        };
+      }
+      if (options.snapshotUpdate !== undefined) {
+        globalConfig.snapshot = {
+          ...globalConfig.snapshot,
+          enabled: true,
+          updateMode: options.snapshotUpdate as 'none' | 'all' | 'failing',
+        };
+      }
+      if (options.snapshotDir !== undefined) {
+        globalConfig.snapshot = {
+          ...globalConfig.snapshot,
+          dir: options.snapshotDir as string,
+        };
+      }
+      if (options.snapshotCi !== undefined) {
+        globalConfig.snapshot = {
+          ...globalConfig.snapshot,
+          ci: options.snapshotCi as boolean,
+        };
+      }
+
       if (allRequests.length === 0) {
         this.logger.logError('No requests found in YAML files');
         process.exit(1);
@@ -450,6 +509,14 @@ class CurlRunnerCLI {
           options.watchClear = true;
         } else if (key === 'no-watch-clear') {
           options.watchClear = false;
+        } else if (key === 'snapshot') {
+          options.snapshot = true;
+        } else if (key === 'update-snapshots') {
+          options.snapshotUpdate = 'all';
+        } else if (key === 'update-failing') {
+          options.snapshotUpdate = 'failing';
+        } else if (key === 'ci-snapshot') {
+          options.snapshotCi = true;
         } else if (nextArg && !nextArg.startsWith('--')) {
           if (key === 'continue-on-error') {
             options.continueOnError = nextArg === 'true';
@@ -483,6 +550,8 @@ class CurlRunnerCLI {
             }
           } else if (key === 'watch-debounce') {
             options.watchDebounce = Number.parseInt(nextArg, 10);
+          } else if (key === 'snapshot-dir') {
+            options.snapshotDir = nextArg;
           } else {
             options[key] = nextArg;
           }
@@ -512,6 +581,12 @@ class CurlRunnerCLI {
             case 'w':
               options.watch = true;
               break;
+            case 's':
+              options.snapshot = true;
+              break;
+            case 'u':
+              options.snapshotUpdate = 'all';
+              break;
             case 'o': {
               // Handle -o flag for output file
               const outputArg = args[i + 1];
@@ -641,6 +716,7 @@ class CurlRunnerCLI {
       defaults: { ...base.defaults, ...override.defaults },
       ci: { ...base.ci, ...override.ci },
       watch: { ...base.watch, ...override.watch },
+      snapshot: { ...base.snapshot, ...override.snapshot },
     };
   }
 
@@ -733,6 +809,13 @@ ${this.logger.color('CI/CD OPTIONS:', 'yellow')}
   --fail-on <count>             Exit with code 1 if failures exceed this count
   --fail-on-percentage <pct>    Exit with code 1 if failure percentage exceeds this value
 
+${this.logger.color('SNAPSHOT OPTIONS:', 'yellow')}
+  -s, --snapshot                Enable snapshot testing
+  -u, --update-snapshots        Update all snapshots
+  --update-failing              Update only failing snapshots
+  --snapshot-dir <dir>          Custom snapshot directory (default: __snapshots__)
+  --ci-snapshot                 Fail if snapshot is missing (CI mode)
+
 ${this.logger.color('EXAMPLES:', 'yellow')}
   # Run all YAML files in current directory
   curl-runner
@@ -782,6 +865,15 @@ ${this.logger.color('EXAMPLES:', 'yellow')}
   # Watch with custom debounce
   curl-runner tests/ -w --watch-debounce 500
 
+  # Snapshot testing - save and compare responses
+  curl-runner api.yaml --snapshot
+
+  # Update all snapshots
+  curl-runner api.yaml -su
+
+  # CI mode - fail if snapshot missing
+  curl-runner api.yaml --snapshot --ci-snapshot
+
 ${this.logger.color('YAML STRUCTURE:', 'yellow')}
   Single request:
     request:

package/src/executor/request-executor.ts

@@ -1,4 +1,5 @@
 import { YamlParser } from '../parser/yaml';
+import { SnapshotManager } from '../snapshot/snapshot-manager';
 import type {
   ExecutionResult,
   ExecutionSummary,
@@ -8,7 +9,9 @@ import type {
   JsonValue,
   RequestConfig,
   ResponseStoreContext,
+  SnapshotConfig,
 } from '../types/config';
+import { evaluateCondition } from '../utils/condition-evaluator';
 import { CurlBuilder } from '../utils/curl-builder';
 import { Logger } from '../utils/logger';
 import { createStoreContext, extractStoreValues } from '../utils/response-store';
@@ -16,10 +19,12 @@ import { createStoreContext, extractStoreValues } from '../utils/response-store'
 export class RequestExecutor {
   private logger: Logger;
   private globalConfig: GlobalConfig;
+  private snapshotManager: SnapshotManager;
 
   constructor(globalConfig: GlobalConfig = {}) {
     this.globalConfig = globalConfig;
     this.logger = new Logger(globalConfig.output);
+    this.snapshotManager = new SnapshotManager(globalConfig.snapshot);
   }
 
   private mergeOutputConfig(config: RequestConfig): GlobalConfig['output'] {
@@ -30,6 +35,13 @@ export class RequestExecutor {
     };
   }
 
+  /**
+   * Gets the effective snapshot config for a request.
+   */
+  private getSnapshotConfig(config: RequestConfig): SnapshotConfig | null {
+    return SnapshotManager.mergeConfig(this.globalConfig.snapshot, config.snapshot);
+  }
+
   /**
    * Checks if a form field value is a file attachment.
    */
@@ -140,6 +152,25 @@ export class RequestExecutor {
           }
         }
 
+        // Snapshot testing
+        const snapshotConfig = this.getSnapshotConfig(config);
+        if (snapshotConfig && config.sourceFile) {
+          const snapshotResult = await this.snapshotManager.compareAndUpdate(
+            config.sourceFile,
+            config.name || 'Request',
+            executionResult,
+            snapshotConfig,
+          );
+          executionResult.snapshotResult = snapshotResult;
+
+          if (!snapshotResult.match && !snapshotResult.updated) {
+            executionResult.success = false;
+            if (!executionResult.error) {
+              executionResult.error = 'Snapshot mismatch';
+            }
+          }
+        }
+
         requestLogger.logRequestComplete(executionResult);
         return executionResult;
       }
@@ -486,6 +517,23 @@ export class RequestExecutor {
     for (let i = 0; i < requests.length; i++) {
       // Interpolate store variables before execution
       const interpolatedRequest = this.interpolateStoreVariables(requests[i], storeContext);
+
+      // Evaluate `when` condition if present
+      if (interpolatedRequest.when) {
+        const conditionResult = evaluateCondition(interpolatedRequest.when, storeContext);
+        if (!conditionResult.shouldRun) {
+          const skippedResult: ExecutionResult = {
+            request: interpolatedRequest,
+            success: true, // Skipped requests are not failures
+            skipped: true,
+            skipReason: conditionResult.reason,
+          };
+          results.push(skippedResult);
+          this.logger.logSkipped(interpolatedRequest, i + 1, conditionResult.reason);
+          continue;
+        }
+      }
+
       const result = await this.executeRequest(interpolatedRequest, i + 1);
       results.push(result);
 
@@ -588,13 +636,15 @@ export class RequestExecutor {
   }
 
   private createSummary(results: ExecutionResult[], duration: number): ExecutionSummary {
-    const successful = results.filter((r) => r.success).length;
+    const skipped = results.filter((r) => r.skipped).length;
+    const successful = results.filter((r) => r.success && !r.skipped).length;
     const failed = results.filter((r) => !r.success).length;
 
     return {
       total: results.length,
       successful,
       failed,
+      skipped,
       duration,
       results,
     };

package/src/snapshot/index.ts

@@ -0,0 +1,3 @@
+export { SnapshotDiffer } from './snapshot-differ';
+export { SnapshotFormatter, type SnapshotStats } from './snapshot-formatter';
+export { filterSnapshotBody, SnapshotManager } from './snapshot-manager';

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

@@ -0,0 +1,358 @@
+import { describe, expect, test } from 'bun:test';
+import type { Snapshot } from '../types/config';
+import { SnapshotDiffer } from './snapshot-differ';
+
+describe('SnapshotDiffer', () => {
+  describe('basic comparison', () => {
+    test('should match identical snapshots', () => {
+      const differ = new SnapshotDiffer({});
+      const snapshot: Snapshot = {
+        status: 200,
+        body: { id: 1, name: 'test' },
+        hash: 'abc123',
+        updatedAt: '2024-01-01',
+      };
+
+      const result = differ.compare(snapshot, snapshot);
+      expect(result.match).toBe(true);
+      expect(result.differences).toHaveLength(0);
+    });
+
+    test('should detect status changes', () => {
+      const differ = new SnapshotDiffer({});
+      const expected: Snapshot = { status: 200, hash: 'a', updatedAt: '' };
+      const received: Snapshot = { status: 201, hash: 'b', updatedAt: '' };
+
+      const result = differ.compare(expected, received);
+      expect(result.match).toBe(false);
+      expect(result.differences).toHaveLength(1);
+      expect(result.differences[0]).toEqual({
+        path: 'status',
+        expected: 200,
+        received: 201,
+        type: 'changed',
+      });
+    });
+
+    test('should detect body value changes', () => {
+      const differ = new SnapshotDiffer({});
+      const expected: Snapshot = {
+        body: { name: 'old' },
+        hash: 'a',
+        updatedAt: '',
+      };
+      const received: Snapshot = {
+        body: { name: 'new' },
+        hash: 'b',
+        updatedAt: '',
+      };
+
+      const result = differ.compare(expected, received);
+      expect(result.match).toBe(false);
+      expect(result.differences[0].path).toBe('body.name');
+      expect(result.differences[0].type).toBe('changed');
+    });
+
+    test('should detect added fields', () => {
+      const differ = new SnapshotDiffer({});
+      const expected: Snapshot = {
+        body: { id: 1 },
+        hash: 'a',
+        updatedAt: '',
+      };
+      const received: Snapshot = {
+        body: { id: 1, newField: 'value' },
+        hash: 'b',
+        updatedAt: '',
+      };
+
+      const result = differ.compare(expected, received);
+      expect(result.match).toBe(false);
+      expect(result.differences[0].path).toBe('body.newField');
+      expect(result.differences[0].type).toBe('added');
+    });
+
+    test('should detect removed fields', () => {
+      const differ = new SnapshotDiffer({});
+      const expected: Snapshot = {
+        body: { id: 1, oldField: 'value' },
+        hash: 'a',
+        updatedAt: '',
+      };
+      const received: Snapshot = {
+        body: { id: 1 },
+        hash: 'b',
+        updatedAt: '',
+      };
+
+      const result = differ.compare(expected, received);
+      expect(result.match).toBe(false);
+      expect(result.differences[0].path).toBe('body.oldField');
+      expect(result.differences[0].type).toBe('removed');
+    });
+  });
+
+  describe('array comparison', () => {
+    test('should compare array elements', () => {
+      const differ = new SnapshotDiffer({});
+      const expected: Snapshot = {
+        body: { items: [1, 2, 3] },
+        hash: 'a',
+        updatedAt: '',
+      };
+      const received: Snapshot = {
+        body: { items: [1, 2, 4] },
+        hash: 'b',
+        updatedAt: '',
+      };
+
+      const result = differ.compare(expected, received);
+      expect(result.match).toBe(false);
+      expect(result.differences[0].path).toBe('body.items[2]');
+    });
+
+    test('should detect added array elements', () => {
+      const differ = new SnapshotDiffer({});
+      const expected: Snapshot = {
+        body: { items: [1, 2] },
+        hash: 'a',
+        updatedAt: '',
+      };
+      const received: Snapshot = {
+        body: { items: [1, 2, 3] },
+        hash: 'b',
+        updatedAt: '',
+      };
+
+      const result = differ.compare(expected, received);
+      expect(result.match).toBe(false);
+      expect(result.differences[0].path).toBe('body.items[2]');
+      expect(result.differences[0].type).toBe('added');
+    });
+  });
+
+  describe('exclusions', () => {
+    test('should exclude exact paths', () => {
+      const differ = new SnapshotDiffer({
+        exclude: ['body.timestamp'],
+      });
+      const expected: Snapshot = {
+        body: { id: 1, timestamp: '2024-01-01' },
+        hash: 'a',
+        updatedAt: '',
+      };
+      const received: Snapshot = {
+        body: { id: 1, timestamp: '2024-12-31' },
+        hash: 'b',
+        updatedAt: '',
+      };
+
+      const result = differ.compare(expected, received);
+      expect(result.match).toBe(true);
+    });
+
+    test('should exclude wildcard paths (*.field)', () => {
+      const differ = new SnapshotDiffer({
+        exclude: ['*.createdAt'],
+      });
+      const expected: Snapshot = {
+        body: { user: { createdAt: '2024-01-01' }, post: { createdAt: '2024-01-01' } },
+        hash: 'a',
+        updatedAt: '',
+      };
+      const received: Snapshot = {
+        body: { user: { createdAt: '2024-12-31' }, post: { createdAt: '2024-12-31' } },
+        hash: 'b',
+        updatedAt: '',
+      };
+
+      const result = differ.compare(expected, received);
+      expect(result.match).toBe(true);
+    });
+
+    test('should exclude array wildcard paths (body[*].id)', () => {
+      const differ = new SnapshotDiffer({
+        exclude: ['body.items[*].id'],
+      });
+      const expected: Snapshot = {
+        body: {
+          items: [
+            { id: 1, name: 'a' },
+            { id: 2, name: 'b' },
+          ],
+        },
+        hash: 'a',
+        updatedAt: '',
+      };
+      const received: Snapshot = {
+        body: {
+          items: [
+            { id: 99, name: 'a' },
+            { id: 100, name: 'b' },
+          ],
+        },
+        hash: 'b',
+        updatedAt: '',
+      };
+
+      const result = differ.compare(expected, received);
+      expect(result.match).toBe(true);
+    });
+  });
+
+  describe('match rules', () => {
+    test('should accept any value with wildcard (*)', () => {
+      const differ = new SnapshotDiffer({
+        match: { 'body.id': '*' },
+      });
+      const expected: Snapshot = {
+        body: { id: 1 },
+        hash: 'a',
+        updatedAt: '',
+      };
+      const received: Snapshot = {
+        body: { id: 999 },
+        hash: 'b',
+        updatedAt: '',
+      };
+
+      const result = differ.compare(expected, received);
+      expect(result.match).toBe(true);
+    });
+
+    test('should match regex patterns', () => {
+      const differ = new SnapshotDiffer({
+        match: { 'body.version': 'regex:^v\\d+\\.\\d+' },
+      });
+      const expected: Snapshot = {
+        body: { version: 'v1.0.0' },
+        hash: 'a',
+        updatedAt: '',
+      };
+      const received: Snapshot = {
+        body: { version: 'v2.5.3' },
+        hash: 'b',
+        updatedAt: '',
+      };
+
+      const result = differ.compare(expected, received);
+      expect(result.match).toBe(true);
+    });
+
+    test('should fail on non-matching regex', () => {
+      const differ = new SnapshotDiffer({
+        match: { 'body.version': 'regex:^v\\d+\\.\\d+' },
+      });
+      const expected: Snapshot = {
+        body: { version: 'v1.0' },
+        hash: 'a',
+        updatedAt: '',
+      };
+      const received: Snapshot = {
+        body: { version: 'invalid' },
+        hash: 'b',
+        updatedAt: '',
+      };
+
+      const result = differ.compare(expected, received);
+      expect(result.match).toBe(false);
+    });
+  });
+
+  describe('type mismatches', () => {
+    test('should detect type changes', () => {
+      const differ = new SnapshotDiffer({});
+      const expected: Snapshot = {
+        body: { count: 42 },
+        hash: 'a',
+        updatedAt: '',
+      };
+      const received: Snapshot = {
+        body: { count: '42' },
+        hash: 'b',
+        updatedAt: '',
+      };
+
+      const result = differ.compare(expected, received);
+      expect(result.match).toBe(false);
+      expect(result.differences[0].type).toBe('type_mismatch');
+    });
+
+    test('should detect object to array change', () => {
+      const differ = new SnapshotDiffer({});
+      const expected: Snapshot = {
+        body: { data: { key: 'value' } },
+        hash: 'a',
+        updatedAt: '',
+      };
+      const received: Snapshot = {
+        body: { data: ['value'] },
+        hash: 'b',
+        updatedAt: '',
+      };
+
+      const result = differ.compare(expected, received);
+      expect(result.match).toBe(false);
+      expect(result.differences[0].type).toBe('type_mismatch');
+    });
+  });
+
+  describe('nested objects', () => {
+    test('should compare deeply nested values', () => {
+      const differ = new SnapshotDiffer({});
+      const expected: Snapshot = {
+        body: { level1: { level2: { level3: { value: 'old' } } } },
+        hash: 'a',
+        updatedAt: '',
+      };
+      const received: Snapshot = {
+        body: { level1: { level2: { level3: { value: 'new' } } } },
+        hash: 'b',
+        updatedAt: '',
+      };
+
+      const result = differ.compare(expected, received);
+      expect(result.match).toBe(false);
+      expect(result.differences[0].path).toBe('body.level1.level2.level3.value');
+    });
+  });
+
+  describe('header comparison', () => {
+    test('should compare headers', () => {
+      const differ = new SnapshotDiffer({});
+      const expected: Snapshot = {
+        headers: { 'content-type': 'application/json' },
+        hash: 'a',
+        updatedAt: '',
+      };
+      const received: Snapshot = {
+        headers: { 'content-type': 'text/html' },
+        hash: 'b',
+        updatedAt: '',
+      };
+
+      const result = differ.compare(expected, received);
+      expect(result.match).toBe(false);
+      expect(result.differences[0].path).toBe('headers.content-type');
+    });
+
+    test('should exclude headers', () => {
+      const differ = new SnapshotDiffer({
+        exclude: ['headers.date', 'headers.x-request-id'],
+      });
+      const expected: Snapshot = {
+        headers: { 'content-type': 'application/json', date: '2024-01-01' },
+        hash: 'a',
+        updatedAt: '',
+      };
+      const received: Snapshot = {
+        headers: { 'content-type': 'application/json', date: '2024-12-31' },
+        hash: 'b',
+        updatedAt: '',
+      };
+
+      const result = differ.compare(expected, received);
+      expect(result.match).toBe(true);
+    });
+  });
+});