README.md

aimock

aimock-demo.mp4

Mock infrastructure for AI application testing — LLM APIs, image generation, text-to-speech, transcription, video generation, MCP tools, A2A agents, AG-UI event streams, vector databases, search, rerank, and moderation. One package, one port, zero dependencies.

Quick Start

npm install @copilotkit/aimock

import { LLMock } from "@copilotkit/aimock";

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

process.env.OPENAI_BASE_URL = `${mock.url}/v1`;

// ... run your tests ...

await mock.stop();

The aimock Suite

aimock mocks everything your AI app talks to:

Tool	What it mocks	Docs
LLMock	OpenAI, Claude, Gemini, Bedrock, Azure, Vertex AI, Ollama, Cohere	Providers
MCPMock	MCP tools, resources, prompts with session management	MCP
A2AMock	Agent-to-agent protocol with SSE streaming	A2A
AGUIMock	AG-UI agent-to-UI event streams for frontend testing	AG-UI
VectorMock	Pinecone, Qdrant, ChromaDB compatible endpoints	Vector
Services	Tavily search, Cohere rerank, OpenAI moderation	Services

Run them all on one port with npx @copilotkit/aimock --config aimock.json, or use the programmatic API to compose exactly what you need.

Features

• Record & Replay — Proxy real APIs, save as fixtures, replay deterministically forever
• 11 LLM Providers — OpenAI, Claude, Gemini, Bedrock, Azure, Vertex AI, Ollama, Cohere — full streaming support
• Multimedia APIs — Image generation (DALL-E, Imagen), text-to-speech, audio transcription, video generation
• MCP / A2A / AG-UI / Vector — Mock every protocol your AI agents use
• Chaos Testing — 500 errors, malformed JSON, mid-stream disconnects at any probability
• Drift Detection — Daily CI validation against real APIs
• Streaming Physics — Configurable ttft, tps, and jitter
• WebSocket APIs — OpenAI Realtime, Responses WS, Gemini Live
• Prometheus Metrics — Request counts, latencies, fixture match rates
• Docker + Helm — Container image and Helm chart for CI/CD
• Vitest & Jest Plugins — Zero-config useAimock() with auto lifecycle and env patching
• Response Overrides — Control id, model, usage, finishReason in fixture responses
• Zero dependencies — Everything from Node.js builtins

GitHub Action

- uses: CopilotKit/aimock@v1
  with:
    fixtures: ./test/fixtures

- run: npm test
  env:
    OPENAI_BASE_URL: http://127.0.0.1:4010/v1

See the GitHub Action docs for all inputs and examples.

CLI

# LLM mocking only
npx @copilotkit/aimock -p 4010 -f ./fixtures

# Full suite from config
npx @copilotkit/aimock --config aimock.json

# Record mode: proxy to real APIs, save fixtures
npx @copilotkit/aimock --record --provider-openai https://api.openai.com

# Convert fixtures from other tools
npx @copilotkit/aimock convert vidaimock ./templates/ ./fixtures/
npx @copilotkit/aimock convert mockllm ./config.yaml ./fixtures/

# Docker
docker run -d -p 4010:4010 -v ./fixtures:/fixtures ghcr.io/copilotkit/aimock -f /fixtures

Framework Guides

Test your AI agents with aimock — no API keys, no network calls: LangChain · CrewAI · PydanticAI · LlamaIndex · Mastra · Google ADK

Switching from other tools?

Step-by-step migration guides: MSW · VidaiMock · mock-llm · piyook/llm-mock · Python mocks · openai-responses · Mokksy

Documentation

https://aimock.copilotkit.dev · Example fixtures

Real-World Usage

AG-UI uses aimock for its end-to-end test suite, verifying AI agent behavior across LLM providers with fixture-driven responses.

License

MIT