openai-api-mock 0.1.33 → 0.2.0

package/README.md

@@ -14,6 +14,16 @@ The module supports the following OpenAI API endpoints:
 
 > This module is powering the sandbox mode for [Aipify](https://aipify.co).
 
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+- [Consistent Outputs for Testing](#consistent-outputs-for-testing)
+- [Intercepted URLs](#intercepted-urls)
+- [TypeScript Support](#typescript-support)
+- [Dependencies](#dependencies)
+- [License](#license)
+
 ## Installation
 
 You can install this module using npm as a dev dependency :
@@ -47,7 +57,9 @@ mockOpenAIResponse(true);
 mockOpenAIResponse(false, {
     includeErrors: true,    // Simulate random API errors
     latency: 1000,         // Add 1 second delay to responses
-    logRequests: true      // Log incoming requests to console
+    logRequests: true,     // Log incoming requests to console
+    seed: 12345,           // Seed for consistent/deterministic responses
+    useFixedResponses: true // Use predefined fixed response templates
 });
 ```
 
@@ -57,6 +69,8 @@ The function accepts two parameters:
   - `includeErrors` (boolean): When true, randomly simulates API errors
   - `latency` (number): Adds artificial delay to responses in milliseconds
   - `logRequests` (boolean): Logs incoming requests to console for debugging
+  - `seed` (number|string): Seed value for consistent/deterministic responses using faker.js
+  - `useFixedResponses` (boolean): Use predefined fixed response templates for completely consistent responses
 
 The function returns an object with control methods:
 ```js
@@ -68,6 +82,16 @@ console.log(mock.isActive);
 // Stop all mocks
 mock.stopMocking();
 
+// Seed management for consistent outputs
+mock.setSeed(12345);        // Set a new seed for deterministic responses
+mock.resetSeed();           // Reset to random responses
+
+// Template management
+const templates = mock.getResponseTemplates(); // Get available templates
+const customTemplate = mock.createResponseTemplate('SIMPLE_CHAT', {
+    choices: [{ message: { content: 'Custom response' } }]
+});
+
 // Add custom endpoint mock (uses api.openai.com as base url)
 mock.addCustomEndpoint('POST', '/v1/custom', (uri, body) => {
     return [200, { custom: 'response' }];
@@ -129,6 +153,74 @@ for await (const part of response) {
 }
 ```
 
+## Consistent Outputs for Testing
+
+The library provides several mechanisms to achieve consistent, deterministic outputs for reliable testing:
+
+### Seed-based Consistency
+
+Use seeds to ensure reproducible responses across test runs:
+
+```js
+// Set up mock with a fixed seed
+const mock = mockOpenAIResponse(true, { seed: 12345 });
+
+// Multiple calls will return identical responses
+const response1 = await openai.chat.completions.create({
+  model: 'gpt-3.5-turbo',
+  messages: [{ role: 'user', content: 'Hello' }]
+});
+
+const response2 = await openai.chat.completions.create({
+  model: 'gpt-3.5-turbo',
+  messages: [{ role: 'user', content: 'Hello' }]
+});
+
+// response1 and response2 will be identical
+console.log(JSON.stringify(response1) === JSON.stringify(response2)); // true
+```
+
+### Fixed Response Templates
+
+For maximum consistency, use predefined response templates:
+
+```js
+// Enable fixed responses
+const mock = mockOpenAIResponse(true, { useFixedResponses: true });
+
+const response = await openai.chat.completions.create({
+  model: 'gpt-3.5-turbo',
+  messages: [{ role: 'user', content: 'Any message' }]
+});
+
+// Will always return the same fixed response
+console.log(response.choices[0].message.content); 
+// "This is a consistent test response."
+```
+
+### Runtime Seed Management
+
+Change seeds during runtime for different test scenarios:
+
+```js
+const mock = mockOpenAIResponse(true);
+
+// Test scenario A
+mock.setSeed(12345);
+const responseA = await openai.chat.completions.create({...});
+
+// Test scenario B  
+mock.setSeed(54321);
+const responseB = await openai.chat.completions.create({...});
+
+// Reset to random behavior
+mock.resetSeed();
+const responseRandom = await openai.chat.completions.create({...});
+```
+
+For comprehensive examples and best practices, see [CONSISTENCY_EXAMPLES.md](./CONSISTENCY_EXAMPLES.md).
+```
+
 ## Intercepted URLs
 
 This module uses the `nock` library to intercept HTTP calls to the following OpenAI API endpoints:
@@ -146,9 +238,11 @@ import { mockOpenAIResponse, MockOptions } from 'openai-api-mock';
 
 // Configure with TypeScript types
 const options: MockOptions = {
-    includeErrors: true,    // Optional: simulate random API errors
-    latency: 1000,         // Optional: add 1 second delay
-    logRequests: true      // Optional: log requests to console
+    includeErrors: true,       // Optional: simulate random API errors
+    latency: 1000,            // Optional: add 1 second delay
+    logRequests: true,        // Optional: log requests to console
+    seed: 12345,              // Optional: seed for consistent responses
+    useFixedResponses: true   // Optional: use fixed response templates
 };
 
 const mock = mockOpenAIResponse(true, options);
@@ -156,6 +250,14 @@ const mock = mockOpenAIResponse(true, options);
 // TypeScript provides full type checking and autocompletion
 console.log(mock.isActive);  // boolean
 mock.stopMocking();         // function
+mock.setSeed(54321);        // function with type checking
+mock.resetSeed();           // function
+
+// Template methods with type safety
+const templates = mock.getResponseTemplates();  // Record<string, any>
+const customTemplate = mock.createResponseTemplate('SIMPLE_CHAT', {
+    choices: [{ message: { content: 'Custom content' } }]
+});
 
 // Custom endpoints with type safety
 mock.addCustomEndpoint('POST', '/v1/custom', (uri, body) => {

package/dist/index.cjs

@@ -2188,16 +2188,129 @@ function getImageResponce(requestBody) {
     data
   };
 }
+const RESPONSE_TEMPLATES = {
+  SIMPLE_CHAT: {
+    choices: [
+      {
+        finish_reason: "stop",
+        index: 0,
+        message: {
+          content: "This is a consistent test response.",
+          role: "assistant"
+        },
+        logprobs: null
+      }
+    ],
+    created: 1640995200,
+    id: "chatcmpl-test123456789",
+    model: "gpt-3.5-mock",
+    object: "chat.completion",
+    usage: {
+      completion_tokens: 10,
+      prompt_tokens: 20,
+      total_tokens: 30
+    }
+  },
+  FUNCTION_CALL: {
+    id: "chatcmpl-test123456789",
+    object: "chat.completion",
+    created: 1640995200,
+    model: "gpt-3.5-mock",
+    choices: [
+      {
+        index: 0,
+        message: {
+          role: "assistant",
+          content: null,
+          function_call: {
+            name: "test_function",
+            arguments: '{"param1": "test_value", "param2": 42}'
+          }
+        },
+        finish_reason: "function_call"
+      }
+    ],
+    usage: {
+      prompt_tokens: 81,
+      completion_tokens: 19,
+      total_tokens: 100
+    }
+  },
+  TOOL_CALL: {
+    id: "chatcmpl-test123456789",
+    object: "chat.completion",
+    created: 1640995200,
+    model: "gpt-3.5-mock",
+    choices: [
+      {
+        index: 0,
+        message: {
+          role: "assistant",
+          content: null,
+          tool_calls: [
+            {
+              id: "call_test123456789",
+              type: "function",
+              function: {
+                name: "test_function",
+                arguments: '{"param1": "test_value", "param2": 42}'
+              }
+            }
+          ]
+        },
+        finish_reason: "tool_calls"
+      }
+    ],
+    usage: {
+      prompt_tokens: 81,
+      completion_tokens: 19,
+      total_tokens: 100
+    }
+  },
+  IMAGE_GENERATION: {
+    created: 1640995200,
+    data: [
+      {
+        url: "https://example.com/test-image.png"
+      }
+    ]
+  }
+};
+function createResponseTemplate(templateType, overrides = {}) {
+  const template = RESPONSE_TEMPLATES[templateType];
+  if (!template) {
+    throw new Error(`Unknown template type: ${templateType}`);
+  }
+  return deepMerge(template, overrides);
+}
+function deepMerge(target, source) {
+  const result = { ...target };
+  for (const key in source) {
+    if (source[key] && typeof source[key] === "object" && !Array.isArray(source[key])) {
+      result[key] = deepMerge(result[key] || {}, source[key]);
+    } else {
+      result[key] = source[key];
+    }
+  }
+  return result;
+}
 const OPEN_AI_BASE_URL = "https://api.openai.com";
 const CHAT_COMPLETIONS_ENDPOINT = "/v1/chat/completions";
 const IMAGE_GENERATIONS_ENDPOINT = "/v1/images/generations";
-const customScopes = [];
 function mockOpenAIResponse(force = false, options = {}) {
   const {
     includeErrors = false,
     latency = 0,
-    logRequests = false
+    logRequests = false,
+    seed = null,
+    useFixedResponses = false
   } = options;
+  if (seed !== null) {
+    f.seed(seed);
+    if (logRequests) {
+      console.log(`[openai-api-mock] Using seed for consistent outputs: ${seed}`);
+    }
+  }
   const env = process.env.NODE_ENV || "development";
   if (env !== "development" && !force) {
     return { isActive: false, stopMocking };
@@ -2218,12 +2331,21 @@ function mockOpenAIResponse(force = false, options = {}) {
         const stream = createChatStream(requestBody);
         return [200, stream];
       }
+      if (useFixedResponses) {
+        if (requestBody.tools) {
+          return [200, createResponseTemplate("TOOL_CALL")];
+        } else if (requestBody.functions) {
+          return [200, createResponseTemplate("FUNCTION_CALL")];
+        } else {
+          return [200, createResponseTemplate("SIMPLE_CHAT")];
+        }
+      }
       return [200, getChatResponce(requestBody)];
     } catch (error) {
       console.error("[openai-api-mock] Error processing chat request:", error);
       return [500, { error: { message: "Internal server error in mock" } }];
     }
-  });
+  }).persist();
   nock(OPEN_AI_BASE_URL).post(IMAGE_GENERATIONS_ENDPOINT).delay(latency).reply(function(uri, requestBody) {
     if (logRequests) {
       console.log(`[openai-api-mock] Image request:`, JSON.stringify(requestBody, null, 2));
@@ -2235,16 +2357,52 @@ function mockOpenAIResponse(force = false, options = {}) {
       if (includeErrors && Math.random() < 0.05) {
         return [400, { error: { message: "Your request was rejected as a result of our safety system." } }];
       }
+      if (useFixedResponses) {
+        return [200, createResponseTemplate("IMAGE_GENERATION")];
+      }
       return [200, getImageResponce(requestBody)];
     } catch (error) {
       console.error("[openai-api-mock] Error processing image request:", error);
       return [500, { error: { message: "Internal server error in mock" } }];
     }
-  });
+  }).persist();
   nock.enableNetConnect((host) => host !== "api.openai.com");
   return {
     isActive: true,
     stopMocking,
+    /**
+     * Resets the faker seed to ensure consistent outputs for subsequent requests
+     * @param {number|string} newSeed - New seed value to use
+     */
+    setSeed(newSeed) {
+      f.seed(newSeed);
+      if (logRequests) {
+        console.log(`[openai-api-mock] Seed updated to: ${newSeed}`);
+      }
+    },
+    /**
+     * Resets faker to use random values (removes deterministic behavior)
+     */
+    resetSeed() {
+      f.seed();
+      if (logRequests) {
+        console.log(`[openai-api-mock] Seed reset - using random values`);
+      }
+    },
+    /**
+     * Get available response templates
+     * @returns {Object} Available response templates
+     */
+    getResponseTemplates() {
+      return RESPONSE_TEMPLATES;
+    },
+    /**
+     * Create a custom response template
+     * @param {string} templateType - Type of template to use
+     * @param {Object} overrides - Values to override in the template
+     * @returns {Object} Response template with overrides applied
+     */
+    createResponseTemplate,
     /**
      * Adds a custom endpoint mock
      * @param {string} method - HTTP method (e.g., 'GET', 'POST')
@@ -2253,14 +2411,12 @@ function mockOpenAIResponse(force = false, options = {}) {
      */
     addCustomEndpoint(method, path, handler) {
       const methodLower = method.toLowerCase();
-      const scope = nock(OPEN_AI_BASE_URL)[methodLower](path).reply(handler).persist();
-      customScopes.push(scope);
+      nock(OPEN_AI_BASE_URL)[methodLower](path).reply(handler).persist();
     }
   };
 }
 function stopMocking() {
   nock.cleanAll();
-  customScopes.forEach((scope) => scope.persist(false));
 }
 exports.mockOpenAIResponse = mockOpenAIResponse;
 exports.stopMocking = stopMocking;