@machina.ai/openapi-contract-tester 2.1.0

package/dist/validators/openapi-validator.js

@@ -0,0 +1,349 @@
+/**
+ * OpenAPI Response Validator
+ *
+ * Validates API responses against OpenAPI specifications.
+ * Checks status codes, headers, content types, and response bodies.
+ *
+ * @module validators/openapi-validator
+ */
+import { validateSchema } from './schema-validator.js';
+/**
+ * Validates an API response against OpenAPI specification
+ *
+ * Checks:
+ * - Status code matches expected
+ * - Content-Type header is correct
+ * - Response body matches schema
+ *
+ * @param response - Actual API response
+ * @param endpoint - Expected endpoint definition
+ * @param expectedStatus - Expected status code
+ * @returns Validation result with detailed errors
+ *
+ * @example
+ * ```typescript
+ * const response = {
+ *   status: 200,
+ *   headers: { 'content-type': 'application/json' },
+ *   body: { id: 1, name: 'John' }
+ * };
+ *
+ * const result = validateResponse(response, endpoint, 200);
+ * if (!result.valid) {
+ *   console.error('Response validation failed:', result.errors);
+ * }
+ * ```
+ */
+export function validateResponse(response, endpoint, expectedStatus) {
+    const errors = [];
+    // 1. Validate status code
+    if (response.status !== expectedStatus) {
+        errors.push({
+            field: 'status',
+            message: `Expected status ${expectedStatus}, got ${response.status}`,
+            code: 'STATUS_MISMATCH',
+        });
+    }
+    // 2. Validate content-type (if response has body)
+    // AGNOSTIC: Accept any valid content type, don't force application/json
+    // The actual content type validation should be based on what the OpenAPI spec declares
+    if (response.body !== null && response.body !== undefined) {
+        const contentType = response.headers['content-type'] || response.headers['Content-Type'];
+        // Only warn if no content-type header is present (but don't error on non-JSON)
+        if (!contentType) {
+            errors.push({
+                field: 'content-type',
+                message: 'Response has body but no Content-Type header',
+                code: 'MISSING_CONTENT_TYPE',
+            });
+        }
+        // Note: We no longer reject non-JSON responses - APIs can return XML, text, etc.
+    }
+    // 3. Validate response body schema
+    const responseSchema = endpoint.responses[expectedStatus];
+    if (responseSchema && response.body !== null && response.body !== undefined) {
+        const schemaValidation = validateSchema(response.body, responseSchema);
+        if (!schemaValidation.valid) {
+            errors.push(...schemaValidation.errors.map((err) => ({
+                ...err,
+                field: `body.${err.field}`,
+            })));
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+/**
+ * Validates that response status code is in the 2xx success range
+ *
+ * @param status - HTTP status code
+ * @returns True if status is successful (200-299)
+ *
+ * @example
+ * ```typescript
+ * isSuccessStatus(200) // true
+ * isSuccessStatus(201) // true
+ * isSuccessStatus(204) // true
+ * isSuccessStatus(400) // false
+ * isSuccessStatus(500) // false
+ * ```
+ */
+export function isSuccessStatus(status) {
+    return status >= 200 && status < 300;
+}
+/**
+ * Validates that response status code is in the 4xx client error range
+ *
+ * @param status - HTTP status code
+ * @returns True if status is client error (400-499)
+ *
+ * @example
+ * ```typescript
+ * isClientError(400) // true
+ * isClientError(404) // true
+ * isClientError(422) // true
+ * isClientError(200) // false
+ * isClientError(500) // false
+ * ```
+ */
+export function isClientError(status) {
+    return status >= 400 && status < 500;
+}
+/**
+ * Validates that response status code is in the 5xx server error range
+ *
+ * @param status - HTTP status code
+ * @returns True if status is server error (500-599)
+ *
+ * @example
+ * ```typescript
+ * isServerError(500) // true
+ * isServerError(503) // true
+ * isServerError(200) // false
+ * isServerError(400) // false
+ * ```
+ */
+export function isServerError(status) {
+    return status >= 500 && status < 600;
+}
+/**
+ * Gets a human-readable description of an HTTP status code
+ *
+ * @param status - HTTP status code
+ * @returns Description of the status code
+ *
+ * @example
+ * ```typescript
+ * getStatusDescription(200) // "OK"
+ * getStatusDescription(404) // "Not Found"
+ * getStatusDescription(500) // "Internal Server Error"
+ * ```
+ */
+export function getStatusDescription(status) {
+    const descriptions = {
+        200: 'OK',
+        201: 'Created',
+        204: 'No Content',
+        400: 'Bad Request',
+        401: 'Unauthorized',
+        403: 'Forbidden',
+        404: 'Not Found',
+        422: 'Unprocessable Entity',
+        500: 'Internal Server Error',
+        502: 'Bad Gateway',
+        503: 'Service Unavailable',
+    };
+    return descriptions[status] || `HTTP ${status}`;
+}
+/**
+ * Validates test result against expected outcome
+ *
+ * Compares actual test result with expected values and generates
+ * detailed validation errors.
+ *
+ * @param testResult - Actual test execution result
+ * @param expectedStatus - Expected HTTP status code
+ * @param endpoint - Endpoint definition with response schemas
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * const testResult = {
+ *   id: 'test-1',
+ *   name: 'POST /users',
+ *   status: 'passed',
+ *   actualStatus: 201,
+ *   response: { id: 1, email: 'user@example.com' }
+ * };
+ *
+ * const result = validateTestResult(testResult, 201, endpoint);
+ * if (!result.valid) {
+ *   console.error('Test result validation failed');
+ * }
+ * ```
+ */
+export function validateTestResult(testResult, expectedStatus, endpoint) {
+    const errors = [];
+    // Check if test execution succeeded
+    if (testResult.status === 'failed' && testResult.error) {
+        errors.push({
+            field: 'execution',
+            message: `Test execution failed: ${testResult.error}`,
+            code: 'EXECUTION_FAILED',
+        });
+        return {
+            valid: false,
+            errors,
+        };
+    }
+    // Validate status code
+    if (testResult.actualStatus !== expectedStatus) {
+        errors.push({
+            field: 'status',
+            message: `Expected status ${expectedStatus}, got ${testResult.actualStatus}`,
+            code: 'STATUS_MISMATCH',
+        });
+    }
+    // Validate response schema if available
+    if (testResult.actualBody && endpoint.responses[expectedStatus]) {
+        const schemaValidation = validateSchema(testResult.actualBody, endpoint.responses[expectedStatus]);
+        if (!schemaValidation.valid) {
+            errors.push(...schemaValidation.errors.map((err) => ({
+                ...err,
+                field: `response.${err.field}`,
+            })));
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+/**
+ * Validates error response format
+ *
+ * Many APIs follow standard error response formats (RFC 7807, JSON:API, etc.).
+ * This function checks if error responses contain expected fields.
+ *
+ * @param response - Error response body
+ * @param expectedFormat - Expected error format
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * const errorResponse = {
+ *   error: 'Bad Request',
+ *   message: 'Email is required',
+ *   statusCode: 400
+ * };
+ *
+ * const result = validateErrorResponse(errorResponse, 'standard');
+ * ```
+ */
+export function validateErrorResponse(response, expectedFormat = 'standard') {
+    const errors = [];
+    if (typeof response !== 'object' || response === null) {
+        errors.push({
+            field: 'response',
+            message: 'Error response must be an object',
+            code: 'INVALID_FORMAT',
+        });
+        return {
+            valid: false,
+            errors,
+        };
+    }
+    const errorObj = response;
+    switch (expectedFormat) {
+        case 'standard':
+            // Common format: { error, message, statusCode }
+            if (!errorObj.message && !errorObj.error) {
+                errors.push({
+                    field: 'response',
+                    message: 'Error response should contain "message" or "error" field',
+                    code: 'MISSING_ERROR_FIELD',
+                });
+            }
+            break;
+        case 'rfc7807':
+            // RFC 7807 Problem Details: { type, title, status, detail, instance }
+            if (!errorObj.type && !errorObj.title) {
+                errors.push({
+                    field: 'response',
+                    message: 'RFC 7807 error response should contain "type" or "title" field',
+                    code: 'MISSING_RFC7807_FIELD',
+                });
+            }
+            break;
+        case 'jsonapi':
+            // JSON:API format: { errors: [{ status, title, detail }] }
+            if (!Array.isArray(errorObj.errors)) {
+                errors.push({
+                    field: 'response',
+                    message: 'JSON:API error response should contain "errors" array',
+                    code: 'MISSING_JSONAPI_ERRORS',
+                });
+            }
+            break;
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+/**
+ * Compares two response bodies for equality
+ *
+ * Performs deep comparison, useful for contract testing where
+ * exact response structure is expected.
+ *
+ * @param actual - Actual response body
+ * @param expected - Expected response body
+ * @returns True if responses match
+ *
+ * @example
+ * ```typescript
+ * const actual = { id: 1, name: 'John' };
+ * const expected = { id: 1, name: 'John' };
+ * const matches = compareResponses(actual, expected); // true
+ * ```
+ */
+export function compareResponses(actual, expected) {
+    return JSON.stringify(actual) === JSON.stringify(expected);
+}
+/**
+ * Extracts error details from a failed response
+ *
+ * Attempts to extract meaningful error information from various
+ * error response formats.
+ *
+ * @param response - Error response body
+ * @returns Extracted error details
+ *
+ * @example
+ * ```typescript
+ * const errorResponse = {
+ *   error: 'ValidationError',
+ *   message: 'Email is required',
+ *   statusCode: 400,
+ *   details: { field: 'email' }
+ * };
+ *
+ * const details = extractErrorDetails(errorResponse);
+ * // { message: 'Email is required', code: 'ValidationError', details: { field: 'email' } }
+ * ```
+ */
+export function extractErrorDetails(response) {
+    if (typeof response !== 'object' || response === null) {
+        return { message: String(response) };
+    }
+    const errorObj = response;
+    return {
+        message: (errorObj.message || errorObj.error || errorObj.title || errorObj.detail),
+        code: (errorObj.error || errorObj.type || errorObj.code),
+        details: errorObj.details || errorObj.errors || undefined,
+    };
+}
+//# sourceMappingURL=openapi-validator.js.map

package/dist/validators/openapi-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-validator.js","sourceRoot":"","sources":["../../src/validators/openapi-validator.ts"],"names":[],"mappings":"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"}

package/dist/validators/response-matcher.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Response Matcher
+ *
+ * Validates API responses using type-based matchers instead of exact values.
+ * Inspired by Pact matchers but implemented without dependencies.
+ *
+ * @module validators/response-matcher
+ */
+import type { ResponseMatcher } from '../types/index.js';
+/**
+ * Validates a value against a matcher
+ *
+ * @param value - Value to validate
+ * @param matcher - Matcher configuration
+ * @param fieldPath - Field path for error messages
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * const result = validateWithMatcher(
+ *   { id: 123, email: 'user@example.com' },
+ *   {
+ *     'id': { type: 'type', expectedType: 'number' },
+ *     'email': { type: 'regex', pattern: '^[^@]+@[^@]+$' }
+ *   }
+ * );
+ *
+ * if (!result.valid) {
+ *   console.error('Validation failed:', result.errors);
+ * }
+ * ```
+ */
+export declare function validateWithMatcher(value: unknown, matcher: ResponseMatcher, fieldPath: string): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Gets nested value from object using dot notation path
+ *
+ * @param obj - Object to get value from
+ * @param path - Dot notation path (e.g., "response.body.user.id")
+ * @returns Value at path or undefined
+ *
+ * @example
+ * ```typescript
+ * const obj = { response: { body: { user: { id: 123 } } } };
+ * const value = getNestedValue(obj, 'response.body.user.id'); // 123
+ * ```
+ */
+export declare function getNestedValue(obj: any, path: string): unknown;
+/**
+ * Validates response against matchers
+ *
+ * @param response - Response object to validate
+ * @param matchers - Matchers configuration (field path to matcher)
+ * @returns Validation result with errors
+ *
+ * @example
+ * ```typescript
+ * const response = {
+ *   body: {
+ *     id: 123,
+ *     email: 'user@example.com',
+ *     createdAt: '2024-01-01T00:00:00Z'
+ *   }
+ * };
+ *
+ * const matchers = {
+ *   'body.id': { type: 'type', expectedType: 'number' },
+ *   'body.email': { type: 'regex', pattern: '^[^@]+@[^@]+$' },
+ *   'body.createdAt': { type: 'regex', pattern: '^\\d{4}-\\d{2}-\\d{2}T' }
+ * };
+ *
+ * const result = validateResponse(response, matchers);
+ * if (!result.valid) {
+ *   console.error('Validation failed:', result.errors);
+ * }
+ * ```
+ */
+export declare function validateResponse(response: any, matchers: Record<string, ResponseMatcher>): {
+    valid: boolean;
+    errors: string[];
+};
+//# sourceMappingURL=response-matcher.d.ts.map

package/dist/validators/response-matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-matcher.d.ts","sourceRoot":"","sources":["../../src/validators/response-matcher.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,MAAM,GAChB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAoBpC;AA4ID;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAqB9D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,GAAG,EACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GACxC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAgBtC"}

package/dist/validators/response-matcher.js

@@ -0,0 +1,234 @@
+/**
+ * Response Matcher
+ *
+ * Validates API responses using type-based matchers instead of exact values.
+ * Inspired by Pact matchers but implemented without dependencies.
+ *
+ * @module validators/response-matcher
+ */
+/**
+ * Validates a value against a matcher
+ *
+ * @param value - Value to validate
+ * @param matcher - Matcher configuration
+ * @param fieldPath - Field path for error messages
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * const result = validateWithMatcher(
+ *   { id: 123, email: 'user@example.com' },
+ *   {
+ *     'id': { type: 'type', expectedType: 'number' },
+ *     'email': { type: 'regex', pattern: '^[^@]+@[^@]+$' }
+ *   }
+ * );
+ *
+ * if (!result.valid) {
+ *   console.error('Validation failed:', result.errors);
+ * }
+ * ```
+ */
+export function validateWithMatcher(value, matcher, fieldPath) {
+    switch (matcher.type) {
+        case 'type':
+            return validateType(value, matcher.expectedType, fieldPath);
+        case 'regex':
+            return validateRegex(value, matcher.pattern, fieldPath);
+        case 'range':
+            return validateRange(value, matcher.min, matcher.max, fieldPath);
+        case 'exists':
+            return validateExists(value, matcher.required, fieldPath);
+        default:
+            return {
+                valid: false,
+                error: `Unknown matcher type: ${matcher.type}`,
+            };
+    }
+}
+/**
+ * Validates type of a value
+ *
+ * @param value - Value to validate
+ * @param expectedType - Expected type
+ * @param fieldPath - Field path for error messages
+ * @returns Validation result
+ * @internal
+ */
+function validateType(value, expectedType, fieldPath) {
+    const actualType = getType(value);
+    if (actualType === expectedType) {
+        return { valid: true };
+    }
+    return {
+        valid: false,
+        error: `Field "${fieldPath}" expected type "${expectedType}" but got "${actualType}"`,
+    };
+}
+/**
+ * Validates value matches regex pattern
+ *
+ * @param value - Value to validate
+ * @param pattern - Regular expression pattern
+ * @param fieldPath - Field path for error messages
+ * @returns Validation result
+ * @internal
+ */
+function validateRegex(value, pattern, fieldPath) {
+    if (typeof value !== 'string') {
+        return {
+            valid: false,
+            error: `Field "${fieldPath}" must be a string for regex matching, got ${getType(value)}`,
+        };
+    }
+    const regex = new RegExp(pattern);
+    if (regex.test(value)) {
+        return { valid: true };
+    }
+    return {
+        valid: false,
+        error: `Field "${fieldPath}" value "${value}" does not match pattern "${pattern}"`,
+    };
+}
+/**
+ * Validates value is within range
+ *
+ * @param value - Value to validate
+ * @param min - Minimum value (optional)
+ * @param max - Maximum value (optional)
+ * @param fieldPath - Field path for error messages
+ * @returns Validation result
+ * @internal
+ */
+function validateRange(value, min, max, fieldPath) {
+    if (typeof value !== 'number') {
+        return {
+            valid: false,
+            error: `Field "${fieldPath}" must be a number for range validation, got ${getType(value)}`,
+        };
+    }
+    if (min !== undefined && value < min) {
+        return {
+            valid: false,
+            error: `Field "${fieldPath}" value ${value} is less than minimum ${min}`,
+        };
+    }
+    if (max !== undefined && value > max) {
+        return {
+            valid: false,
+            error: `Field "${fieldPath}" value ${value} is greater than maximum ${max}`,
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Validates field exists or not
+ *
+ * @param value - Value to validate
+ * @param required - Whether field is required
+ * @param fieldPath - Field path for error messages
+ * @returns Validation result
+ * @internal
+ */
+function validateExists(value, required, fieldPath) {
+    const exists = value !== undefined && value !== null;
+    if (required && !exists) {
+        return {
+            valid: false,
+            error: `Field "${fieldPath}" is required but was ${value === undefined ? 'undefined' : 'null'}`,
+        };
+    }
+    // required: false means optional — field may be present or absent, both are valid
+    return { valid: true };
+}
+/**
+ * Gets the type of a value as a string
+ *
+ * @param value - Value to get type of
+ * @returns Type string
+ * @internal
+ */
+function getType(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+/**
+ * Gets nested value from object using dot notation path
+ *
+ * @param obj - Object to get value from
+ * @param path - Dot notation path (e.g., "response.body.user.id")
+ * @returns Value at path or undefined
+ *
+ * @example
+ * ```typescript
+ * const obj = { response: { body: { user: { id: 123 } } } };
+ * const value = getNestedValue(obj, 'response.body.user.id'); // 123
+ * ```
+ */
+export function getNestedValue(obj, path) {
+    const parts = path.split('.');
+    let current = obj;
+    for (const part of parts) {
+        if (current === null || current === undefined) {
+            return undefined;
+        }
+        // Handle array indices
+        const arrayMatch = part.match(/^(.+)\[(\d+)\]$/);
+        if (arrayMatch) {
+            const key = arrayMatch[1];
+            const index = parseInt(arrayMatch[2], 10);
+            current = current[key]?.[index];
+        }
+        else {
+            current = current[part];
+        }
+    }
+    return current;
+}
+/**
+ * Validates response against matchers
+ *
+ * @param response - Response object to validate
+ * @param matchers - Matchers configuration (field path to matcher)
+ * @returns Validation result with errors
+ *
+ * @example
+ * ```typescript
+ * const response = {
+ *   body: {
+ *     id: 123,
+ *     email: 'user@example.com',
+ *     createdAt: '2024-01-01T00:00:00Z'
+ *   }
+ * };
+ *
+ * const matchers = {
+ *   'body.id': { type: 'type', expectedType: 'number' },
+ *   'body.email': { type: 'regex', pattern: '^[^@]+@[^@]+$' },
+ *   'body.createdAt': { type: 'regex', pattern: '^\\d{4}-\\d{2}-\\d{2}T' }
+ * };
+ *
+ * const result = validateResponse(response, matchers);
+ * if (!result.valid) {
+ *   console.error('Validation failed:', result.errors);
+ * }
+ * ```
+ */
+export function validateResponse(response, matchers) {
+    const errors = [];
+    for (const [path, matcher] of Object.entries(matchers)) {
+        const value = getNestedValue(response, path);
+        const result = validateWithMatcher(value, matcher, path);
+        if (!result.valid && result.error) {
+            errors.push(result.error);
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+//# sourceMappingURL=response-matcher.js.map

package/dist/validators/response-matcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-matcher.js","sourceRoot":"","sources":["../../src/validators/response-matcher.ts"],"names":[],"mappings":"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"}