Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 119 ยท Testing

Integration Testing

Write Java integration tests that hit a real database and HTTP server, keep test data isolated, use Testcontainers and Failsafe, and read JaCoCo code coverage wisely.

Unit tests check one class with its dependencies replaced by doubles. They are fast and precise, but they cannot tell you whether your SQL is valid, whether a column is really called published_year, whether the JSON your endpoint returns matches what clients expect, or whether a unique constraint is enforced. Those questions are only answered by running your code against the real thing.

An integration test exercises your code together with the real infrastructure it talks to: a database, an HTTP server, a message broker, the file system. In this lesson you will test a JDBC repository against a real database, keep test data from leaking between tests, test an HTTP endpoint over a real socket, and learn the tools teams use in real projects: Testcontainers, the Maven Failsafe plugin and JaCoCo coverage reports. The JDBC code builds on The DAO and Repository Patterns.

The test pyramid

Mike Cohn's test pyramid is the usual picture of a healthy test suite:

TEXT
           /\
          /  \      End-to-end tests: a few, through the UI or public API
         /----\
        /      \    Integration tests: some, real database / HTTP / queue
       /--------\
      /          \  Unit tests: many, fast, in-memory
     /____________\
  • Unit tests are the broad base: thousands of them, each running in milliseconds, pinpointing failures to one class.
  • Integration tests are fewer and slower (a database round trip, a server start), but they catch wiring, SQL and serialization bugs that unit tests cannot see.
  • End-to-end tests drive the whole deployed system the way a user would. They give the most confidence per test and are the slowest and most fragile, so keep them to the critical journeys (sign up, check out).

The shape is a guideline, not a law. A thin CRUD service with little logic gets more value from integration tests than from mocking every repository call. What matters is that each behavior is tested at the cheapest level that can actually catch its bugs.

Testing a repository against a real database

The repository below stores books with JDBC. A unit test with a mocked Connection would only prove that the code calls prepareStatement with some string. The integration test runs the real SQL against H2, an in-memory database that starts in milliseconds, so every test can get a brand-new, empty database.

Each test gets its own database by putting a random name in the JDBC URL (jdbc:h2:mem:<uuid>). An H2 in-memory database lives as long as a connection to it is open, so closing the connection in @AfterEach throws it away.

Java Testing a JDBC repository on H2

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

These three tests check things no mock can: that the INSERT is valid SQL for this schema, that ORDER BY published_year really sorts, that generated keys come back, and that the database's UNIQUE constraint fires and is translated into a domain exception (SQL state 23505 is the standard code for a unique violation, used by H2 and PostgreSQL alike). Try renaming published_year in the schema to year_published and run again: every test fails with a SQL error, exactly the kind of bug that sails through mocked unit tests.

Keeping test data isolated

Integration tests share something unit tests never do: external state. If one test leaves rows behind, the next test sees them, and results start to depend on the order tests run in. Flaky, order-dependent tests are the most common complaint about integration suites. There are three standard cures:

Strategy How Trade-off
Fresh database per test new in-memory DB (as above) or re-create the schema perfectly isolated; slow for real databases with big schemas
Roll back after each test setAutoCommit(false) before, rollback() after fast; does not work if the code under test commits itself or uses other connections
Clean up explicitly DELETE FROM / TRUNCATE tables in @BeforeEach works with any code; you must keep the table list complete and ordered by foreign keys

Clean before each test rather than after: if a test crashes halfway, the next test still starts from a known state. The next example shows the problem and the rollback cure side by side. Both classes share one database per class; @Order forces the unlucky order so the leak is guaranteed to show.

Java Leaking data versus rolling back

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

LeakyTest.seedDataHasTwoMembers fails with expected: <2> but was: <3> even though nothing is wrong with the code, while the same test in IsolatedTest passes because the insert was rolled back. In a real suite you would not see the forced order: the failure would appear only on some machines or after someone adds a test, which is what makes leaks so painful. This is also how Spring's @Transactional test support works: it rolls back each test's transaction by default (see Testing Spring Boot Applications).

Test data that is easy to read

