Java Testing (JUnit, Mockito)

The pyramid says to have many fast, isolated unit tests, fewer integration tests and very few end-to-end tests. Cost, run time and flakiness grow as you go up, while precision of failure location drops.

• Unit: one class, collaborators doubled, milliseconds.
• Integration: real wiring with DB, HTTP or messaging, seconds.
• E2E/UI: whole deployed system, slow and brittle.
• Variants: the "testing trophy" favours integration tests; the "ice cream cone" (mostly manual/E2E) is the anti-pattern.

A unit test exercises one unit in isolation with no I/O, no network and no framework startup. An integration test verifies that several real components cooperate, such as a repository with a real database.

• Unit tests should run in-process in milliseconds and be deterministic.
• "Unit" is defined by behaviour, not necessarily one class; the London school mocks collaborators, the Detroit/classicist school uses real ones when cheap.
• Maven convention: Surefire runs *Test, Failsafe runs *IT in the verify phase.

JUnit 5 = JUnit Platform (launches tests, TestEngine SPI) + JUnit Jupiter (the new programming and extension model) + JUnit Vintage (runs JUnit 3/4 tests on the platform).

• Package is org.junit.jupiter.api; tests may be package-private.
• Other engines (Spock, ArchUnit, Cucumber) plug in through the same platform.
• Requires Java 8+; Spring Boot 3 starters bring Jupiter by default and no longer ship Vintage.

@BeforeAll once before all tests, @BeforeEach before every test, then the test, @AfterEach, and finally @AfterAll. A new test class instance is created per test method by default.

• @BeforeAll/@AfterAll must be static unless @TestInstance(Lifecycle.PER_CLASS) is used.
• Superclass @BeforeEach runs before the subclass one; @AfterEach runs in reverse.
• Replaces JUnit 4 @Before, @BeforeClass, @After, @AfterClass.

assertAll runs all grouped assertions and reports every failure together instead of stopping at the first. assertThrows(Type.class, executable) passes if the executable throws that type or a subtype and returns the exception for further checks.

@Test
void rejectsNegativeAmount() {
    var ex = assertThrows(IllegalArgumentException.class,
        () -> new Money(-1, "USD"));
    assertAll("money error",
        () -> assertTrue(ex.getMessage().contains("negative")),
        () -> assertNull(ex.getCause()));
}

• assertThrowsExactly demands the exact type, not a subtype.
• assertTimeout waits for completion; assertTimeoutPreemptively aborts in another thread.

@ParameterizedTest plus a source annotation runs the same method with many inputs, each as its own reported invocation. It needs the junit-jupiter-params artifact (included in junit-jupiter).

• Sources: @ValueSource, @EnumSource, @CsvSource, @CsvFileSource, @MethodSource, @ArgumentsSource, @NullAndEmptySource.
• @MethodSource factory is static (unless PER_CLASS) and returns Stream<Arguments>.
• name = "{index}: {0} -> {1}" customizes display names.
• Implicit conversion handles String to enum, numbers, dates; @ConvertWith for custom.

Extensions implement callback interfaces such as BeforeEachCallback, ParameterResolver, TestExecutionExceptionHandler and ExecutionCondition, and are registered with @ExtendWith. Unlike JUnit 4, you can combine many extensions on one class.

• Registration: declarative @ExtendWith, programmatic @RegisterExtension field, or automatic via ServiceLoader (enable junit.jupiter.extensions.autodetection.enabled).
• MockitoExtension, SpringExtension, @TempDir and TestInfo injection all use this model.
• Use the ExtensionContext.Store for per-test or per-class state.

Implement ParameterResolver with supportsParameter and resolveParameter, then register it. JUnit calls it for constructor and method parameters that it does not resolve itself.

class RandomPortResolver implements ParameterResolver {
    public boolean supportsParameter(ParameterContext p, ExtensionContext c) {
        return p.getParameter().getType() == int.class
            && p.isAnnotated(RandomPort.class);
    }
    public Object resolveParameter(ParameterContext p, ExtensionContext c) {
        try (var s = new java.net.ServerSocket(0)) { return s.getLocalPort(); }
        catch (java.io.IOException e) { throw new RuntimeException(e); }
    }
}

@Nested marks a non-static inner class as a group of tests that shares the outer context, so you can express "given X, when Y, then Z" hierarchies with layered @BeforeEach setup.

• Outer @BeforeEach runs before the inner one for each inner test.
• Inner classes must be non-static; static members were not allowed before Java 16.
• Pair with @DisplayName for readable reports.

@Tag("slow") labels tests so build tools can include or exclude them. Conditional annotations such as @EnabledOnOs, @EnabledIfEnvironmentVariable, @EnabledForJreRange and @DisabledIf toggle execution, and @Disabled skips unconditionally.

• Maven: -Dgroups=fast / -DexcludedGroups=slow (Surefire), or Gradle useJUnitPlatform { includeTags("fast") }.
• Assumptions (assumeTrue) abort a test, reported as skipped, not failed.
• Always put a reason in @Disabled("JIRA-123").

@TempDir injects a temporary directory deleted after the test, TestInfo gives display name and tags, and @RepeatedTest(n) re-runs a test n times with RepetitionInfo.

• @TempDir works on fields (per class or per test) and parameters, typed Path or File.
• @RepeatedTest is useful when diagnosing flaky behaviour, not as a cure.
• @TestMethodOrder(OrderAnnotation.class) exists, but order dependence is a smell.

By default (PER_METHOD) JUnit creates a new instance for each test. @TestInstance(PER_CLASS) creates one instance per class, allowing non-static @BeforeAll/@AfterAll and @MethodSource factories.

• Change it for expensive shared setup or when using Kotlin or @Nested with @BeforeAll.
• Cost: instance fields become shared mutable state, so tests may couple.
• Set globally with junit.jupiter.testinstance.lifecycle.default=per_class.

Enable junit.jupiter.execution.parallel.enabled=true, then choose mode (same_thread or concurrent) per class or method; the platform runs them on a ForkJoinPool strategy. Use @ResourceLock for shared resources and @Execution to opt in/out.

