Java quickstart: run JUnit tests without the API they call
In this quickstart, you build a small Java app whose JUnit 5 tests call a users
API with Java's HttpClient. You record those calls once, with the API up.
Then you run the same mvn test with the API switched off, and the tests still
pass.
You don't write any mock code, and the tests don't change. You don't need a Keploy account either: the recording stays in your repository.
Every output on this page comes from a real run of Keploy 3.9.4 on Linux.
Some of Keploy's and Maven's log lines are left out, long lines are trimmed
(…), and timestamps are removed.
Before you begin
You need:
-
Linux. Keploy's agent runs as root, so Keploy may ask for your
sudopassword. -
A JDK, version 17 or newer, such as Eclipse Temurin.
-
Maven 3.9 or newer.
-
Keploy. To install it, run:
source /dev/stdin <<<"$(curl -fsSL https://keploy.io/install.sh || echo 'echo Keploy installer download failed >&2; return 1')"For other ways to install it, see Installation.
Step 1: Create the sample app
-
Create a folder with a git repository and Maven's source folders:
mkdir billing-java && cd billing-java && git init
mkdir -p src/main/java/com/example src/test/java/com/example -
Save this as
UsersApi.java. It stands in for an external users API that your app calls:// A stand-in for an external users API. It listens on port 8085.
import com.sun.net.httpserver.HttpServer;
import java.net.InetSocketAddress;
import java.nio.charset.StandardCharsets;
import java.util.Map;
public class UsersApi {
static final Map<String, Map<String, String>> TABLES = Map.of(
"users", Map.of(
"1", "{\"id\":1,\"name\":\"Ada Lovelace\",\"plan\":\"pro\"}",
"2", "{\"id\":2,\"name\":\"Alan Turing\",\"plan\":\"free\"}"),
"plans", Map.of(
"free", "{\"price\":0}",
"pro", "{\"price\":20}"));
public static void main(String[] args) throws Exception {
HttpServer server = HttpServer.create(new InetSocketAddress("127.0.0.1", 8085), 0);
server.createContext("/", exchange -> {
String[] parts = exchange.getRequestURI().getPath().split("/");
String item = parts.length == 3
? TABLES.getOrDefault(parts[1], Map.of()).get(parts[2])
: null;
byte[] body = (item != null ? item : "{\"error\":\"not found\"}")
.getBytes(StandardCharsets.UTF_8);
exchange.getResponseHeaders().set("Content-Type", "application/json");
exchange.sendResponseHeaders(item != null ? 200 : 404, body.length);
exchange.getResponseBody().write(body);
exchange.close();
});
server.start();
}
} -
Save this as
pom.xml. It builds the app with Jackson for JSON, and tests it with JUnit 5:<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>billing</artifactId>
<version>1.0</version>
<properties>
<maven.compiler.release>17</maven.compiler.release>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<dependencies>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.18.2</version>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter</artifactId>
<version>5.11.4</version>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>3.5.2</version>
</plugin>
</plugins>
</build>
</project> -
Save this as
src/main/java/com/example/Billing.java. It's your app:monthlyBilllooks a user up in the users API and formats their bill:package com.example;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
// A small billing app. It calls an external users API.
public class Billing {
static final String USERS_API = "http://127.0.0.1:8085";
static final HttpClient HTTP = HttpClient.newHttpClient();
static final ObjectMapper JSON = new ObjectMapper();
static JsonNode get(String path) throws IOException, InterruptedException {
HttpRequest request = HttpRequest.newBuilder(URI.create(USERS_API + path)).build();
HttpResponse<String> response = HTTP.send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() != 200) {
throw new IOException("HTTP " + response.statusCode() + " for " + path);
}
return JSON.readTree(response.body());
}
// Look up a user and format their monthly bill.
public static String monthlyBill(int userId) throws IOException, InterruptedException {
JsonNode user = get("/users/" + userId);
String plan = user.get("plan").asText();
int price = plan.equals("pro") ? 20 : 0;
return user.get("name").asText() + " (" + plan + "): $" + price + "/month";
}
} -
Save this as
src/test/java/com/example/BillingTest.java. These are your tests:package com.example;
import static org.junit.jupiter.api.Assertions.assertEquals;
import org.junit.jupiter.api.Test;
class BillingTest {
@Test
void proUserBill() throws Exception {
assertEquals("Ada Lovelace (pro): $20/month", Billing.monthlyBill(1));
}
@Test
void freeUserBill() throws Exception {
assertEquals("Alan Turing (free): $0/month", Billing.monthlyBill(2));
}
} -
Keep Maven's build output out of git:
printf 'target/\n' > .gitignore
Step 2: Run the tests against the real API
-
In a second terminal, in the
billing-javafolder, start the users API:java UsersApi.java -
Back in the first terminal, run the tests:
mvn testThe first run downloads Jackson, JUnit and Maven's plugins. Then the tests run:
[INFO] Scanning for projects...
…
[INFO] -------------------------------------------------------
[INFO] T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.example.BillingTest
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.347 s -- in com.example.BillingTest
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------Run the tests this way once before you record, so Maven has downloaded what it needs. If Maven downloads during a record, Keploy records its downloads along with your app's calls.
Step 3: Record the calls
Run the same test command under keploy mock record:
keploy mock record --local -c "mvn test"
🐰 Keploy: INFO Recording mocks for your test command {"mock-set": "default", "program": "mvn", "args": 1}
🐰 Keploy: INFO pointing Java at a merged keploy truststore via JAVA_TOOL_OPTIONS (the JDK's cacerts is left untouched) {"truststore": "/tmp/keploy-java-truststore-1000.jks", …}
🐰 Keploy: INFO Starting Application : {"program": "mvn", "args": 1}
Picked up JAVA_TOOL_OPTIONS: -Djavax.net.ssl.trustStore=/tmp/keploy-java-truststore-1000.jks -Djavax.net.ssl.trustStorePassword=changeit
[INFO] Scanning for projects...
…
[INFO] T E S T S
[INFO] -------------------------------------------------------
Picked up JAVA_TOOL_OPTIONS: -Djavax.net.ssl.trustStore=/tmp/keploy-java-truststore-1000.jks -Djavax.net.ssl.trustStorePassword=changeit
[INFO] Running com.example.BillingTest
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.332 s -- in com.example.BillingTest
…
[INFO] BUILD SUCCESS
…
🐰 Keploy: INFO recorded mocks {"mocks": 2, "mock-set": "default"}
🐰 Keploy: INFO test command finished successfully {"phase": "record"}
--local keeps the recording in your repository, so you don't need a Keploy
account for this quickstart. Without --local, Keploy asks you to sign in
first.
Keploy sets JAVA_TOOL_OPTIONS for your test command. It points each JVM at a
truststore that holds your system's certificates and Keploy's own, so Keploy
can record calls to HTTPS services too. Your JDK's cacerts file doesn't
change. Each JVM prints the Picked up JAVA_TOOL_OPTIONS line as it starts:
first Maven's, then the one Surefire starts to run the tests.
Keploy wrote four files:
keploy.yml, the project's Keploy settings. It holds the app name and the test command.keploy/default/mocks.yaml, the recording: the 2 calls to the users API, each with its answer.keploy/default/last-record.yaml, the command Keploy recorded this set with.keploy mock statusreplays the recording with it.keploy/.gitignore, which keeps Keploy's temporary files out of git.
Here is the first call in mocks.yaml, trimmed:
kind: Http
name: mock-0
spec:
metadata:
destAddr: "[127.0.0.1]:8085"
operation: GET
type: HTTP_CLIENT
req:
method: GET
url: /users/1
header:
Connection: Upgrade, HTTP2-Settings
Host: 127.0.0.1:8085
Http2-Settings: AAEAAEAAAAIAAAAAAAMAAAAAAAQBAAAAAAUAAEAAAAYABgAA
Upgrade: h2c
User-Agent: Java-http-client/21.0.13.1
resp:
status_code: 200
header:
Content-Length: "43"
Content-Type: application/json
body: '{"id":1,"name":"Ada Lovelace","plan":"pro"}'
Java's HttpClient offers to switch a plain HTTP call to HTTP/2, with the
Upgrade: h2c header. The users API answers in HTTP/1.1, and Keploy records
the call as your app made it.
Step 4: Replay with the API off
-
Stop the users API with Ctrl+C in the second terminal.
-
Run the tests on their own. They fail, because nothing answers:
mvn test[INFO] Running com.example.BillingTest
[ERROR] Tests run: 2, Failures: 0, Errors: 2, Skipped: 0, Time elapsed: 0.277 s <<< FAILURE! -- in com.example.BillingTest
[ERROR] com.example.BillingTest.proUserBill -- Time elapsed: 0.258 s <<< ERROR!
java.net.ConnectException
…
[ERROR] com.example.BillingTest.freeUserBill -- Time elapsed: 0.005 s <<< ERROR!
java.net.ConnectException
…
[ERROR] Tests run: 2, Failures: 0, Errors: 2, Skipped: 0
…
[INFO] BUILD FAILURE
… -
Run them under
keploy mock replay:keploy mock replay --local -c "mvn test"🐰 Keploy: INFO Replaying mocks for your test command {"mock-set": "default", "program": "mvn", "args": 1, "on-miss": "fail"}
🐰 Keploy: INFO Starting Application : {"program": "mvn", "args": 1}
…
[INFO] Running com.example.BillingTest
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.317 s -- in com.example.BillingTest
…
[INFO] BUILD SUCCESS
…
🐰 Keploy: INFO mock replay summary {"loaded": 2, "consumed": 2, "missed": 0}
🐰 Keploy: INFO test command finished successfully {"phase": "replay"}
🐰 Keploy: INFO this replay ran with every dependency answered from the recording {"mock-set": "default", "served": 2}
The tests pass with no users API running. Keploy answered every call from the recording.
Step 5: Add a call the recording doesn't have
-
Add this method to
Billing.java, just before the class's last}. It calls a new endpoint,/plans/<plan>:// Look up the monthly price of a plan.
public static int planPrice(String plan) throws IOException, InterruptedException {
return get("/plans/" + plan).get("price").asInt();
} -
Add this test to
BillingTest.java, just before the class's last}:@Test
void proPlanPrice() throws Exception {
assertEquals(20, Billing.planPrice("pro"));
} -
Replay again, with the API still off:
keploy mock replay --local -c "mvn test"🐰 Keploy: INFO Replaying mocks for your test command {"mock-set": "default", "program": "mvn", "args": 1, "on-miss": "fail"}
🐰 Keploy: INFO Starting Application : {"program": "mvn", "args": 1}
…
[INFO] Running com.example.BillingTest
[ERROR] Tests run: 3, Failures: 0, Errors: 1, Skipped: 0, Time elapsed: 0.339 s <<< FAILURE! -- in com.example.BillingTest
[ERROR] com.example.BillingTest.proPlanPrice -- Time elapsed: 0.298 s <<< ERROR!
java.io.IOException: HTTP 502 for /plans/pro
…
[ERROR] Tests run: 3, Failures: 0, Errors: 1, Skipped: 0
…
[INFO] BUILD FAILURE
…
🐰 Keploy: ERROR error while running the app {"error": "exit status 1"}
🐰 Keploy: INFO mock replay summary {"loaded": 2, "consumed": 2, "missed": 1}
🐰 Keploy: WARN no recorded mock matched an outgoing call {"protocol": "HTTP", "call": "GET /{}/{}", …}
Mock mismatch: [HTTP] GET /plans/pro [path tag #…] → 127.0.0.1:8085
Hint: Only values drifted (path). If the change is expected, re-record the mock set with 'keploy mock record', or, with the dependency reachable, capture the new calls with 'keploy mock replay --on-miss record'. …
🐰 Keploy: INFO test command exited non-zero; mirroring its exit code {"phase": "replay", "exitCode": 1}
🐰 Keploy: INFO this replay did not prove the tests run with the dependencies off {"mock-set": "default", "reason": "the test command failed"}The recording has no
/plans/procall. Keploy doesn't send the call to the real API. It answers it with502 Bad Gateway, fails the run, names the call, and says what to do. The exit code is the test command's, so CI fails too. -
Start the users API again in the second terminal:
java UsersApi.java -
Record again, so the recording has the new call too:
keploy mock record --local -c "mvn test"🐰 Keploy: INFO Recording mocks for your test command {"mock-set": "default", "program": "mvn", "args": 1}
🐰 Keploy: INFO Starting Application : {"program": "mvn", "args": 1}
…
[INFO] Running com.example.BillingTest
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.391 s -- in com.example.BillingTest
…
[INFO] BUILD SUCCESS
…
🐰 Keploy: INFO recorded mocks {"mocks": 3, "mock-set": "default"}
🐰 Keploy: INFO test command finished successfully {"phase": "record"}A new record replaces the recording, so it always matches the tests you have now.
-
Stop the users API with Ctrl+C, and replay:
keploy mock replay --local -c "mvn test"🐰 Keploy: INFO Replaying mocks for your test command {"mock-set": "default", "program": "mvn", "args": 1, "on-miss": "fail"}
🐰 Keploy: INFO Starting Application : {"program": "mvn", "args": 1}
…
[INFO] Running com.example.BillingTest
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.272 s -- in com.example.BillingTest
…
[INFO] BUILD SUCCESS
…
🐰 Keploy: INFO mock replay summary {"loaded": 3, "consumed": 3, "missed": 0}
🐰 Keploy: INFO test command finished successfully {"phase": "replay"}
🐰 Keploy: INFO this replay ran with every dependency answered from the recording {"mock-set": "default", "served": 3}All three tests pass from the recording, with no users API running.
Step 6: See a failing test fail the run
-
In
BillingTest.java, change$20/monthto$25/month. -
Replay, and print the exit code:
keploy mock replay --local -c "mvn test"
echo "exit code: $?"🐰 Keploy: INFO Replaying mocks for your test command {"mock-set": "default", "program": "mvn", "args": 1, "on-miss": "fail"}
🐰 Keploy: INFO Starting Application : {"program": "mvn", "args": 1}
…
[INFO] Running com.example.BillingTest
[ERROR] Tests run: 3, Failures: 1, Errors: 0, Skipped: 0, Time elapsed: 0.320 s <<< FAILURE! -- in com.example.BillingTest
[ERROR] com.example.BillingTest.proUserBill -- Time elapsed: 0.012 s <<< FAILURE!
org.opentest4j.AssertionFailedError: expected: <Ada Lovelace (pro): $25/month> but was: <Ada Lovelace (pro): $20/month>
…
[ERROR] Tests run: 3, Failures: 1, Errors: 0, Skipped: 0
…
[INFO] BUILD FAILURE
…
🐰 Keploy: ERROR error while running the app {"error": "exit status 1"}
🐰 Keploy: INFO mock replay summary {"loaded": 3, "consumed": 3, "missed": 0}
🐰 Keploy: INFO test command exited non-zero; mirroring its exit code {"phase": "replay", "exitCode": 1}
🐰 Keploy: INFO this replay did not prove the tests run with the dependencies off {"mock-set": "default", "reason": "the test command failed"}
exit code: 1JUnit shows the value it expected and the value it got. The summary shows no missed call, so every call was answered from the recording, and the failure is in the code or the test. Keploy exits with the test command's exit code, so a failing test fails your CI job.
-
Change
$25/monthback to$20/month.
Step 7: Commit the recording
Commit keploy.yml and the keploy/ folder with your code:
git add . && git status --short
A .gitignore
A UsersApi.java
A keploy.yml
A keploy/.gitignore
A keploy/default/last-record.yaml
A keploy/default/mocks.yaml
A pom.xml
A src/main/java/com/example/Billing.java
A src/test/java/com/example/BillingTest.java
keploy/default/ holds the recording (mocks.yaml) and the record command
(last-record.yaml). The other files in keploy/default/, such as
last-replay.yaml, are run files from this machine's last replay:
keploy/.gitignore keeps them out of git, so git add . skips them.
Commit what git add staged:
git commit -m "Add billing tests and their Keploy recording"
Now anyone can replay the tests on a clone with no users API, and CI can too.
The replay gives mvn test no network, so Maven must already have every plugin
and library the build uses. On a machine whose Maven repository
(~/.m2/repository) doesn't have them yet, such as a fresh CI runner, fetch
them first with a run that starts Surefire but matches no test:
mvn -B test -Dtest='*#none' -Dsurefire.failIfNoSpecifiedTests=false
keploy mock replay --local -c "mvn test"
Without that first command, the replay ends in BUILD FAILURE and Keploy
reports DNS misses for repo.maven.apache.org. Its hint says to re-record, but
a record would capture Maven's downloads: fetch them before the replay instead.
mvn dependency:go-offline isn't enough on its own, because Surefire fetches
the rest only when it starts to run tests.
Clean up
Step 5 stopped the users API, so nothing is left running. Delete the
billing-java folder when you no longer need it.
Next steps
- Node.js quickstart: the same loop with Jest and
fetch. - Python quickstart: the same loop with
pytest, and--on-miss recordto add a new call. - Go quickstart: a sample with PostgreSQL and an HTTP API, and a check of each test on its own.
- Run the replay in CI, and share recordings with your team.
With a Keploy account, recordings live in Keploy Cloud, and the repository
keeps only
keploy.ymlandkeploy.lock. - keploy.yml and keploy.lock: what to commit when your recordings live in Keploy Cloud.
- Learn every option of
keploy mock.