Testing Mock API

`startMockAnthropicServer()`

Signature

declare function startMockAnthropicServer(): Promise<MockServer>;

Returns

type MockServer = {
  port: number;
  server: http.Server;
  close: () => void;
  requests: Array<{ model: string; messages: unknown[]; stream: boolean; timestamp: string }>;
  onLog: (handler: (line: string) => void) => void;
};

Log shape

type MockLogEntry = {
  ts: string;
  type: "request" | "response" | "error" | "info";
  method?: string;
  url?: string;
  model?: string;
  stream?: boolean;
  messageCount?: number;
  userText?: string;
  systemPromptLength?: number;
  replyText?: string;
  requestBody?: unknown;
  error?: string;
  message?: string;
};

Example

import { startMockAnthropicServer } from "@sna-sdk/testing";

const mock = await startMockAnthropicServer();
process.env.ANTHROPIC_BASE_URL = `http://localhost:${mock.port}`;
process.env.ANTHROPIC_API_KEY = "sk-test";

mock.onLog((line) => {
  process.stdout.write(`${line}\n`);
});

try {
  // Anthropic-compatible API를 기대하는 코드를 실행합니다.
} finally {
  mock.close();
}

Behavior

OS가 고른 사용 가능한 port에서 시작합니다. 현재 구현은 fixed port option을 받지 않습니다.
Anthropic-compatible POST /v1/messages endpoint를 제공합니다.
CORS preflight request를 지원합니다.
Parsed request를 mock.requests에 기록합니다.
mock.onLog로 JSONL log line을 emit합니다.
일반 text는 마지막 user text를 뒤집은 값으로 응답합니다. Realistic한 답변이 아니라 deterministic test fixture입니다.
Tool이 선언되어 있고 최신 user text에 [tool:Name]이 있으면 해당 tool의 tool_use block을 반환하거나 stream합니다.
Streaming SSE와 non-streaming JSON response를 모두 지원합니다.

`startMockOpenAIServer(options?)`

Signature

declare function startMockOpenAIServer(options?: MockOpenAIOptions): Promise<MockOpenAIServer>;

Options

type MockOpenAIOptions = {
  models?: Array<{ id: string; owned_by?: string }>;
  responseText?: string | ((ctx: MockOpenAIResponseContext) => string);
  chunkSize?: number;
};

Example

import { startMockOpenAIServer } from "@sna-sdk/testing";

const mock = await startMockOpenAIServer({
  models: [{ id: "gpt-5.4", owned_by: "openai" }],
  responseText: ({ endpoint, userText }) => `${endpoint}: ${userText}`,
});

try {
  const res = await fetch(`${mock.url}/v1/responses`, {
    method: "POST",
    headers: { "Content-Type": "application/json", Authorization: "Bearer sk-test" },
    body: JSON.stringify({ model: "gpt-5.4", input: "hello" }),
  });
  console.log(await res.json());
  console.log(mock.requests[0]);
} finally {
  await mock.close();
}

Behavior

사용 가능한 local port에서 시작하고 mock.url을 노출합니다.
GET /v1/models, POST /v1/chat/completions, POST /v1/responses를 제공합니다.
authorization, model, stream flag, user text, system prompt 길이, raw request body를 포함해 parsed request를 기록합니다.
mock.onLog로 JSONL log line을 emit합니다.
Chat completions와 responses 모두 non-streaming JSON 및 streaming SSE를 지원합니다.
기본 응답은 마지막 user text를 뒤집은 값입니다. 고정 응답이나 요청별 응답은 responseText로 지정하십시오.

`runOneshot(cliArgs?)`

Signature

declare function runOneshot(cliArgs?: string[]): Promise<void>;

Use it when full interactive CLI harness를 띄우지 않고 mock Anthropic API에 연결된 Claude 실행만 검증하고 싶을 때 사용합니다.

runOneshot은 mock server를 시작하고, ANTHROPIC_BASE_URL을 그 server로 지정한 뒤, 전달된 CLI argument로 claude를 실행합니다. stdout/stderr를 capture하고 Claude의 exit code로 process를 종료합니다. CLAUDE_CONFIG_DIR은 .sna/mock-claude-oneshot을 사용합니다.

Written files:

File	Contents
`.sna/mock-claude-stdout.log`	Captured Claude stdout.
`.sna/mock-claude-stderr.log`	Captured Claude stderr.
`.sna/mock-claude-oneshot/`	Temporary Claude config directory.

Instance helpers

`generateInstanceName()`

고유한 test instance 이름을 만듭니다. 병렬 테스트에서 log/config directory 충돌을 피할 때 사용합니다.

`getInstancesDir()` / `getInstanceDir(name)`

testing CLI가 사용하는 .sna/instances storage path를 계산합니다. Path를 직접 하드코딩하지 말고 이 helper를 사용하십시오.

`listInstances()`

디스크에 저장된 test instance metadata 목록을 반환합니다. Debug UI나 cleanup script에서 사용합니다.

`readInstanceMeta(name)` / `writeInstanceMeta(name, meta)`

test instance metadata를 읽고 씁니다. 추가 상태를 instance에 연결해야 할 때 사용합니다.

`removeInstance(name)`

instance directory와 log를 제거합니다. 테스트 cleanup에서 사용합니다.

Testing Mock API

목차