• Config via junit-platform.properties.
• Static state, shared DB rows, files and ports are the usual causes of failures once parallel.
• Surefire forkCount / parallel is a separate, process-level mechanism.

AssertJ offers a fluent, discoverable API with rich failure messages: assertThat(actual).isEqualTo(...) with chained type-specific checks for strings, collections, optionals, dates and exceptions.

assertThat(users)
    .filteredOn(u -> u.age() > 18)
    .extracting(User::name)
    .containsExactlyInAnyOrder("Ann", "Bob");
assertThatThrownBy(() -> service.find(0))
    .isInstanceOf(NotFoundException.class)
    .hasMessageContaining("0");

• usingRecursiveComparison() compares objects field by field without equals.
• SoftAssertions / assertSoftly collects failures like assertAll.
• Spring Boot starter-test ships AssertJ and Hamcrest.

usingRecursiveComparison() compares fields reflectively, ignoring the class's equals, so it works on types that do not override it and reports the exact differing path.

• Configure with ignoringFields, ignoringFieldsMatchingRegexes, comparingOnlyFields, withComparatorForType.
• By default, differing types with identical fields are considered equal unless withStrictTypeChecking().
• Useful for DTO/entity mapping tests with generated ids or timestamps.

Gerard Meszaros' taxonomy: dummy, stub, spy, mock and fake.

• Dummy: passed to fill a parameter, never used.
• Stub: returns canned answers.
• Spy: a real or recording object that remembers calls.
• Mock: pre-programmed with expectations and verifies interactions.
• Fake: working lightweight implementation (in-memory repository, H2).

Mockito calls everything a "mock", but a stubbed-only mock acts as a stub.

Prefer asserting observable outcomes (return values, state, persisted data) over verifying internal calls. Behaviour verification is justified for side effects that have no observable result, such as sending an email.

• Over-verifying couples tests to implementation, so refactors break tests.
• Query methods should be stubbed, commands should be verified.
• Fakes give state-based tests without brittle verify chains.

A mock replaces all behaviour: methods return defaults (null, 0, empty collections/Optional) unless stubbed. A spy wraps a real object, calling real methods unless stubbed.

• spy(realObject) copies the instance state at creation; the spy is a different object from the original.
• Stub spies with doReturn(x).when(spy).method(), because when(spy.method()) invokes the real method first.
• A spy signals a design smell (partial mocking); prefer extracting a collaborator.

@ExtendWith(MockitoExtension.class) initializes @Mock and @Spy fields and builds the @InjectMocks object, trying constructor injection first, then setter, then field injection by type and name.

@ExtendWith(MockitoExtension.class)
class OrderServiceTest {
    @Mock PaymentClient payments;
    @InjectMocks OrderService service;

    @Test void charges() {
        when(payments.charge(10)).thenReturn(true);
        assertTrue(service.pay(10));
    }
}

• Failure to inject is silent when the strategy fails (a field stays null); prefer explicit constructor creation when in doubt.
• JUnit 4 equivalent: MockitoJUnitRunner or MockitoAnnotations.openMocks.

when(m.call()).thenReturn(x) is the common form. doReturn/doThrow/doNothing/doAnswer().when(m).call() is required for void methods and spies. BDDMockito.given(...).willReturn(...) and then(m).should() are aliases with given-when-then wording.

• Chain consecutive results: thenReturn(a, b, c) or thenThrow(...).
• thenAnswer computes from arguments.
• Later stubbing of the same call overrides earlier.

Matchers such as any(), eq(), anyString(), argThat() and isNull() match arguments flexibly. If one argument uses a matcher, all arguments in that call must use matchers; wrap raw values with eq().

when(repo.find(anyLong(), eq("ACTIVE"))).thenReturn(user);
// invalid: when(repo.find(anyLong(), "ACTIVE"))  -> InvalidUseOfMatchersException

• Mockito 2+: any(Class) is type-checking and does not match null; any() matches anything including null.
• anyString() does not match null in Mockito 2+.

verify(mock).method(args) checks exactly one call with matching arguments. Modes: times(n), never(), atLeast(n), atMost(n), timeout(ms). InOrder checks relative order across mocks.

InOrder order = inOrder(audit, repo);
order.verify(audit).start();
order.verify(repo).save(any());
verifyNoMoreInteractions(repo);

• verifyNoInteractions(mock) asserts the mock was never touched.
• verify after the fact does not require stubbing.

ArgumentCaptor captures the actual argument passed to a mock so you can assert on its fields, which is better than argThat when the object is complex or built inside the code under test.

var captor = ArgumentCaptor.forClass(Email.class);
verify(mailer).send(captor.capture());
assertThat(captor.getValue().to()).isEqualTo("a@x.com");

• @Captor annotation works with the extension.
• getAllValues() returns every capture across calls.
• Do not capture inside stubbing (when); use it with verify.

With MockitoExtension the default strictness is STRICT_STUBS: an unused stub fails the test with UnnecessaryStubbingException, and a stubbed call made with different arguments raises PotentialStubbingProblem.

• Keeps tests clean by removing dead setup.
• Relax per stub with lenient().when(...) or per class via @MockitoSettings(strictness = Strictness.LENIENT).
• Strict stubs also make verify of stubbed calls redundant.

Default answer RETURNS_DEFAULTS gives null, 0, false, empty collections and empty Optional/Stream. RETURNS_DEEP_STUBS returns mocks of return types to allow chained stubbing like when(a.b().c()).thenReturn(x).

• RETURNS_SMART_NULLS returns a descriptive exception-throwing object instead of null.
• Deep stubs usually signal a Law of Demeter violation; use sparingly (builders, fluent APIs).
• Custom Answer for dynamic responses.

Yes, with the inline mock maker, which is the default since Mockito 5. It uses instrumentation (Byte Buddy agent) to mock final classes/methods, mockStatic and mockConstruction.

