CopilotKit/aimock

aimock – Mock infrastructure for AI‑application testing

What it is

• A Node‑only library (zero external dependencies) that runs a local HTTP server on a single port and pretends to be every major LLM, image/video/audio, vector‑store, and AI‑agent service you might call from your code.
• By pointing the SDKs you use (OpenAI, Anthropic, Gemini, Bedrock, Ollama, etc.) at the mock’s base URL, your application receives deterministic responses – no network calls, no API keys, no surprise billing.

Why it matters

• Makes unit‑ and integration‑tests for AI‑augmented apps reliable and fast.
• Supports record‑and‑replay: proxy real APIs once, save the exact JSON fixtures (including token usage, timings, streaming order), then replay them forever.
• Provides a rich set of testing knobs – chaos injection, model‑misbehaviour simulation, strict‑mode matching, and per‑request context routing – so you can verify error handling, rate‑limit retries, and edge‑case behaviours.

Core components

Component	What it mocks
LLMock	Chat, embeddings, realtime, video, image, TTS, transcription, moderation across 11 providers (OpenAI, Claude, Gemini, Bedrock, Azure, Vertex, Ollama, Cohere, OpenRouter, BytePlus, ElevenLabs, etc.)
MCPMock	Copilot‑Kit’s MCP tool‑execution protocol
A2AMock	Agent‑to‑agent streaming protocol (SSE)
AGUIMock	Agent‑to‑UI event streams for front‑end testing
VectorMock	Pinecone, Qdrant, ChromaDB‑compatible vector‑store endpoints
Services	Search (Tavily), rerank (Cohere), moderation (OpenAI)

Key features (as described in the README)

• Record & replay with timing‑aware playback and captured token usage/cost.
• Multi‑turn conversation fixtures that can match on turn index, tool calls, system messages, or custom predicates.
• Chaos testing: inject 500 errors, malformed JSON, disconnects, rate‑limit responses, or artificial latency.
• Model misbehaviour: force invalid arguments, schema violations, refusals, content‑filter blocks, etc., across many provider “wires”.
• Streaming physics: configure time‑to‑first‑token, tokens‑per‑second, jitter, and streaming usage chunks.
• WebSocket support for OpenAI Realtime, Responses, and Gemini Live.
• Metrics via Prometheus, Docker/Helm images for CI/CD, and Vitest/Jest plugins (useAimock()) for zero‑config test lifecycles.
• Fixture management: context‑based routing, strict‑mode overrides, request journal, OpenAPI catalog, and drift‑detection CI checks.

Typical usage

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`;
process.env.OPENAI_API_KEY = "mock"; // required by SDKs
// run your test suite …
await mock.stop();

You can also run the full suite via CLI:

npx @copilotkit/aimock --config aimock.json   # all mocks on one port

Or use the GitHub Action to spin up the server in CI and point your tests at it.

Who should use it

• Developers building AI‑driven products who need fast, repeatable tests without incurring cloud costs.
• Teams that want to validate error‑handling, rate‑limit back‑off, or custom tool‑call logic.
• Anyone needing to capture real API interactions once and replay them deterministically for offline development.

---

All details above come directly from the repository’s README; no additional features are inferred.