Integration tests need realistic rows, and long INSERT statements bury the point of the test. Two patterns help:

  • Test data builders: aBook().withAuthor("Frank Herbert").publishedIn(1969).build() fills every required column with sensible defaults, so each test states only the fields it cares about.
  • Shared schema scripts: load the same migration files production uses (Flyway or Liquibase) instead of a hand-written test schema. Then a migration bug fails the tests, not the deployment.

Testing an HTTP endpoint for real

The same idea applies to web code: start the server on a real socket and call it with a real HTTP client. The example starts the JDK's built-in HttpServer on port 0 (the operating system picks a free port, so parallel builds never collide) in @BeforeAll, calls it with HttpClient, and checks status codes, headers and the body. The HTTP lessons explain these classes in detail.

Java An HTTP integration test

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The server starts once per class because starting it is the expensive part; the tests only read data, so sharing it is safe. In a Spring Boot project the equivalent is @SpringBootTest(webEnvironment = RANDOM_PORT) with a test client, or @WebMvcTest with MockMvc for a lighter slice.

When H2 is not enough: Testcontainers

H2 is fast and needs no installation, but it is not your production database. It supports a lot of standard SQL and offers compatibility modes (MODE=PostgreSQL, MODE=MySQL), yet many vendor features are missing or behave differently. For example, with H2 2.5 in PostgreSQL mode, INSERT ... ON CONFLICT (id) DO NOTHING, INSERT ... RETURNING id, jsonb_build_object(...) and interval '1 day' all fail, although they are everyday PostgreSQL. A test suite that passes on H2 can still ship SQL that breaks in production. See for yourself:

Java PostgreSQL syntax on H2's PostgreSQL mode

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Some PostgreSQL features (string_agg, ILIKE) work in compatibility mode; the others do not.

Testcontainers solves this by starting the real database in a Docker container for the test run and throwing it away afterward. It needs Docker on the developer machine and the CI server. With the JUnit integration (Testcontainers 2.x shown; read-only here, since Docker is not available on this site):

XML
<dependency>
  <groupId>org.testcontainers</groupId>
  <artifactId>testcontainers-postgresql</artifactId>
  <version>2.0.5</version>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.testcontainers</groupId>
  <artifactId>testcontainers-junit-jupiter</artifactId>
  <version>2.0.5</version>
  <scope>test</scope>
</dependency>
Java
@Testcontainers
class JdbcBookRepositoryIT {
    @Container
    static PostgreSQLContainer postgres = new PostgreSQLContainer("postgres:17-alpine");

    Connection connection;

    @BeforeEach
    void connect() throws SQLException {
        connection = DriverManager.getConnection(
                postgres.getJdbcUrl(), postgres.getUsername(), postgres.getPassword());
        // run migrations or the schema script, then clean tables
    }

    @Test
    void saveAssignsAGeneratedId() throws SQLException { ... }
}

A static @Container field starts one container for the whole class (a few seconds); an instance field would start one per test. Testcontainers 2.0 renamed its modules with a testcontainers- prefix and moved classes into per-module packages; 1.x projects use artifacts like org.testcontainers:postgresql and org.testcontainers.containers.PostgreSQLContainer. Beyond databases, there are modules for Kafka, RabbitMQ, Redis, Elasticsearch, LocalStack (AWS) and any Docker image. Spring Boot can wire a container into the application automatically with @ServiceConnection.

A common setup uses both: H2 or fakes for fast feedback while coding, Testcontainers in CI for the real database.

Running integration tests separately

Integration tests are slower, so builds usually separate them from unit tests. In Maven, Surefire runs unit tests in the test phase, and the Failsafe plugin runs classes named *IT (or IT*, *ITCase) in the integration-test phase, with the build failing in verify. That is why the classes above end in IT.

XML
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-failsafe-plugin</artifactId>
  <version>3.6.0</version>
  <executions>
    <execution>
      <goals>
        <goal>integration-test</goal>
        <goal>verify</goal>
      </goals>
    </execution>
  </executions>
</plugin>
Terminal
mvn test      # unit tests only (Surefire)
mvn verify    # unit tests, then integration tests (Failsafe)