try (var s = mockStatic(UUID.class)) {
    s.when(UUID::randomUUID).thenReturn(FIXED);
    assertEquals(FIXED, UUID.randomUUID());
}

• Static mocks are thread-local and must be closed (try-with-resources) or they leak into other tests.
• Mockito 4 and earlier: add mockito-inline artifact.
• Java 21+ warns about dynamic agent loading; configure -javaagent for Mockito explicitly in future-proof builds.
• Prefer wrapping statics behind an injectable interface.

Mockito cannot stub or verify equals() and hashCode(), as it relies on them internally. Private methods are not mockable, and native methods and some JDK internals are restricted even with the inline maker.

• Constructor logic of a mocked class is skipped (objenesis), so field initializers do not run.
• Mocking value objects, collections or String is a smell: use real instances.
• Don't mock types you don't own; wrap them in an adapter and test the adapter via integration test.

Test-driven development writes a failing test first (red), writes the minimal code to pass (green), then cleans up with tests as the safety net (refactor).

• Benefits: design pressure toward small, decoupled units; built-in regression suite; focus.
• Costs: learning curve, poor fit for exploratory spikes or heavy UI work.
• Related: BDD (given-when-then, behaviour naming), ATDD (acceptance test first).

The Detroit/classicist style uses real collaborators where cheap and asserts on state. The London/mockist style mocks collaborators and drives design outside-in by verifying interactions.

• Mockist gives fast isolated tests and discovers interfaces early, but is more coupled to implementation.
• Classicist tests survive refactoring better but failures point to a wider area.
• Most teams mix: fakes or real objects for domain, mocks at architectural boundaries.

FIRST: Fast, Independent, Repeatable, Self-validating, Timely. Structure with Arrange-Act-Assert (or Given-When-Then), test one behaviour, and name the test by behaviour, such as rejectsExpiredToken.

• No logic (loops, conditionals) in tests.
• One logical assertion; assertAll groups related checks.
• Test public behaviour, not private methods.
• Avoid shared mutable fixtures and order dependence.

A test data builder provides a fluent object with valid defaults where each test overrides only what matters. An Object Mother is a factory with named canned instances (Users.admin()), which explode in variants over time.

class UserBuilder {
    private String name = "Ann"; private int age = 30;
    UserBuilder age(int a) { this.age = a; return this; }
    User build() { return new User(name, age); }
}
// new UserBuilder().age(17).build()

• Keeps tests resilient when constructors change (one place to fix).
• Combine: mother methods return pre-configured builders.

@SpringBootTest bootstraps the full ApplicationContext (finds @SpringBootApplication) for integration tests. webEnvironment selects MOCK (default, MockMvc), RANDOM_PORT, DEFINED_PORT or NONE.

• Slow startup, so contexts are cached by configuration key across test classes.
• @MockBean / @SpyBean (Spring Boot 3.4+: @MockitoBean / @MockitoSpyBean) alter the cache key and force new contexts.
• Use TestRestTemplate, WebTestClient or @LocalServerPort with a real port.

@WebMvcTest(Controller.class) loads only the MVC slice: controllers, @ControllerAdvice, converters, filters and security config for web, but not @Service, @Repository or @Component beans. Collaborators are supplied via @MockBean/@MockitoBean, and MockMvc is auto-configured.

@WebMvcTest(UserController.class)
class UserControllerTest {
    @Autowired MockMvc mvc;
    @MockBean UserService service;

    @Test void returns404() throws Exception {
        when(service.find(1L)).thenThrow(new NotFoundException());
        mvc.perform(get("/users/1")).andExpect(status().isNotFound());
    }
}

@DataJpaTest loads JPA repositories, entities, EntityManager, TestEntityManager and Flyway/Liquibase, replaces the DataSource with an embedded DB, and wraps each test in a transaction that rolls back.

• Use @AutoConfigureTestDatabase(replace = NONE) with Testcontainers to run on the real DB engine.
• Services and controllers are not loaded.
• Rollback hides flush issues: call entityManager.flush() and clear() to force SQL and re-read.

@JsonTest, @WebFluxTest, @DataJdbcTest, @DataMongoTest, @DataRedisTest, @JdbcTest, @RestClientTest and @JooqTest each load only the relevant auto-configuration.

• Slices are faster and expose wiring mistakes in the layer under test.
• Add extra beans with @Import.
• Custom slice annotations combine @TypeExcludeFilters and @AutoConfigure....

@Mock creates a plain Mockito mock outside Spring. @MockBean creates a mock and registers it in the Spring context, replacing any bean of that type. Boot 3.4 deprecates it in favour of @MockitoBean (Spring Framework 6.2).

• @MockBean mocks are reset after each test.
• Different @MockBean sets produce different cache keys, so contexts are recreated.
• Prefer plain @Mock with constructor injection for unit tests to avoid Spring entirely.

Use spring-security-test: @WithMockUser(roles = "ADMIN"), @WithUserDetails, or request post-processors such as jwt(), httpBasic() and csrf().

• @WebMvcTest includes the security filter chain; state-changing requests need .with(csrf()) unless CSRF is disabled.
• Test both allowed and denied paths (401 vs 403).
• Method security (@PreAuthorize) needs a context that enables it, not a plain unit test.

Testcontainers starts disposable Docker containers (PostgreSQL, Kafka, Redis) from tests, so integration tests run against the real engine rather than a fake like H2.

@Testcontainers
@SpringBootTest
class RepoIT {
    @Container @ServiceConnection
    static PostgreSQLContainer<?> pg = new PostgreSQLContainer<>("postgres:16");
}

• Spring Boot 3.1+ @ServiceConnection wires properties automatically; before that use @DynamicPropertySource.
• A static @Container is shared by all tests in the class; instance field means one per test.
• Needs Docker in CI; Ryuk container cleans up leaked containers.

Options: roll back each test's transaction (@Transactional), truncate tables in @BeforeEach, recreate a Flyway schema, or reuse a template database. Pick based on whether the code under test commits.

