llmock: OpenAI, Gemini, Anthropic API를 대체하는 결정론적 LLM 모킹 도구

섹션별 상세

llmock은 실제 포트에서 구동되는 HTTP 서버를 생성하여 Next.js, Mastra, LangGraph 등 모든 외부 프로세스가 접근할 수 있는 통합 테스트 환경을 제공한다. 이는 단순히 프로세스 내부의 호출을 가로채는 MSW와 달리, 여러 마이크로서비스나 워커가 동일한 모킹 엔드포인트를 공유할 수 있게 한다.

OpenAI, Claude, Gemini 등 주요 제공자의 고유한 SSE(Server-Sent Events) 형식을 완벽하게 지원하여 스트리밍 및 비스트리밍 모드 모두에서 실제 API와 동일한 데이터 흐름을 재현한다. 이를 통해 프론트엔드 UI의 스트리밍 렌더링이나 복잡한 에이전트 워크플로를 실제 비용 지출 없이 테스트할 수 있다.

JSON 피스처 파일을 통해 응답을 정의하며, 단순 텍스트 매칭뿐만 아니라 정규표현식이나 사용자 정의 조건(Predicate)을 활용한 라우팅이 가능하다. 시스템 프롬프트의 특정 플래그나 메시지 이력을 검사하여 에이전트의 상태에 따른 동적 응답을 설정할 수 있어 복잡한 멀티턴 대화 시나리오를 구성하기 용이하다.

json

{
  "fixtures": [
    {
      "match": {
        "userMessage": "stock price of AAPL"
      },
      "response": {
        "content": "The current stock price of Apple Inc. (AAPL) is $150.25."
      }
    }
  ]
}

특정 사용자 메시지에 대해 텍스트 응답을 반환하도록 설정하는 JSON 피스처 예시

실제 API와의 규격 불일치를 방지하기 위해 SDK 타입, 실제 API 응답, 모킹 출력을 삼각 비교하는 드리프트 감지(Drift Detection) 시스템을 운영한다. 매일 자동 실행되는 CI 테스트를 통해 제공자의 API 변경 사항을 즉각 감지하며, 규격이 어긋날 경우 테스트를 실패 처리하여 개발자가 잘못된 모킹 데이터로 인해 프로덕션 장애를 겪지 않도록 보호한다.

typescript

import { LLMock } from "@copilotkit/llmock";
const mock = new LLMock({ port: 5555 });

mock.loadFixtureDir("./fixtures/openai");
const url = await mock.start();

process.env.OPENAI_BASE_URL = `${url}/v1`;
process.env.OPENAI_API_KEY = "mock-key";

llmock 서버를 시작하고 환경 변수를 설정하여 API 호출을 가로채는 TypeScript 코드

OpenAI Realtime 및 Gemini Live와 같은 최신 WebSocket 기반 API를 지원하며, 오디오/비디오를 제외한 텍스트 및 도구 호출 경로에 대해 RFC 6455 프레임워크를 준수하는 통신을 제공한다. 또한 429(Rate Limit), 503(Service Unavailable) 등 일회성 에러 주입 기능을 통해 애플리케이션의 예외 처리 로직을 손쉽게 검증할 수 있다.

용어 해설

서버 전송 이벤트(SSE): — 서버가 클라이언트로 데이터를 실시간 스트리밍하기 위해 사용하는 단방향 통신 기술이다. LLM 응답이 생성되는 대로 한 글자씩 전달하는 방식의 핵심 메커니즘으로, llmock은 각 제공자의 고유한 SSE 형식을 완벽하게 재현한다.
결정론적(Deterministic): — 동일한 입력에 대해 항상 동일한 출력을 보장하는 성질이다. 실제 LLM API는 매번 응답이 달라져 테스트가 불안정해지지만, llmock은 미리 정의된 피스처를 통해 일관된 응답을 반환하여 테스트 신뢰도를 높인다.
피스처(Fixture): — 테스트를 위해 고정된 상태나 예상 응답을 정의한 데이터 파일이다. llmock에서는 JSON 형식을 사용하여 특정 사용자 메시지에 대해 어떤 텍스트나 도구 호출을 반환할지 미리 설정하는 용도로 사용된다.
드리프트 감지(Drift Detection): — 실제 API의 응답 규격과 모킹 도구의 응답 규격이 일치하는지 비교 검증하는 프로세스이다. API 업데이트로 인해 모킹 데이터가 낡아져 발생하는 테스트 오류를 방지하기 위해 SDK, 실제 API, 모킹 출력을 삼각 비교한다.
도구 호출(Tool Calling): — LLM이 외부 함수나 API를 실행하기 위해 구조화된 인자를 생성하는 기능이다. llmock은 에이전트 프레임워크가 즉시 실행할 수 있는 형태의 구조화된 JSON 인자를 포함한 도구 호출 응답을 모킹할 수 있다.

기술

TypeScript
OpenAI API
Claude API
Gemini API
WebSocket
SSE
Playwright

활용 사례

비용 없는 LLM 에이전트 E2E 테스트
결정론적인 스트리밍 UI 테스트
API 에러 처리(429, 503) 로직 검증
오프라인 환경에서의 LLM 앱 개발

언급된 리소스

GitHubllmock GitHub Repository

DemoCopilotKit Test Suite Examples

{ "fixtures": [ { "match": { "userMessage": "stock price of AAPL" }, "response": { "content": "The current stock price of Apple Inc. (AAPL) is $150.25." } } ] }

import { LLMock } from "@copilotkit/llmock"; const mock = new LLMock({ port: 5555 }); mock.loadFixtureDir("./fixtures/openai"); const url = await mock.start(); process.env.OPENAI_BASE_URL = `${url}/v1`; process.env.OPENAI_API_KEY = "mock-key";

llmock: OpenAI, Gemini, Anthropic API를 대체하는 결정론적 LLM 모킹 도구

섹션별 상세

용어 해설

기술

활용 사례

언급된 리소스

llmock: OpenAI, Gemini, Anthropic API를 대체하는 결정론적 LLM 모킹 도구

섹션별 상세

용어 해설

기술

활용 사례

언급된 리소스

관련 토론

댓글

관련 피드

관련 토론

댓글

관련 피드