testing with junit

the picture

a test is a tiny experiment. set up a clean lab bench, do one thing, check the result, throw the bench away. the "throw it away" part is the important one: if experiments share a bench, the second one can pass (or fail) because of crumbs the first one left. junit enforces the clean bench for you, by building a new object for every single test method.

a first test

the code under test, and its test. it's not runnable on this page (junit isn't part of the JDK), so here's what really happened when i ran it with the junit 6.1.3 console launcher on jdk 25.

class Prices {
    static long withTax(long cents) { return cents + cents * 18 / 100; }
}

import static org.junit.jupiter.api.Assertions.assertEquals;
 
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.CsvSource;
 
class PricesTest {
 
    @ParameterizedTest(name = "{0} cents → {1}")
    @CsvSource({
        "100,  118",
        "0,    0",
        "1000, 1180",
        "99,   117",
    })
    void addsTax(long cents, long expected) {
        assertEquals(expected, Prices.withTax(cents));
    }
}

├─ JUnit Jupiter ✔
│  └─ PricesTest ✔
│     └─ addsTax(long, long) ✔
│        ├─ "100" cents → "118" ✔
│        ├─ "0" cents → "0" ✔
│        ├─ "1000" cents → "1180" ✔
│        └─ "99" cents → "117" ✘ expected: <117> but was: <116>

one method, four tests, and the fourth found a real bug: 99 * 18 / 100 is 17.82, and integer division throws away the .82. a single hand-picked example (100 cents) would have passed forever. that's the case for parameterized tests: the cases are data, so adding the nasty ones costs one line each. @CsvSource, @ValueSource, @EnumSource and @MethodSource (any method returning a stream of arguments) cover almost everything.

the lifecycle

here's the order junit calls things in. the output is real, and it has a surprise in it.

@BeforeAll

@Test void first()  { System.out.println("first"); }
@Test void second() { System.out.println("second"); }

assertions that explain themselves

when a test fails, the message is the whole bug report. junit's own assertEquals tells you the two values. AssertJ's fluent assertions (assertThat(x).something()) tell you how they differ. here a method meant to return the first three items alphabetically accidentally sorts in reverse. real output from both:

assertEquals(List.of("apple", "fig", "kiwi"), got);

expected: <[apple, fig, kiwi]> but was: <[pear, kiwi, fig]>

assertThat(got).containsExactly("apple", "fig", "kiwi");

Expecting actual:
  ["pear", "kiwi", "fig"]
to contain exactly (and in same order):
  ["apple", "fig", "kiwi"]
but some elements were not found:
  ["apple"]
and others were not expected:
  ["pear"]

AssertJ has assertions for almost everything (containsEntry, isCloseTo, hasMessageContaining, extracting(...)), and your IDE autocompletes them after assertThat(x)., which is most of why people like it.

mocks and spies

some code talks to things you don't want in a unit test: a payment API, a clock, an email server. a mock is a fake stand-in you create in one line, tell what to return, and check afterwards. Mockito is the standard one.

mock

a fake with no real behaviour. unstubbed methods return defaults. use it for collaborators: the thing your code calls.

spy

a real object, wrapped. real methods run unless you stub them. use it rarely: usually a smell that a class does too much.

stub

when(x.call()).thenReturn(v): "if asked this, answer that".

verify

verify(x).call(): "check my code actually asked this".

real dependencies: testcontainers

mocking a database is a trap: your fake happily accepts SQL the real postgres would reject. Testcontainers starts a real postgres (or kafka, or redis) in docker for the duration of a test, hands you its address, and deletes it afterwards. this is the 2.0 API (artifact testcontainers-postgresql, class in org.testcontainers.postgresql):

import org.junit.jupiter.api.Test;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.testcontainers.postgresql.PostgreSQLContainer;
 
@Testcontainers
class UserRepositoryTest {
 
    @Container
    static PostgreSQLContainer db = new PostgreSQLContainer("postgres:17-alpine");
 
    @Test
    void savesAndLoads() throws Exception {
        try (var conn = java.sql.DriverManager.getConnection(
                db.getJdbcUrl(), db.getUsername(), db.getPassword())) {
            // run real migrations, real queries, real constraints
        }
    }
}

the trade: these tests take seconds instead of milliseconds and need docker on the build machine. that's why most suites are mostly fast unit tests with mocks, plus a smaller layer of these.