Kotlin & JVM Integration Testing Open Source

Mock HTTP APIs
with real-world behavior

Mokksy is a mock HTTP server for integration testing — with true streaming, SSE, and failure simulation. Test your services as they behave in production.

Read the Docs View on GitHub

Simple POST

 1// Create mock server
 2val mokksy = MokksyServer()
 3mokksy.startSuspend()
 4
 5// Stub a POST endpoint
 6mokksy.post {
 7    path("/items")
 8    bodyContains("widget")
 9} respondsWith {
10    body = """{"id":"42"}"""
11    httpStatus = HttpStatusCode.Created
12}
13
14// Call the server
15val response = client.post(mokksy.baseUrl() + "/items") {
16    setBody("""{"name":"widget"}""")
17}
18println(response.bodyAsText()) // {"id":"42"}

 1// Create mock server
 2var mokksy = Mokksy.create();
 3mokksy.start();
 4
 5// Stub a POST endpoint
 6mokksy.post(spec -> spec.path("/items"))
 7    .respondsWith(builder -> builder
 8        .body("{\"id\":\"42\"}")
 9        .status(201)
10        .header("Location", "/items/42"));
11
12// Call the server - response streams as text/event-stream
13var response = httpClient.send(
14    HttpRequest.newBuilder()
15        .uri(URI.create(mokksy.baseUrl() + "/items"))
16        .POST(BodyPublishers.ofString("{\"name\":\"widget\"}"))
17        .build(),
18    BodyHandlers.ofString());
19System.out.println(response.body()); // {"id":"42"}

Streaming Response

 1// Create mock server
 2val mokksy = MokksyServer()
 3mokksy.startSuspend()
 4
 5// Stub a streaming endpoint
 6mokksy.get {
 7    path("/stream")
 8} respondsWithStream {
 9    flow = flow {
10        delay(100.milliseconds)
11        emit("Hello")
12        delay(50.milliseconds)
13        emit(" World")
14    }
15}
16
17// Call the server — response streams as text/event-stream
18val response = client.get(mokksy.baseUrl() + "/stream")
19println(response.bodyAsText()) // Hello World

 1// Create mock server
 2var mokksy = Mokksy.create().start();
 3
 4// Stub a streaming endpoint
 5mokksy.get(spec -> spec.path("/stream"))
 6    .respondsWithStream(builder -> builder
 7        .chunks(List.of("Hello", " World")));
 8
 9// Call the server — response streams as text/event-stream
10var response = httpClient.send(
11    HttpRequest.newBuilder()
12        .uri(URI.create(mokksy.baseUrl() + "/stream"))
13        .GET().build(),
14    BodyHandlers.ofString());
15System.out.println(response.body()); // Hello World

OpenAI Chat Completion

 1// Create a mock OpenAI server
 2val openai = MockOpenai()
 3
 4// Stub a chat completion
 5openai.completion {
 6    model = "gpt-4o-mini"
 7    userMessageContains("say 'Hello!'")
 8} responds {
 9    assistantContent = "Hello!"
10    finishReason = "stop"
11}
12
13// Use the official OpenAI SDK
14val client = OpenAIOkHttpClient.builder()
15    .apiKey("test-key")
16    .baseUrl(openai.baseUrl())
17    .build()
18
19val result = client.chat().completions().create(
20    ChatCompletionCreateParams.builder()
21        .model(ChatModel.GPT_4O_MINI)
22        .messages(listOf(
23            ChatCompletionMessageParam.ofUser(
24                ChatCompletionUserMessageParam.builder()
25                    .content("Just say 'Hello!'")
26                    .build())))
27        .build())
28
29println(result.choices().first().message().content()) // Hello!

 1// Create a mock OpenAI server
 2var mockOpenai = new MockOpenai();
 3
 4// Stub a chat completion
 5mockOpenai.completion(req -> {
 6    req.model("gpt-4o-mini");
 7    req.requestBodyContains("say 'Hello!'");
 8}).responds(response -> {
 9    response.assistantContent("Hello!");
10    response.finishReason("stop");
11});
12
13// Use the official OpenAI SDK
14var client = OpenAIOkHttpClient.builder()
15    .apiKey("test-key")
16    .baseUrl(mockOpenai.baseUrl())
17    .build();
18
19var result = client.chat().completions().create(
20    ChatCompletionCreateParams.builder()
21        .model(ChatModel.GPT_4O_MINI)
22        .messages(List.of(
23            ChatCompletionMessageParam.ofUser(
24                ChatCompletionUserMessageParam.builder()
25                    .content("Just say 'Hello!'")
26                    .build())))
27        .build());
28
29System.out.println(result.choices().get(0).message().content()); // Hello!

Tested with these LLM providers & frameworks

🤖 Anthropic ✦ OpenAI ♊️ Google Gemini 🦙 Ollama ⇄ Agent-to-Agent (A2A) ⛓🦜 LangChain4j 🌱 Spring AI

Why it matters

Catch failures before production

Unit tests don’t cover timeouts, retries, or streaming behavior. Mokksy lets you test real HTTP interactions — including slow responses, partial streams, and connection drops — in a deterministic way.

Why Mokksy

Everything WireMock isn't
for AI testing

Built for the unique challenges of testing LLM-powered applications — streaming, chunked responses, and non-determinism included.

True Streaming

Native Server-Side Events support. Simulate chunked token delivery just like real LLM APIs — with configurable delays between chunks.

Request Matching

Fluent Kotlin DSL for matching requests by model, prompt content, parameters, and headers. Return different responses per scenario.

Error Simulation

Mock rate limits, token exhaustion, network timeouts, and provider-specific error formats. Test unhappy paths reliably.

Latency Control

Add configurable delays at request level or between individual streaming chunks. Reproduce real-world performance conditions in tests.

Drop-in Compatible

Point your existing Anthropic, OpenAI, or Gemini SDK client at the mock server URL. No code changes needed in your application.

Kotest Ready

First-class Kotest integration with fluent assertions, concise test DSL, and full JUnit 5 support for Java teams.

Next-level mocking

Mokksy & AI-Mocks

Mokksy and AI-Mocks bring realistic behavior to HTTP and LLM API testing. They let you test streaming, delays, retries, and failures — not just static responses.

Mokksy

A Kotlin + Ktor mock HTTP server with streaming and Server-Side Events (SSE).

AI-Mocks

Built on Mokksy, providing ready-to-use mocks for OpenAI, Anthropic, Google Gemini, Ollama, and Agent-to-Agent APIs.

Mock HTTP APIswith real-world behavior