• @Transactional tests hide bugs involving real commits, lazy loading outside a session and REQUIRES_NEW.
• A test-side @Transactional does not roll back work done on another thread (e.g. RANDOM_PORT server).
• Use @Sql scripts for fixtures; avoid dependence on pre-seeded shared data.

Contract testing verifies that a consumer's expectations of a provider's API and the provider's actual behaviour agree, without deploying both together.

• Consumer-driven (Pact): consumers publish expectations to a broker; the provider verifies them in CI. can-i-deploy gates releases.
• Spring Cloud Contract (provider-driven): contracts in Groovy/YAML generate provider tests and consumer stubs (WireMock).
• Catches breaking changes (renamed field, status code) cheaply compared to E2E.
• Does not test business logic of either side.

A flaky test passes and fails with no code change. Typical causes: timing and Thread.sleep, shared state or ordering, real time/randomness, concurrency races, external services, and resource limits.

• Fix the cause: inject Clock, use Awaitility for async, isolate data, seed randomness, use fakes for remote services.
• Quarantine a flaky test quickly (tag it, track it) rather than blindly rerunning.
• Retries (Surefire rerunFailingTestsCount) mask, not solve.
• Detect via repeated runs, random ordering and CI trend dashboards.

Inject a java.time.Clock instead of calling Instant.now() or LocalDate.now() directly; tests use Clock.fixed(...) or a mutable test clock.

Clock clock = Clock.fixed(Instant.parse("2026-01-01T00:00:00Z"), ZoneOffset.UTC);
var service = new TokenService(clock);
assertTrue(service.issue().expiresAt().isAfter(clock.instant()));

• LocalDate.now(clock) overloads exist on all java.time types.
• Mocking Instant.now() statically is a last resort.
• For scheduled work, extract logic from @Scheduled methods and call it directly.

Make the code deterministic where possible (inject an Executor that runs inline), and otherwise coordinate with latches/futures and poll with Awaitility, never with fixed sleeps.

await().atMost(Duration.ofSeconds(2))
       .untilAsserted(() -> assertThat(repo.count()).isEqualTo(1));

• Use CountDownLatch/CyclicBarrier to maximize contention in race tests.
• Run the test many times (@RepeatedTest) to improve odds of exposing races; passing proves little.
• Tools: jcstress for memory-model tests, Lincheck, ExecutorService shutdown in @AfterEach.
• Exceptions on other threads do not fail the test automatically; collect and rethrow.

For void methods assert on side effects: collaborator calls (verify), state changes, or captured output. For exceptions use assertThrows/assertThatThrownBy; for logs use a test appender (Logback ListAppender) or OutputCaptureExtension.

• Do not assert log text unless logging is a requirement.
• @ExtendWith(OutputCaptureExtension.class) gives a CapturedOutput parameter in Spring Boot.
• doThrow on a mock tests error paths.

Coverage (line, branch, instruction via JaCoCo) tells you which code was executed, not whether behaviour was verified. High coverage with no assertions is worthless; low coverage reliably signals untested areas.

• Branch coverage is stronger than line coverage.
• Goodhart's law: a mandated percentage encourages assertion-free tests.
• Use thresholds as a floor on changed code (diff coverage), not a goal.
• Exclude generated code and trivial DTOs sensibly.

Mutation testing injects small defects (mutants) such as flipping > to >= or removing a call, and re-runs tests. A mutant that no test fails on has "survived", revealing a weak assertion. PIT (Pitest) is the main JVM tool.

• Mutation score = killed / total mutants, a better quality proxy than coverage.
• Slow, so run on changed classes or nightly (withHistory, scmMutationCoverage).
• Equivalent mutants (behaviour unchanged) cause false survivors.
• Plugin for JUnit 5: pitest-junit5-plugin.

WireMock runs a real HTTP server with stubbed endpoints, so the full client stack (serialization, timeouts, retries, TLS) is exercised. MockRestServiceServer replaces the RestTemplate request factory in-process and is faster but skips the network layer.

• WireMock supports fault injection (delays, connection reset) to test resilience.
• @RegisterExtension WireMockExtension with a dynamic port; point base URL at it.
• Verify requests with verify(postRequestedFor(urlEqualTo("/pay"))).

Service classes with constructor injection should be tested as plain Java with Mockito and no Spring; slices are for verifying framework behaviours such as mapping, validation, transactions and serialization.

• Constructor injection makes new OrderService(repo, clock) possible without reflection.
• @Transactional on a service only works through the Spring proxy, so a plain unit test cannot verify transactional behaviour.
• Self-invocation and private methods also bypass proxies.

