aimock: Comprehensive Mocking for AI Application Testing

Introduction

aimock is a robust and comprehensive mocking infrastructure designed for testing AI applications. It allows developers to mock virtually everything an AI app interacts with, including LLM APIs, Multi-Cloud Protocol (MCP) tools, Agent-to-Agent (A2A) protocols, AG-UI event streams, vector databases, search services, and more. This powerful tool provides a unified solution in a single package, running on one port, with zero external dependencies, making it an ideal choice for creating deterministic and efficient testing environments for complex AI systems.

Installation

Getting started with aimock is straightforward. You can install it via npm:

npm install @copilotkit/aimock

Examples

Here's a quick example demonstrating how to use aimock to mock an OpenAI API call in your tests. Remember to set environment variables before importing or constructing your AI provider client to ensure your tests interact with aimock instead of real APIs.

// The class is still named `LLMock` for back-compat after the v1.7.0 package
// rename from `@copilotkit/llmock` to `@copilotkit/aimock`.
import { LLMock } from "@copilotkit/aimock";

const mock = new LLMock({ port: 0 });
mock.onMessage("hello", { content: "Hi there!" });
await mock.start();

// Set env BEFORE importing/constructing the OpenAI (or other provider) client.
// Many SDKs cache the base URL at construction time — if the client is built
// before these are set, it will talk to the real API (surprise bills) instead
// of aimock.
process.env.OPENAI_BASE_URL = `${mock.url}/v1`;
process.env.OPENAI_API_KEY = "mock"; // SDK requires a value, even when base URL is mocked

// ... run your tests ...

await mock.stop();

Why Use aimock?

aimock stands out as an essential tool for AI development and testing due to several key features:

• Comprehensive API Mocking: It supports a vast array of AI services, including OpenAI (Chat, Responses, Realtime), Claude, Gemini, Bedrock, Azure, Vertex AI, Ollama, Cohere, OpenRouter, ElevenLabs TTS, image generation, image editing, text-to-speech, audio transcription, video generation, and more.
• Record & Replay: Capture real API interactions and replay them deterministically. This feature includes timing-aware recording and replay, allowing for accurate simulation of response timings.
• Chaos Testing: Introduce controlled failures such as 500 errors, malformed JSON, or mid-stream disconnects to test the resilience of your AI application.
• Zero Dependencies: Built entirely from Node.js builtins, aimock is lightweight and avoids dependency conflicts.
• Multi-turn Conversations: Easily record and replay complex multi-turn interactions with tool calls.
• Framework Integrations: Seamlessly integrate with popular AI agent frameworks like LangChain, CrewAI, PydanticAI, LlamaIndex, Google ADK, and Microsoft Agent Framework.
• Developer-Friendly Tools: Offers a powerful CLI, Docker and Helm support for CI/CD, GitHub Action, and Vitest/Jest plugins for streamlined testing workflows.
• Drift Detection: Validate against real APIs daily to detect any unexpected changes.

Links

• GitHub Repository
• Official Documentation
• npm Package