JAVA-220 · Lesson 7 of 12 · 23 min
Integration tests
▶ Video coming soon A video version of this lesson is on the way.
On Thursday, October 28, Hamza's unit tests were all green, and PartsDesk still crashed. Kofi had saved the parts list with a part named "Brake pads, road", the comma split the line in two, and the next load failed. Every unit test had passed because each one tested a class alone, with doubles standing in for files. "Unit tests tell you each part works," Ingrid said. "Integration tests tell you the parts work together, with the real file, the real database, the real network. You need both."
What integration tests check
An integration test exercises two or more real parts of a system together, usually including something outside the program's own memory: the file system, a database, a web service, another module. It checks the seams between parts, where unit tests cannot look: formats, encodings, SQL, configuration, the real behavior of a library. Integration tests are slower than unit tests, need more setup and fail for more reasons, which is why the test pyramid has fewer of them, but they catch a whole class of bugs that unit tests structurally cannot.
| Seam | What can go wrong | Integration test |
|---|---|---|
| File format | Commas, quotes, line endings or character encoding break saving and loading | Save real data to a temporary file and load it back |
| Database | SQL syntax, column types, constraints, transactions | Run the repository against a real database engine |
| HTTP service | URLs, status codes, JSON field names, timeouts | Call a local test server or a recorded response |
| Modules | Two modules disagree about a shared type or rule | Test partsdesk and core together through their public API |
| Configuration | A missing property or wrong path at start-up | Start the program with a test configuration file |
The comma bug
The fastest way to understand the bug is to reproduce it with the real file code. The test below saves parts to a temporary file and loads them back, a round-trip test, with the part name that broke PartsDesk. The naive format writes fields separated by commas and splits on commas when reading.
import java.io.IOException;
import java.nio.file.*;
import java.util.*;
public class Main {
record Part(String code, String name, int count) { }
static void save(Path file, List<Part> parts) throws IOException {
List<String> lines = new ArrayList<>();
for (Part p : parts) lines.add(p.code() + "," + p.name() + "," + p.count());
Files.write(file, lines);
}
static List<Part> load(Path file) throws IOException {
List<Part> parts = new ArrayList<>();
for (String line : Files.readAllLines(file)) {
String[] f = line.split(",");
parts.add(new Part(f[0], f[1], Integer.parseInt(f[2].trim())));
}
return parts;
}
public static void main(String[] args) throws IOException {
Path dir = Files.createTempDirectory("it");
Path file = dir.resolve("parts.csv");
List<Part> before = List.of(new Part("B-11", "Brake pads, road", 32), new Part("BELL", "Bell", 9));
try {
save(file, before);
List<Part> after = load(file);
System.out.println("Round trip equal: " + before.equals(after));
} catch (NumberFormatException e) {
System.out.println("Load failed: " + e.getMessage());
} finally {
Files.deleteIfExists(file);
Files.deleteIfExists(dir);
}
}
}Load failed: For input string: "road"
What this code does
The save writes B-11, Brake pads, road, 32 as one line, so the load sees four fields and tries to read the word road as the count. Integer.parseInt throws a NumberFormatException, and the test reports the same failure Kofi saw. No unit test with a fake file could find this, because the bug is in how the real text format and the real splitting interact.
The fix is to use a format that can hold any text. Hamza chose to put each name in double quotes and to double any quote inside it, the same rule spreadsheet programs use for CSV files. The same round-trip test, unchanged except for the format code, now proves the fix, and it stays in the build forever as a regression test.
import java.io.IOException;
import java.nio.file.*;
import java.util.*;
public class Main {
record Part(String code, String name, int count) { }
static String quote(String s) { return "\"" + s.replace("\"", "\"\"") + "\""; }
static List<String> fields(String line) {
List<String> out = new ArrayList<>();
StringBuilder cur = new StringBuilder();
boolean inQuotes = false;
for (int i = 0; i < line.length(); i++) {
char c = line.charAt(i);
if (inQuotes) {
if (c == '"' && i + 1 < line.length() && line.charAt(i + 1) == '"') { cur.append('"'); i++; }
else if (c == '"') inQuotes = false;
else cur.append(c);
} else if (c == '"') inQuotes = true;
else if (c == ',') { out.add(cur.toString()); cur.setLength(0); }
else cur.append(c);
}
out.add(cur.toString());
return out;
}
static void save(Path file, List<Part> parts) throws IOException {
List<String> lines = new ArrayList<>();
for (Part p : parts) lines.add(p.code() + "," + quote(p.name()) + "," + p.count());
Files.write(file, lines);
}
static List<Part> load(Path file) throws IOException {
List<Part> parts = new ArrayList<>();
for (String line : Files.readAllLines(file)) {
List<String> f = fields(line);
parts.add(new Part(f.get(0), f.get(1), Integer.parseInt(f.get(2))));
}
return parts;
}
public static void main(String[] args) throws IOException {
Path dir = Files.createTempDirectory("it");
Path file = dir.resolve("parts.csv");
List<Part> before = List.of(new Part("B-11", "Brake pads, road", 32),
new Part("SADDLE-K", "Kids' saddle, 8\" wide", 3), new Part("BELL", "Bell", 9));
try {
save(file, before);
System.out.println("File line 2: " + Files.readAllLines(file).get(1));
System.out.println("Round trip equal: " + before.equals(load(file)));
} finally {
Files.deleteIfExists(file);
Files.deleteIfExists(dir);
}
}
}File line 2: SADDLE-K,"Kids' saddle, 8"" wide",3 Round trip equal: true
What this code does
Each name is written inside double quotes with any quote inside it doubled, and the reader walks the line character by character, ignoring commas inside quotes. The test adds a harder case, a name containing both a comma and a quote mark, and prints that line of the file to show the escaping. The loaded list equals the saved one, so the round trip passes for all three parts.
In production, Hamza will use a CSV library rather than his own parser, and the same round-trip test will protect that choice too: if a future library upgrade changes how quotes are handled, the test fails before Kofi's file does.
Testing with a real server
The supplier offered a small web service for prices, so Hamza's PriceList needed an implementation that calls it over HTTP. An integration test for that code must make real HTTP requests, but not to the real supplier, whose prices change and whose service may be down. The JDK includes a small HTTP server, com.sun.net.httpserver, which a test can start on the local machine in milliseconds, with a free port chosen by the operating system.
import com.sun.net.httpserver.HttpServer;
import java.io.IOException;
import java.net.*;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
public class Main {
static long fetchPrice(HttpClient client, URI base, String code) throws IOException, InterruptedException {
HttpRequest req = HttpRequest.newBuilder(base.resolve("/price/" + code)).GET().build();
HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
if (res.statusCode() == 404) throw new IllegalArgumentException("unknown part " + code);
if (res.statusCode() != 200) throw new IOException("supplier returned " + res.statusCode());
return Long.parseLong(res.body().trim());
}
public static void main(String[] args) throws Exception {
HttpServer server = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0);
server.createContext("/price/", exchange -> {
String code = exchange.getRequestURI().getPath().substring("/price/".length());
byte[] body = (code.equals("TUBE-700x25") ? "450" : "").getBytes(StandardCharsets.UTF_8);
exchange.sendResponseHeaders(body.length > 0 ? 200 : 404, body.length > 0 ? body.length : -1);
exchange.getResponseBody().write(body);
exchange.close();
});
server.start();
try {
URI base = URI.create("http://127.0.0.1:" + server.getAddress().getPort());
HttpClient client = HttpClient.newHttpClient();
System.out.println("TUBE-700x25 costs " + fetchPrice(client, base, "TUBE-700x25") + " cents");
try {
fetchPrice(client, base, "UNICORN");
} catch (IllegalArgumentException e) {
System.out.println("Rejected: " + e.getMessage());
}
} finally {
server.stop(0);
}
}
}TUBE-700x25 costs 450 cents Rejected: unknown part UNICORN
What this code does
The test starts a real HTTP server on port 0, which asks the operating system for any free port, and serves a price for the tube and a 404 status for anything else. fetchPrice then makes real requests with Java's HttpClient, so URL building, status codes and parsing are all tested for real. The server is stopped in a finally block, and the random port is never printed, which keeps the output repeatable.
Libraries such as WireMock and MockWebServer make this kind of test easier, with recorded responses, request matching and simulated delays. The idea is the same: real HTTP on the local machine, controlled answers, no dependence on a service the team does not run.
Databases in integration tests
When PartsDesk moves to a database next term, its repository code will need tests against a real database engine. There are two common approaches. An in-memory database such as H2 starts inside the test JVM in milliseconds, but its SQL dialect differs from PostgreSQL's in small ways, so a query can pass in tests and fail in production. Testcontainers is a library that starts a real database, such as PostgreSQL, in a Docker container for the test run and removes it afterwards; it is slower to start but tests the real thing. Most teams now prefer Testcontainers for anything beyond trivial SQL.
@Testcontainers
class PartRepositoryIT {
@Container
static PostgreSQLContainer<?> db = new PostgreSQLContainer<>("postgres:17");
PartRepository repo;
@BeforeEach
void connect() throws SQLException {
repo = new PartRepository(DriverManager.getConnection(db.getJdbcUrl(), db.getUsername(), db.getPassword()));
repo.createSchema();
repo.deleteAll();
}
@Test
void savedPartCanBeFoundByCode() {
repo.save(new Part("B-11", "Brake pads, road", 32, 15));
assertEquals(32, repo.findByCode("B-11").orElseThrow().count());
}
}What this code does
The static @Container field starts one PostgreSQL container for the whole test class, which Testcontainers stops at the end. Each test connects with the container's URL and credentials and empties the table first, so tests do not see each other's rows. The class name ends in IT, a common convention that keeps slow integration tests separate from unit tests.
Keeping integration tests separate
Because integration tests are slower and need more setup, builds usually run them separately from unit tests. Developers run the fast unit tests constantly and the integration tests before pushing, and the CI server runs both. In Maven, the Surefire plugin runs unit tests in the test phase and the Failsafe plugin runs classes named *IT in the integration-test phase. In Gradle, the JVM Test Suite plugin defines a second source set, src/integrationTest/java, with its own task.
testing {
suites {
val test by getting(JvmTestSuite::class) {
useJUnitJupiter("6.1.3")
}
register<JvmTestSuite>("integrationTest") {
dependencies {
implementation(project())
}
targets {
all {
testTask.configure { shouldRunAfter(tasks.test) }
}
}
}
}
}
tasks.named("check") {
dependsOn(testing.suites.named("integrationTest"))
}What this code does
The testing block configures the normal test suite to use JUnit Jupiter and registers a second suite called integrationTest, with its own source folder src/integrationTest/java and its own task. The dependency on project() lets the integration tests use the module's main code. Making check depend on the new suite means gradle check, and therefore gradle build, runs both kinds of tests, unit tests first.
Flaky tests
A flaky test sometimes passes and sometimes fails with no change to the code. Integration tests are especially prone to it, and flaky tests are poisonous: once people learn that a red build might mean nothing, they stop trusting red builds. The usual causes are known, and each has a fix.
| Cause | Example | Fix |
|---|---|---|
| Shared state between tests | Two tests use the same static list or database rows | Reset state in @BeforeEach; give each test its own data |
| Time | A test assumes a rental is not overdue, using the real clock | Inject a fixed Clock |
| Order | A test passes only if another runs first | Make every test arrange its own fixture |
| Concurrency and timing | A test sleeps for 100 milliseconds and hopes a background task is done | Wait for a condition with a timeout instead of sleeping |
| External services | A test calls a real web service | Use a local test server or a recorded response |
import java.util.*;
public class Main {
static final List<String> SHARED_CART = new ArrayList<>(); // shared by every test: the bug
static boolean testAddTube() {
SHARED_CART.add("TUBE-700x25");
return SHARED_CART.size() == 1;
}
static boolean testAddBell() {
SHARED_CART.add("BELL");
return SHARED_CART.size() == 1;
}
static void runInOrder(String label, List<String> order) {
SHARED_CART.clear();
StringBuilder sb = new StringBuilder(label + ":");
for (String t : order) {
boolean ok = t.equals("tube") ? testAddTube() : testAddBell();
sb.append(" ").append(t).append(ok ? " pass" : " FAIL");
}
System.out.println(sb);
}
public static void main(String[] args) {
runInOrder("Order A", List.of("tube", "bell"));
runInOrder("Order B", List.of("bell", "tube"));
runInOrder("Alone ", List.of("bell"));
}
}Order A: tube pass bell FAIL Order B: bell pass tube FAIL Alone : bell pass
What this code does
Both tests add to one static list and expect it to hold exactly one item, so whichever runs second fails, and each test passes when run alone. That is the classic signature of a test that depends on shared state: results change with the order and selection of tests. The fix is to give each test its own cart, which is exactly what JUnit's new instance per test and a @BeforeEach provide.
Try it yourself
Make the tests independent
The two tests share a static map, so one of them fails. Change the code so that each test creates its own map of stock counts instead of using STOCK, without changing what the tests check.
The program should print pass pass for both orders.
import java.util.*;
public class Main {
static final Map<String, Integer> STOCK = new HashMap<>(Map.of("BELL", 4));
static boolean testSellBell() {
STOCK.merge("BELL", -1, Integer::sum);
return STOCK.get("BELL") == 3;
}
static boolean testReceiveBells() {
STOCK.merge("BELL", 2, Integer::sum);
return STOCK.get("BELL") == 6;
}
public static void main(String[] args) {
System.out.println((testSellBell() ? "pass" : "FAIL") + " " + (testReceiveBells() ? "pass" : "FAIL"));
System.out.println((testReceiveBells() ? "pass" : "FAIL") + " " + (testSellBell() ? "pass" : "FAIL"));
}
}Try it yourself
A round-trip check
save turns a list of codes into one line of text and load turns it back. Write the round-trip check in main: save the list, load the result and print round trip ok if the loaded list equals the original, or round trip broken: followed by the loaded list.
The provided save and load are correct, so the program should print round trip ok.
import java.util.*;
public class Main {
static String save(List<String> codes) { return String.join(";", codes); }
static List<String> load(String line) { return line.isEmpty() ? List.of() : List.of(line.split(";")); }
public static void main(String[] args) {
List<String> codes = List.of("TUBE-700x25", "PAD-ROAD", "CHAIN-11");
System.out.println("not written yet");
}
}Common mistakes
MistakeRelying only on unit tests with doubles for code that reads files or talks to a database.
InsteadAdd integration tests that use the real file format, database or HTTP stack.
MistakeCalling a real external service from a test.
InsteadStart a local test server or use recorded responses, so the test is repeatable.
MistakeTesting SQL against an in-memory database that differs from production.
InsteadUse Testcontainers to run the real database engine when SQL details matter.
MistakeRunning slow integration tests on every keystroke.
InsteadKeep them in a separate suite that runs before pushing and in CI.
MistakeIgnoring a flaky test or rerunning until it passes.
InsteadFind the cause, such as shared state, time or ordering, and fix it.
Summary and key terms
- Integration tests exercise real parts together, including files, databases, HTTP and other modules, and catch bugs at the seams that unit tests with doubles cannot see.
- Round-trip tests save real data and load it back; PartsDesk's comma bug was found and then guarded this way.
- A local HTTP server, such as the JDK's com.sun.net.httpserver on port 0, tests HTTP code without depending on a real service.
- Database code is tested against an in-memory database or, more faithfully, a real engine in Testcontainers.
- Integration tests live in a separate suite: Maven's Failsafe plugin runs *IT classes, and Gradle's JVM Test Suite plugin adds an integrationTest task that check depends on.
- Flaky tests come from shared state, time, ordering, timing and external services, and each cause has a fix.
- Integration test
- A test of real parts working together, often with files, databases or the network.
- Seam
- A boundary between parts of a system, where formats and assumptions must agree.
- Round-trip test
- A test that saves data and loads it back, checking that nothing changed.
- In-memory database
- A database engine such as H2 that runs inside the test JVM.
- Testcontainers
- A library that runs real services such as PostgreSQL in Docker containers for tests.
- Failsafe
- The Maven plugin that runs integration tests, by convention classes named *IT.
- JVM Test Suite plugin
- The Gradle feature for defining extra test suites such as integrationTest.
- Flaky test
- A test that passes or fails unpredictably with no change to the code.
Practice problems
Work each problem on paper first, then reveal the answer to check.
Why did every unit test pass while PartsDesk failed to load Kofi's file?
Show answer
The unit tests used doubles; only the real file format and splitting together had the bug.
What is a round-trip test?
Show answer
A test that saves data and loads it back and checks it is unchanged.
Why start a test HTTP server on port 0?
Show answer
The operating system picks a free port, so the test never clashes with another program.
What is the main advantage of Testcontainers over H2?
Show answer
It runs the real database engine, so SQL behaves as in production.
Name two common causes of flaky tests.
Show answer
Shared state between tests and dependence on the real clock (also ordering, timing and external services).
Lesson quiz · 5 questions
Score 60% or more to complete this lesson.
Create a free account to save your progress, take quizzes and earn a certificate.