JUnit does not guarantee method order unless you set @TestMethodOrder. Surefire runs unit tests (*Test, *Tests, Test*) in the test phase; Failsafe runs *IT/*ITCase in integration-test and checks results in verify, so teardown still happens when tests fail.

• Run only integration tests: mvn verify -DskipUTs style flags or profiles.
• Gradle uses separate source sets and tasks for integration tests.
• Tests that rely on order should be merged into one scenario test.

Inject the source: a Random with a fixed seed, a Supplier<UUID>, or an IdGenerator interface. Assert on properties (format, uniqueness) when exact values are not needed.

• new Random(42) is deterministic for a given JDK algorithm.
• For hashing and ordering tests, use fixed fixtures.
• Log the seed when using randomized or property-based tests (jqwik) so failures are reproducible.

With MockitoExtension (strict stubs) the call findById(2L) raises PotentialStubbingProblem because the mock was stubbed for different arguments. Without strictness it silently returns Optional.empty() (Mockito's default for Optional) and the test fails later with a confusing message.

• The strict message lists the stubbed and actual arguments, pointing straight at the mismatch.
• If the stub is never used, UnnecessaryStubbingException is reported at the end.

List<String> real = new ArrayList<>();
List<String> spy = spy(real);
spy.add("a");
System.out.println(real.size() + " " + spy.size());

Output: 0 1. spy() copies the instance, so real is untouched and only the spy's own state changes.

• To observe state on the original, assert on the spy itself.
• when(spy.get(0)).thenReturn("x") on an empty list throws IndexOutOfBoundsException because it calls the real get(0); use doReturn("x").when(spy).get(0).

Move each stub into the tests that need it, or mark shared ones lenient(). Moving is better since it keeps tests self-explanatory; lenient() is acceptable for truly common defaults.

• Do not disable strictness globally; unused stubs are real dead code and often hide a bug (the code path was never executed).
• Alternative: build a helper method stubHappyPath() called explicitly.

CSRF protection is on by default in Spring Security, and @WebMvcTest includes the security filter chain. Add .with(csrf()) to the request or disable CSRF in the security config for stateless APIs.

mvc.perform(post("/orders").with(csrf())
        .contentType(MediaType.APPLICATION_JSON).content("{}"))
   .andExpect(status().isCreated());

• If the role is wrong you would get 403 too; with no authentication at all, 401 (or a redirect to login for form login).

The slice does not component-scan @Service beans. Declare @MockBean/@MockitoBean UserService service; or @Import a real implementation and its dependencies.

• Do not switch to @SpringBootTest just to silence this; you lose the speed of the slice.
• If the controller needs many beans, that may indicate it is doing too much.

H2 differs in SQL dialect, JSON/array types, locking, case handling and constraint behaviour. Run @DataJpaTest against a Testcontainers PostgreSQL with @AutoConfigureTestDatabase(replace = Replace.NONE), using the same Flyway migrations.

@DataJpaTest
@AutoConfigureTestDatabase(replace = Replace.NONE)
@Testcontainers
class UserRepoTest {
    @Container @ServiceConnection
    static PostgreSQLContainer<?> pg = new PostgreSQLContainer<>("postgres:16");
}

• H2 MODE=PostgreSQL narrows gaps but does not remove them.

The test method's transaction keeps the persistence context open, so lazy associations load at any point. In production the service transaction ends and the entity is detached before the view/serializer touches the lazy field.

• Fix the code (fetch join, @EntityGraph, DTO projection) and make the test expose it: remove test @Transactional, or call entityManager.flush(); entityManager.clear(); before asserting, or run via the real service boundary.
• Same effect hides missing flushes and constraint violations until commit.

The HTTP request is handled by a server thread with its own transaction that commits; the test-managed transaction on the test thread does not cover it, so rollback never undoes those writes.

• Clean up explicitly: @Sql cleanup script, truncating in @AfterEach, or Testcontainers per class.
• With MOCK environment and MockMvc the request runs on the test thread and the rollback does work.

Spring caches application contexts by configuration key. Each distinct combination of @MockBeans, @TestPropertySource, active profiles or @DirtiesContext produces a new context, which must be started again.

• Consolidate mocks in a shared abstract base class or a @TestConfiguration so many classes use one key.
• Prefer slices (@WebMvcTest) and plain unit tests to reduce @SpringBootTest count.
• Check the log line "Started ... in" count, and enable context cache logging (logging.level.org.springframework.test.context.cache=DEBUG).

Replace the sleep with polling for the observable outcome using Awaitility; it returns as soon as the condition holds and fails only after a timeout.

publisher.send(event);
await().atMost(Duration.ofSeconds(5))
       .pollInterval(Duration.ofMillis(50))
       .untilAsserted(() -> assertThat(store.find(event.id())).isPresent());

• A fixed sleep is simultaneously slow on fast machines and too short on slow ones.
• If possible make the executor injectable and synchronous in tests.

The code depends on the real current date. Inject Clock into the class, call LocalDate.now(clock), and construct the test with Clock.fixed(...) for the boundary case you want, such as 31 January.

• Add tests for edge dates: month end, leap day 29 Feb, DST change, year boundary.
• Avoid ZoneId.systemDefault() in code and tests; use an explicit zone.

@ParameterizedTest
@CsvSource({"1,2,3", "2,2,4", "5,5,11"})
void adds(int a, int b, int sum) { assertEquals(sum, a + b); }

The test runs three invocations; the first two pass and the third fails (5 + 5 = 10, not 11). The report shows 2 passed, 1 failed with the failing row's arguments; the other rows are not affected.

• Display names default to [3] 5, 5, 11.
• @CsvSource converts strings to int implicitly.

mockStatic registers a thread-local mock on the creating thread. If it is not closed, the static stays mocked for later tests on that thread, and the next mockStatic of the same class throws "static mocking is already registered in the current thread".

try (MockedStatic<Files> f = mockStatic(Files.class)) {
    f.when(() -> Files.exists(any())).thenReturn(true);
    // code under test
}  // closed here, real behaviour restored

• Use try-with-resources or @AfterEach close; never create in @BeforeAll shared across parallel tests.
• Mocking JDK classes broadly (Files, System) can break the test framework itself.

Best: refactor to inject the client or a factory. Fallback: mockConstruction(HttpClient.class, (mock, ctx) -> when(mock.send(...)).thenReturn(resp)) intercepts constructors invoked within the scope of the try block.

• mockConstruction also works with the inline mock maker only.
• Hard-to-test code is a design signal: new-ing collaborators inside methods couples the class to their implementation.
• For HTTP specifically, point the real client at WireMock.

any() accepts everything, so the verification is vacuous. Capture the argument and assert on fields, or use argThat with a precise predicate.

var cap = ArgumentCaptor.forClass(Email.class);
verify(emailService).send(cap.capture());
assertThat(cap.getValue().to()).isEqualTo("ann@x.com");

• If Email implements equals, verify(emailService).send(expectedEmail) is simplest.

Shared mutable state leaks between tests: static fields or singletons, cached Spring context mutated by a test, leftover database rows, system properties, default Locale/TimeZone, files in a shared temp dir, or unclosed static mocks.

• Reproduce with the failing pair and random order (junit.jupiter.testmethod.order.default=...Random, Surefire runOrder=random).
• Bisect by running subsets; print state in @AfterEach.
• Fix by resetting in @BeforeEach/@AfterEach, or by removing the global state.

Parallel execution exposes the shared mutable static. Remove the sharing (instance field, new per test), or protect with @ResourceLock("LIST"), or force @Execution(SAME_THREAD) for that class.

• Default instance-per-method lifecycle already gives each test a fresh instance, so use instance fields.
• Fixtures on shared DB rows or ports need the same treatment: unique data per test.

when(repo.find(anyLong(), "ACTIVE")).thenReturn(user);

It throws InvalidUseOfMatchersException: matchers and raw values cannot be mixed in a single call. Write when(repo.find(anyLong(), eq("ACTIVE"))).

• Mockito registers matchers on a stack as they are evaluated; mixed use makes the count mismatch the parameter count.
• A stray matcher in a previous test line may produce misattributed errors at a later verify call.

Stub the mock to throw in one test and return normally in another, then assert the result for each.

@Test void fallsBackWhenRemoteFails() {
    when(client.rate("USD")).thenThrow(new RuntimeException("down"));
    assertEquals(1.0, service.rate("USD"));
}
@Test void usesRemoteRate() {
    when(client.rate("USD")).thenReturn(0.9);
    assertEquals(0.9, service.rate("USD"));
}

• Only checked exceptions declared by the method can be thrown by thenThrow; otherwise Mockito reports "Checked exception is invalid for this method".

Join with a timeout and assert the result, or inject a direct/inline executor so the task completes on the calling thread.

var result = service.fetchAsync(1).get(2, TimeUnit.SECONDS);
assertEquals("ok", result);

• Test failure paths with assertThrows(ExecutionException.class, ...) and check getCause().
• Always use a timeout; plain get() can hang the build.
• Use Runnable::run as Executor for deterministic tests; mock futures with CompletableFuture.completedFuture/failedFuture.

Start N threads behind a latch so they run together, repeat many increments, then assert the final total.

var counter = new UnsafeCounter();
var start = new CountDownLatch(1);
var pool = Executors.newFixedThreadPool(8);
for (int i = 0; i < 8; i++)
    pool.submit(() -> { start.await(); for (int j = 0; j < 10_000; j++) counter.inc(); return null; });
start.countDown(); pool.shutdown(); pool.awaitTermination(5, TimeUnit.SECONDS);
assertEquals(80_000, counter.get());

With a non-atomic count++ the assertion typically fails with a lower number; a correct AtomicInteger always passes.

• A pass does not prove safety; use jcstress or review the memory model.
• Shut down pools in a finally/@AfterEach to avoid leaking threads.

Extract the job body into a method (processDueInvoices(Instant now)), unit test that with a fixed Clock, and trust the framework for triggering. Add one small integration test verifying that the cron expression is valid (CronExpression.parse) and the bean is registered.

• Avoid waiting for real cron times in tests.
• Awaitility with a fixedDelay of a few ms property override is an option for wiring tests.
• Distributed locks (ShedLock) are tested with an integration test and a real DB.

Introduce a test data builder (or Object Mother returning a builder) with valid defaults, so constructor changes affect one place, and each test states only the fields relevant to its scenario.

• The test intent improves: aUser().withAge(17).build() says what matters.
• Keep builders in src/test, not production.
• Combine with Instancio or EasyRandom for large graphs if exact values are irrelevant.

Use WireMock fault injection: fixed delay longer than the client timeout, Fault.CONNECTION_RESET_BY_PEER, or scenario states that return 503 twice then 200.

stubFor(get("/rate").inScenario("retry").whenScenarioStateIs(STARTED)
    .willReturn(serverError()).willSetStateTo("second"));
stubFor(get("/rate").inScenario("retry").whenScenarioStateIs("second")
    .willReturn(ok("0.9")));

Assert the final result is 0.9 and verify(2, getRequestedFor(urlEqualTo("/rate"))).

• Keep timeouts small in test config to keep suites quick.
• Check that non-idempotent requests (POST) are not retried blindly.

Share one container across classes: the singleton container pattern (static field in an abstract base class started once, closed by Ryuk at JVM exit), or Spring Boot's @ServiceConnection on a bean in a shared @TestConfiguration.

• Reset data between tests rather than restarting the DB (truncate or per-test schema/template DB).
• withReuse(true) plus testcontainers.reuse.enable=true keeps containers across runs locally; do not use in CI.
• Use a lighter image tag and start dependent containers in parallel with Startables.deepStart.

CI runner has no reachable Docker daemon. Provide Docker (privileged runner, DinD sidecar, or a runner with the socket) or the Testcontainers Cloud agent, and make sure DOCKER_HOST is set when needed.

• Mark such tests with @Testcontainers(disabledWithoutDocker = true) for optional environments, but do not let CI silently skip them.
• Pull-rate limits on public registries: use a mirror and set hub.image.name.prefix.

Hibernate delays SQL until flush. The test transaction rolls back and never flushes, so the constraint is not checked. Call repo.saveAndFlush(entity) or entityManager.flush() inside assertThrows(DataIntegrityViolationException.class, ...).

• With GenerationType.IDENTITY the insert is executed immediately, so the behaviour differs by id strategy.
• Clear the persistence context to verify reload from the DB rather than the first-level cache.

assertThat(list.contains("a"));

Nothing is asserted: assertThat(boolean) returns an assert object and no terminal method is called, so the test always passes. Use assertThat(list).contains("a") for a descriptive failure message.

• Static analysis (Error Prone, SonarQube) can flag dangling assertThat.
• Also avoid assertTrue(list.contains("a")) since the failure message is just "expected true".

Use EqualsVerifier, which checks reflexivity, symmetry, transitivity, consistency, null handling and the hashCode contract, including subclass and mutable-field pitfalls.

EqualsVerifier.forClass(Money.class).verify();

• Hand-written asserts miss cases such as symmetry with subclasses or null fields.
• JPA entities need .suppress(Warning.SURROGATE_KEY) or specific config depending on the strategy.

Coverage as a target gets gamed. Switch to meaningful signals: branch coverage on changed code (diff coverage), mutation score via PIT on critical modules, and code review of test intent.

• Run PIT in CI nightly; surviving mutants list exactly the weak assertions.
• Remove coverage gates on trivial code; keep a floor, not a target.
• Add assertion-less test detection via Sonar.

No test exercises the boundary value 18, so the test suite cannot distinguish >= from >. Add a test (or parameterized row) with age exactly 18 expecting adult.

@ParameterizedTest
@CsvSource({"17,false", "18,true", "19,true"})
void adultBoundary(int age, boolean expected) { assertEquals(expected, rules.isAdult(age)); }

• Boundary-value analysis is the general fix for "conditional boundary" mutants.

Inject a Supplier<UUID> (or IdGenerator) via the constructor; production passes UUID::randomUUID, tests pass () -> FIXED.

class OrderFactory {
    private final Supplier<UUID> ids;
    OrderFactory(Supplier<UUID> ids) { this.ids = ids; }
    Order create() { return new Order(ids.get()); }
}

• Same technique for Clock, Random, System.getenv.
• It avoids the thread-local pitfalls of mockStatic.

@InjectMocks uses constructor, then setter/field injection; if the target has two constructor args and only one @Mock exists, the missing one is null. Field injection by type is ambiguous with two mocks of the same type, so Mockito uses the field name.

• Spring wiring (@Value, @Autowired by qualifier, proxies, @PostConstruct) does not run, so values stay default.
• Create the object explicitly: new Service(repo, clock); then no injection surprises exist.

Use ApplicationContextRunner (no full context) or @SpringBootTest(classes = ..., properties = ...); or @EnableConfigurationProperties in a minimal slice.

new ApplicationContextRunner()
    .withUserConfiguration(AppConfig.class)
    .withPropertyValues("app.timeout=5s")
    .run(ctx -> assertThat(ctx.getBean(AppProps.class).timeout())
                    .isEqualTo(Duration.ofSeconds(5)));

• Test validation failures: run(ctx -> assertThat(ctx).hasFailed()).
• Same runner tests conditional auto-configuration.

Unit test the handler logic with plain objects; for wiring, run a Kafka Testcontainer (or @EmbeddedKafka), publish a record with KafkaTemplate, and use Awaitility to assert the effect, since consumption is asynchronous.

• Use unique topic and group names per test (or a fresh container) to avoid cross-test offsets.
• Set auto.offset.reset=earliest for the test consumer so it sees the record.
• Test idempotency by sending the same record twice and the dead-letter path with a poison message.

When the main risk is interface drift (field renamed, status code changed) and the services are owned by different teams. Contract tests run independently in each pipeline in seconds, while E2E needs both deployed and is slow and flaky.

• Keep a few E2E smoke tests for critical journeys.
• Pact can-i-deploy and provider verification on consumer pact changes catch breakage before release.
• Contracts should assert structure and essential values with matchers, not exact data.

Provider verification failed because the provider no longer satisfies the consumer's expectation (or the consumer added a new one). Decide who is right: if the consumer needs the header, the provider adds support; if the provider changed incompatibly, it must stay backward compatible (add, deprecate, then remove) before verification passes.

• Use provider states to set up data (given("user 1 exists")).
• Pending pacts and WIP pacts stop new consumer expectations from failing the provider build unexpectedly.

Use jsonPath or content().json(expected, strict) (JSONassert) rather than string equality, so field order and whitespace do not matter.

mvc.perform(get("/users/1"))
   .andExpect(status().isOk())
   .andExpect(jsonPath("$.name").value("Ann"))
   .andExpect(jsonPath("$.roles", hasSize(2)));

• content().json(str) is lenient by default (extra fields allowed); pass true for strict.
• MvcResult plus ObjectMapper lets you deserialize into a DTO and use AssertJ.

Send an invalid payload through MockMvc in @WebMvcTest; MethodArgumentNotValidException is handled by the @ControllerAdvice (also in the slice) or default handler, giving status 400.

mvc.perform(post("/users").contentType(APPLICATION_JSON)
    .content("{\"email\":\"bad\"}"))
   .andExpect(status().isBadRequest())
   .andExpect(jsonPath("$.errors[0].field").value("email"));

• Unit-test the validator itself with Validation.buildDefaultValidatorFactory() for custom constraints.
• Missing @Valid means no validation: the test would return 2xx and expose it.

Mockito's RETURNS_DEFAULTS returns empty collections (Map, List, Set), empty Optional/Stream, 0/false for primitives, and null for other object types. So getSettings() returning Map gives an empty map, not null, but a method returning a custom Config gives null and may NPE.

• Stub explicitly rather than relying on defaults; hidden defaults make tests misleading.
• RETURNS_SMART_NULLS improves the failure message for such NPEs.

Use verify(mock, times(1)).send(eq("a")) per argument, or verify(mock, times(3)).send(anyString()) for the total, and capture values for the set check.

verify(notifier, times(3)).send(captor.capture());
assertThat(captor.getAllValues()).containsExactlyInAnyOrder("a", "b", "c");

• Plain verify(notifier).send(anyString()) fails with TooManyActualInvocations for 3 calls.

String is a final JDK class and mocking it is rejected or fragile, and mocking any simple value object is pointless: use real instances ("abc", new Money(10)). Mock only collaborators with behaviour or I/O.

• Rule of thumb: do not mock what you own if cheap to construct, and do not mock types you do not own (wrap them).
• Over-mocking produces tests that restate the implementation.

Later tests see leftover state (cache entries, counters, in-memory queues) because singleton beans are shared across cached contexts. Fix by resetting the state in @AfterEach (cache.clear()), using @MockBean resets, or as a last resort @DirtiesContext for that class.

• @DirtiesContext forces context rebuild after the class or method, costing seconds.
• Design beans so tests can reset them explicitly.

Load a context with method security enabled (@SpringBootTest or a slice with @EnableMethodSecurity imported) and annotate the test with @WithMockUser(roles = "ADMIN") for the success case; for the other, expect AccessDeniedException.

@Test @WithMockUser(roles = "USER")
void deniesUser() { assertThrows(AccessDeniedException.class, () -> service.purge()); }

• A plain new Service() unit test will never apply @PreAuthorize because it relies on the Spring proxy.

Treat it as a real bug until proven otherwise: log the seed on failure, replay it, and fix either the code (e.g. unhandled edge value) or the test (unfounded assumption). Make tests deterministic by seeding or by passing explicit values.

• Property-based frameworks (jqwik) print the failing seed and shrink inputs.
• Do not simply rerun and ignore.

Extract setup into builders and small helper methods with intention-revealing names, keep arrange/act/assert visible in each test, and prefer a bit of duplication (DAMP) over clever shared fixtures (DRY) so a failure is readable alone.

• Use @Nested to group shared context.
• Avoid inheritance chains of test base classes with hidden state.
• Custom AssertJ assertions (assertThat(order).isPaid()) express domain checks.

Measure first, then cut context starts and external waits.

• Count distinct contexts; consolidate @MockBean sets and profiles; use slices and plain unit tests where a full context is unneeded.
• Share one Testcontainers instance; truncate data rather than restart.
• Run Surefire/Failsafe with parallel forks and JUnit parallel where tests are isolated.
• Lazy initialization (spring.main.lazy-initialization=true) in tests.
• Replace sleeps with Awaitility; run only affected modules in PRs and the full suite on merge.

An unstubbed save returns null, causing an NPE. Stub with an Answer that mimics JPA by assigning the id and returning the argument.

when(repo.save(any(Order.class))).thenAnswer(inv -> {
    Order o = inv.getArgument(0);
    o.setId(42L);
    return o;
});

• Alternatively use a fake in-memory repository for several tests.
• Do not blindly return the same argument unless the code does not depend on generated fields.

Assert on the observable consequence (returned fallback, metric, retry call) and optionally capture logs with a Logback ListAppender or OutputCaptureExtension. Swallowed exceptions are a design smell: consider returning a result type or rethrowing.

var appender = new ListAppender<ILoggingEvent>(); appender.start();
((Logger) LoggerFactory.getLogger(Job.class)).addAppender(appender);
job.run();
assertThat(appender.list).extracting(ILoggingEvent::getLevel).contains(Level.ERROR);

Use @TempDir Path dir so each test writes into an isolated, auto-deleted directory, and accept a Path or FileSystem in the code under test.

@Test void writesReport(@TempDir Path dir) throws IOException {
    Path out = dir.resolve("r.txt");
    writer.write(out, "hi");
    assertEquals("hi", Files.readString(out));
}

• Avoid hard-coded paths and /tmp names that collide in parallel runs.
• In-memory file systems (Jimfs) can simulate Windows/Unix differences.

Distribute by risk and cost.

• Unit: pricing, discount and validation rules in the domain (plain JUnit, no mocks where possible).
• Service unit tests with Mockito for orchestration branches (payment failure, out of stock).
• @WebMvcTest: request validation, status codes, JSON mapping, security rules.
• @DataJpaTest with Testcontainers: repository queries and constraints.
• One or two @SpringBootTest integration tests of the happy path plus a rollback path with real transactions.
• Contract test for the payment provider API; one E2E smoke test.

Start with characterization tests that pin current behaviour (often at a higher level), then create seams with small safe refactorings (extract method, introduce constructor-injected interface, wrap statics) and move to finer unit tests.

• Use mockStatic/mockConstruction temporarily to get a test in place, then remove them with the refactor.
• Approval/snapshot tests (ApprovalTests) quickly capture complex outputs.
• Refactor only under a green test, one step at a time (Michael Feathers' "Working Effectively with Legacy Code").

It fails: 0.1 + 0.2 is 0.30000000000000004. Use a delta overload assertEquals(0.3, 0.1 + 0.2, 1e-9), or AssertJ isCloseTo(0.3, within(1e-9)); for money use BigDecimal with compareTo or isEqualByComparingTo.

• assertEquals(BigDecimal("2.0"), BigDecimal("2.00")) also fails since scale differs under equals.

assertThrows(RuntimeException.class, ...) passes for any runtime exception, including an unrelated NullPointerException from a bug in the test setup. Assert the specific type and message or cause, and keep the lambda to the single statement under test.

var ex = assertThrowsExactly(InsufficientFundsException.class,
    () -> account.withdraw(500));
assertEquals(100, ex.getShortfall());

• Put arrange code outside the lambda so setup errors fail clearly.

Either generate a signed token with a test key and send it as a Bearer header via TestRestTemplate/WebTestClient, or in MockMvc use jwt() post-processor to skip signature validation while testing authorities.

mvc.perform(get("/me").with(jwt().authorities(new SimpleGrantedAuthority("SCOPE_read"))))
   .andExpect(status().isOk());

• Use a mock JWK/issuer (WireMock or Keycloak container) for full-flow tests of decoding and signature.
• Test expired and wrong-audience tokens produce 401.

Differences in classpath, working directory, JVM args, locale/time zone, test order or parallelism, unsynchronized shared state, or the test not following Surefire's naming conventions (so not run at all).

• IDE may compile resources differently; Maven filters resources or uses profile properties.
• Set -Duser.timezone and file.encoding consistently via argLine.
• Run mvn -Dtest=MyTest test to reproduce; check target/surefire-reports.
• Mockito inline agent warnings or Java version mismatch between IDE and Maven toolchain.

Prefer a fake (in-memory map-backed repository) when many tests exercise save-then-read flows: tests stay about outcomes, stubs are not repeated, and refactoring call patterns does not break them.

• Use mocks for interaction-only boundaries such as email, payment gateways or message publishers.
• A fake needs its own tests or contract tests to ensure it behaves like the real implementation.
• Spring Data repositories are interfaces, so a fake needs full implementation of the used methods.

No. Default to plain unit tests for logic, add slices for web/persistence layers, and keep a small set of @SpringBootTest tests for end-to-end wiring.

• Full-context tests start slowly, fail with large unrelated diffs and give vague failures.
• A slice test fails only when its layer is wrong, so diagnosis is faster.
• Keep one smoke test that the context loads (contextLoads) to catch wiring problems.