Java and Kotlin Integration Testing Open Source

Mock HTTP APIs
with real-world behavior

Mokksy is a mock Streaming HTTP and SSE server for deterministic Java and Kotlin integration testing. Test streaming APIs, retries, timeouts, and failure paths through real HTTP behavior. Testing AI providers? Use AI-Mocks, built on Mokksy.

🦊 Start with Mokksy 🤖 Explore AI-Mocks ⭐ Star on GitHub

Choose a product

Choose the testing layer you need

Mokksy is the core HTTP and SSE mock server. AI-Mocks adds provider-compatible AI testing on top of Mokksy.

Mokksy

Mock any HTTP or SSE dependency with controlled responses, streaming chunks, delays, failures, uploads, and request verification.

🦊 Start with Mokksy →

AI-Mocks

Test OpenAI, Anthropic, Gemini, Ollama, and A2A clients with provider-compatible behavior and no real API calls.

🤖 Start with AI-Mocks →

Mokksy: Simple POST

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

Mokksy: Multipart File Upload

 1val mokksy = Mokksy().start()
 2
 3mokksy.post {
  path("/upload")
  body {
      form {
          field("description", "Mokksy upload")
          file("avatar") {
              filename("photo.bin")
              contentType("application/octet-stream")
              bytes { it?.contentEquals(avatarFile.readBytes()) == true }
          }
      }
  }
15} respondsWith {
  body = "file-upload-ok"
17}
18
19val response = client.post(mokksy.baseUrl() + "/upload") {
  setBody(
      MultiPartFormDataContent(
          formData {
              append("description", "Mokksy upload")
              append(
                  "avatar",
                  avatarFile.readBytes(),
                  Headers.build {
                      append(
                          HttpHeaders.ContentDisposition,
                          """form-data; name="avatar"; filename="photo.bin"""",
                      )
                      append(HttpHeaders.ContentType, "application/octet-stream")
                  },
              )
          },
      ),
  )
38}
39
40check(response.status == HttpStatusCode.OK)
41println(response.bodyAsText()) // file-upload-ok

 1var mokksy = Mokksy.create().start();
 2var avatarFile = Files.createTempFile("ktor_logo", ".png");
 3
 4Files.writeString(avatarFile, "dummy-content");
 5
 6mokksy.post(spec -> spec
 7    .path("/upload")
 8    .body(body -> body.form(form -> form
 9        .field("description", "Ktor logo")
10        .file("image", file -> file
11            .filename("ktor_logo.png")
12            .contentType("image/png")
13            .bytesMatches(bytes -> {
14                try {
15                    return Arrays.equals(bytes, Files.readAllBytes(avatarFile));
16                } catch (IOException e) {
17                    throw new UncheckedIOException(e);
18                }
19            })
20        )
21    ))
22).respondsWith(rb -> rb.body("OK"));
23
24var boundary = "----TestBoundary" + System.nanoTime();
25var head = (
26    "--" + boundary + "\r\n"
27        + "Content-Disposition: form-data; name=\"description\"\r\n"
28        + "\r\n"
29        + "Ktor logo\r\n"
30        + "--" + boundary + "\r\n"
31        + "Content-Disposition: form-data; name=\"image\"; filename=\"ktor_logo.png\"\r\n"
32        + "Content-Type: image/png\r\n"
33        + "\r\n"
34).getBytes(StandardCharsets.UTF_8);
35var tail = ("\r\n--" + boundary + "--\r\n").getBytes(StandardCharsets.UTF_8);
36var body = new ByteArrayOutputStream();
37body.write(head);
38body.write(Files.readAllBytes(avatarFile));
39body.write(tail);
40
41var response = httpClient.send(
42    HttpRequest.newBuilder()
43        .uri(URI.create(mokksy.baseUrl() + "/upload"))
44        .header("Content-Type", "multipart/form-data; boundary=" + boundary)
45        .POST(HttpRequest.BodyPublishers.ofByteArray(body.toByteArray()))
46        .build(),
47    HttpResponse.BodyHandlers.ofString()
48);
49
50System.out.println(response.body()); // OK

Mokksy: 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

AI-Mocks: 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!

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 hanging streams — in a deterministic way.

Why Mokksy

Test real HTTP behavior
with confidence

Mock streaming APIs, slow responses, retries, partial failures, and connection-sensitive clients in repeatable Kotlin and Java integration tests.

True SSE and Streaming

Native Server-Sent Events and chunked response streams with controllable timing between chunks.

Request Matching

Match paths, headers, request bodies, multipart uploads, and typed payloads with a fluent Java API and Kotlin DSL.

Failure Simulation

Model slow responses, retry-after headers, rate limits, malformed payloads, hanging streams, and timeout paths.

Deterministic CI Tests

Run integration tests locally and in CI without depending on external service availability or network stability.

Framework Friendly

Use Mokksy with Spring Boot, Quarkus, Ktor, JVM SDK clients, and any HTTP client that accepts a base URL.

AI-Mocks Layer

Add provider-specific OpenAI, Anthropic, Gemini, Ollama, and A2A mocks when the dependency is an AI API.

Integration paths

Use the right layer for your dependency

HTTP integration testing with Mokksy

🧩 Ktor 🌱 Spring Boot 🚀 Quarkus

AI frameworks and providers with AI-Mocks

🌿 Spring AI ⛓🦜 LangChain4j ✦ OpenAI SDK 🤖 Anthropic SDK 🤖 Gemini 🧑‍🍳 Koog

Mock HTTP APIswith real-world behavior