Java Testing (JUnit Jupiter + Mockito)

Overview

Test-first in Java, same discipline as everywhere (see tdd-workflow): write the failing test, watch it fail, minimal code to pass. This skill is the Java mechanics for that cycle.

Core principle: Unit-test the domain and services as plain Java without booting the framework. Reserve framework-integration tests for the boundary (HTTP, persistence).

Test levels

Level	What it covers	Tools
Unit	Domain entity / value object, no mocks	JUnit Jupiter
Unit with mocks	Service (mock its ports)	JUnit Jupiter + Mockito
Persistence slice	Repository against a real DB, no HTTP layer	@DataJpaTest (Spring) + Testcontainers @ServiceConnection; Quarkus @QuarkusTest with Dev Services
Web slice	Controller/resource wiring, serialization, validation — mocked service	@WebMvcTest (Spring); Quarkus @QuarkusTest + @InjectMock
End-to-end	Full app boot, real DB, real HTTP	@SpringBootTest(webEnvironment=RANDOM_PORT) + RestTestClient (Spring Boot 4); @QuarkusTest + RestAssured

Most tests are the first two — fast, no container. Boot the framework only where you're testing wiring, serialization, or SQL; reach for the narrowest slice that proves it before a full @SpringBootTest/plain @QuarkusTest.

JUnit Jupiter + Mockito unit test

class TaskServiceTest {
    private final TaskRepository repo = mock(TaskRepository.class);
    private final TaskService service = new TaskService(repo);   // constructor injection pays off

    @Test
    void create_persists_and_returns_task() {
        Task t = service.create("Write the report");
        verify(repo).persist(any(Task.class));   // or save(...) for Spring
        assertEquals("Write the report", t.title());
    }

    @Test
    void create_rejects_blank_title() {
        assertThrows(InvalidTaskTitle.class, () -> service.create("  "));
        verifyNoInteractions(repo);              // invalid input never hits the DB
    }
}

Rules

• Mock collaborators (ports), never the class under test. A test whose asserts only exercise the mock proves nothing — assert on the real object's behavior/return.
• One behavior per @Test, named for the behavior (create_rejects_blank_title).
• Prefer real value objects over mocking them — they're cheap to construct.
• @ParameterizedTest for boundary tables (200 chars ok, 201 rejected).
• Integration tests use Testcontainers for a real Postgres, not H2 — test against the DB you deploy on. Seed per test with the repository's real migrations plus minimal inserts; never share state between tests.
• AssertJ (assertThat(...)) is fine and reads well; match the repo's existing assertion style.
• Spring Boot 4: @MockitoBean/@MockitoSpyBean replace @MockBean/@SpyBean, which were removed in Boot 4.0 — use the old annotations only on a repo still pinned to Boot 3.x.
• Quarkus: @InjectMock inside a @QuarkusTest for a CDI-bean mock; RestAssured for the HTTP-level assertion: given().when().post("/tasks").then().statusCode(201).
• Testcontainers Java 2.x coordinates: artifacts are prefixed testcontainers-* (e.g. org.testcontainers:testcontainers-postgresql), class org.testcontainers.postgresql.PostgreSQLContainer; JUnit 4 support was removed, Jupiter only.
• On JDK 21+, register mockito-core as a -javaagent in the build's surefire/failsafe config if the repo doesn't already, to avoid the dynamic-agent-loading warning.

Common Mistakes

• @SpringBootTest/plain @QuarkusTest on everything — slow, and hides design problems that plain unit tests would surface.
• Mocking the service you're testing.
• Asserting verify(mock) only, never checking the returned/observable value.
• H2 in tests but Postgres in prod — dialect gaps ship bugs.
• Using @MockBean on a Spring Boot 4 repo (removed; use @MockitoBean).

Red Flags

• The test passes without the production code being written (it tests the mock).
• A unit test that needs a running database.
• No failing-first run — you wrote the test after the code.