java-junit

Java Testing with JUnit 5/6, AssertJ and Mockito

Framework-neutral guidance for fast, deterministic unit tests. For Spring slices use spring-boot-testing (if installed); for real databases/brokers in Docker use java-testcontainers; for failures you cannot explain, java-debugging.

First: detect, don't impose

1. Read pom.xml/build.gradle*: JUnit version (junit-jupiter, junit-bom, or inherited from a Spring Boot BOM), assertion library, Mockito, Surefire/Failsafe versions, Java release.
2. Copy the conventions already in src/test/java (naming, assertion library, static imports, mocking style). Do not introduce AssertJ, Mockito or JaCoCo into a project that lacks them without asking.
3. Never bump the JUnit major version implicitly; upgrading is its own task (see java-upgrade if installed).

JUnit 5 vs JUnit 6

Source: JUnit 6.0.0 release notes (<https://docs.junit.org/6.0.0/release-notes.html>). Read the notes for the target version (<https://docs.junit.org/current/release-notes/>) and prefer them over this table. JUnit 4 tests need the Vintage engine; do not mix org.junit.Test and org.junit.jupiter.api.Test in one class.

Dependencies (same for 5 and 6; verified with Maven and Gradle): import org.junit:junit-bom, then declare org.junit.jupiter:junit-jupiter (aggregates api, params, engine) with test scope. Gradle 9 additionally requires testRuntimeOnly("org.junit.platform:junit-platform-launcher") (verified: without it the test executor fails with "Failed to load JUnit Platform") and tasks.test { useJUnitPlatform() }. Maven needs Surefire 3.x (verified with 3.6.0).

Assertions

Match the project's library. Plain Jupiter rules: expected value first, lazy Supplier messages, assertAll, assertThrowsExactly, timeouts. (The separate instructions/java-junit5-assertions.instructions.md resource has the longer version but is not installed with this skill.) If the project uses AssertJ, prefer it for collections, strings and exceptions; patterns (soft assertions, assertThatThrownBy, extracting, containsExactly, usingRecursiveComparison) are in references/assertj-and-mockito.md.

• Assert on outcomes and state, not on how many times internals were called.
• Compare values; avoid bare assertNotNull.
• Never catch AssertionError/Exception to make a test pass.

Mocking (Mockito)

• Mock collaborators across a boundary (repository, HTTP client, clock, message sender). Do not mock value objects, records, collections, String, or the class under test; use real instances or simple fakes.
• Prefer a hand-written fake over a mock when the interaction is stateful.
• Use @ExtendWith(MockitoExtension.class) with @Mock/@InjectMocks/@Captor. Strict stubs are the default there, so an unused stub fails the test (UnnecessaryStubbingException). Fix the test; relax with @MockitoSettings(strictness = Strictness.LENIENT) only for a justified shared setup.
• Mockito 5 uses the inline mock maker by default. On JDK 21+ it may self-attach and print a dynamic-agent warning. With Mockito 5.14.0+, register mockito-core as a -javaagent instead (setup for Maven and Gradle in references/assertj-and-mockito.md, verified on JDK 21 and 25). Check the resolved version first: earlier 5.x jars lack Premain-Class and cannot be used as the agent. Ask before upgrading; otherwise use the instrumentation setup documented for the installed version.
• Mockito 5 requires Java 11+. Its default inline mock maker does not work on GraalVM native image, where the subclass mock maker is appropriate (Mockito 5.0.0 release notes, <https://github.com/mockito/mockito/releases/tag/v5.0.0>).
• Avoid mockStatic/mockConstruction; wrap the static call behind an interface.

Determinism

• Time: inject java.time.Clock (Clock.fixed(...)) and call Instant.now(clock); avoid Instant.now()/LocalDate.now() in code under test.
• Randomness: inject a Random/RandomGenerator with a fixed seed; log the seed if generated.
• Do not depend on default locale, time zone, file encoding, network, or wall-clock sleeps. Set them explicitly (newer 6.x releases add built-in locale/time-zone/system-property extensions; check the release notes of your version, otherwise use try/finally).

Unit vs integration tests

Surefire defaults pick *Test, Test*, *Tests, *TestCase; Failsafe picks *IT, IT*, *ITCase. Failsafe needs the integration-test and verify goals bound and is run by mvn verify, not mvn test. Alternatively split by @Tag. For databases and brokers see java-testcontainers; for Spring slices see spring-boot-testing. Full build snippets: references/build-setup.md.

Coverage and mutation testing (optional)

• JaCoCo: add only if the project uses it or the user asks. With Surefire/Failsafe use <argLine>@{argLine} ...</argLine> so the JaCoCo agent is not overwritten.
• Coverage is a smell detector, not a goal; never add assertion-free tests to raise a number, and do not add a coverage gate the project lacks.
• PIT (mutation testing) is slow; run it on changed classes only if the project already uses it or the user asks (see references/build-setup.md, which records a verified pitest-maven + JUnit 5 plugin run).

Agent guardrails

1. Never delete, comment out, @Disabled, weaken (looser assertion, wider tolerance, swallowed exception) or skip a failing test to get green. Find the cause.
2. Decide which side is wrong, the test or the production code. If the fix changes production behavior, stop and ask the user first; if the test encodes an obviously stale expectation, say so and propose the change.
3. Do not add -DskipTests, -Dmaven.test.skip, -x test or failIfNoTests=false to make a build pass.
4. Do not mock the class under test or assert on mock internals to "prove" correctness.
5. Run the narrowest test first, then the full build:

• Maven: mvn -q -Dtest=OrdersTest test (one method: -Dtest='OrdersTest#place_should_saveAndNotify_when_itemValid'), then mvn verify.
• Gradle: ./gradlew test --tests 'demo.OrdersTest', then ./gradlew check.

Prefer the project wrapper (./mvnw, ./gradlew) when present.

1. Flaky test: reproduce by rerunning, then remove the nondeterminism (time, order, shared state, async waits); do not add retries.
2. New code gets new tests beside the existing ones, in the same style: happy path, boundaries, error cases.

References

• references/assertj-and-mockito.md: AssertJ patterns, Mockito strictness/captors/agent setup, when not to mock.
• references/build-setup.md: Maven and Gradle (Kotlin DSL) setups for JUnit 5/6, Failsafe split, JaCoCo, PIT.