Quick Start (5 minutes)

This guide gets you from an empty test to a local HTTP mock server. You will stub one endpoint, call it through a real HTTP client, and verify the response.

Add the test dependency

Add Mokksy to the test classpath. Most JVM projects should use mokksy-jvm as a test dependency.

build.gradle.kts
1dependencies {
2  testImplementation("dev.mokksy:mokksy-jvm:$latestVersion")
3}

pom.xml
1<dependency>
2  <groupId>dev.mokksy</groupId>
3  <artifactId>mokksy-jvm</artifactId>
4  <version>[LATEST_VERSION]</version>
5  <scope>test</scope>
6</dependency>

Stub and call an HTTP endpoint

Start Mokksy before the system under test creates its HTTP client, register the expected stub, then call the endpoint through a real HTTP client.

 1// before SUT starts
 2val mokksy = Mokksy(verbose = true).start()
 3
 4// SUT setup
 5val client = HttpClient {
 6  install(DefaultRequest) {
 7    url(mokksy.baseUrl())
 8  }
 9}
10
11// Given - before test
12mokksy.get {
13  path("/accounts/42")
14} respondsWith {
15  body = """{"id":"42","status":"active"}"""
16  httpStatus = HttpStatusCode.OK
17}
18
19// When
20val response = client.get("/accounts/42")
21
22// Then
23response.status shouldBe HttpStatusCode.OK
24response.bodyAsText() shouldBe """{"id":"42","status":"active"}"""

 1// before SUT starts
 2var mokksy = Mokksy.create().start();
 3
 4// Given - before test
 5mokksy.get(spec -> spec.path("/accounts/42"))
 6    .respondsWith(response -> response
 7        .body("{\"id\":\"42\",\"status\":\"active\"}")
 8        .status(200));
 9
10// When
11var httpClient = HttpClient.newHttpClient();
12var response = httpClient.send(
13    HttpRequest.newBuilder()
14        .uri(URI.create(mokksy.baseUrl() + "/accounts/42"))
15        .GET()
16        .build(),
17    HttpResponse.BodyHandlers.ofString()
18);
19
20// Then
21assertThat(response.statusCode()).isEqualTo(200);
22assertThat(response.body()).isEqualTo("{\"id\":\"42\",\"status\":\"active\"}");
23
24// after SUT stop (or never)
25mokksy.shutdown();

What this proves

Your test talks to a real HTTP server.
The external service is replaced by Mokksy.
The response is deterministic and can run in CI without API keys or network access.

Next, build a complete first integration test or test a streaming API.