Failsafe's split matters: if an integration test fails, the post-integration-test phase still runs (to stop servers or containers) before verify fails the build. In Gradle, teams create a separate source set or a dedicated Test task (the JVM Test Suite plugin's integrationTest suite), or filter by @Tag("integration") as shown in Test Lifecycle and Organization.

Code coverage with JaCoCo

Code coverage measures which parts of the production code ran during the tests. JaCoCo is the standard Java tool: a Java agent records execution while tests run, and a report goal turns that into HTML showing every line in green (covered), yellow (some branches covered) or red (never run).

XML
<plugin>
  <groupId>org.jacoco</groupId>
  <artifactId>jacoco-maven-plugin</artifactId>
  <version>0.8.15</version>
  <executions>
    <execution>
      <goals><goal>prepare-agent</goal></goals>
    </execution>
    <execution>
      <id>report</id>
      <phase>verify</phase>
      <goals><goal>report</goal></goals>
    </execution>
  </executions>
</plugin>

After mvn verify, open target/site/jacoco/index.html. In Gradle, apply the jacoco plugin and run gradle test jacocoTestReport. The check goal (Maven) or jacocoTestCoverageVerification task (Gradle) can fail the build below a threshold.

How to read the numbers:

  • Line coverage says a line ran. Branch coverage says both sides of each if, switch case and && ran, which is the more honest number: if (age < 0 || age > 120) can be "covered" by one test that checks neither boundary.
  • Coverage shows what is untested, not what is tested well. A test without assertions covers code too. 80% coverage with sharp assertions beats 100% with weak ones.
  • Use red lines as questions. An uncovered error branch often means a missing test for a real failure mode. An uncovered getter is rarely worth a test.
  • Mutation testing (PIT, pitest-maven) goes further: it changes your code (flips < to <=, removes calls) and checks that some test fails. Surviving mutants reveal weak assertions that coverage cannot.

Avoid hard coverage targets like "100% or the build fails". Teams then write tests to satisfy the tool instead of to catch bugs. A modest floor (say 70-80% branch coverage for business logic) plus reviewing coverage on each change works better.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which bug can an integration test against a real database catch that a unit test with a mocked Connection cannot?

    A mocked Connection accepts any SQL string. Only a real database parses the statement and checks it against the actual schema.
  2. 2. Each test opens jdbc:h2:mem:<random-uuid> and closes the connection in @AfterEach. What does that achieve?

    An H2 in-memory database is identified by its name and lives while a connection is open, so a unique name plus closing the connection gives perfect isolation.
  3. 3. Why can rolling back after each test fail to isolate data?

    Rollback only undoes work done in the test's own uncommitted transaction. Commits inside the code, or writes through other connections, survive.
  4. 4. Your production database is PostgreSQL and your repository uses INSERT ... ON CONFLICT DO NOTHING. What is the most reliable way to test it?

    H2's compatibility modes cover only part of PostgreSQL's syntax; ON CONFLICT with a column list fails on H2. Testcontainers runs the real database version you use in production.
  5. 5. A test calls if (age < 0 || age > 120) once with age 30. What does JaCoCo report for that line?

    Line coverage only says the line ran. Branch coverage shows that the true outcomes were never exercised, which is why branch coverage is the more honest metric.

Summary

  • Integration tests run your code with real infrastructure (database, HTTP, queues) and catch SQL, schema, wiring and serialization bugs unit tests cannot.
  • The test pyramid: many unit tests, some integration tests, a few end-to-end tests; test each behavior at the cheapest level that can catch its bugs.
  • Test JDBC code against H2 with a fresh database per test, or roll back / clean up before each test. Leaked data causes flaky, order-dependent failures.
  • Test HTTP endpoints over a real socket: start the server on port 0 in @BeforeAll, call it with HttpClient, check status, headers and body.
  • H2 is not your production database; Testcontainers runs the real one in Docker, typically one static container per class.
  • Name integration tests *IT and run them with Failsafe in mvn verify. Measure coverage with JaCoCo, prefer branch coverage, and treat it as a map of what is untested rather than a score.

Next: Logging with SLF4J and Logback, where you learn how professional Java applications report what they are doing.