JUnit 5 Tutorial for Beginners With Maven and Gradle
Add JUnit 5 to a Maven or Gradle project, write a first test, run it from the command line and read the output, in about fifteen minutes.

JUnit 5 is the standard test framework for Java, and getting a first test to run takes one dependency and one class. The hard part for a beginner is not the test; it is the build file around it, where one missing line produces a green build that ran nothing. This tutorial builds a tiny Money class and its tests on JDK 25 with both Maven and Gradle, runs them, breaks one on purpose to learn to read a failure and points to what to learn next. Afterwards, the JUnit 5 handbook covers the rest of the framework, and a practical Java testing strategy covers what to test.
Create the project
With Maven, a minimal pom.xml is enough.
<project xmlns="http://maven.apache.org/POM/4.0.0">
<modelVersion>4.0.0</modelVersion>
<groupId>dev.javahacks</groupId>
<artifactId>junit-demo</artifactId>
<version>1.0</version>
<properties>
<maven.compiler.release>25</maven.compiler.release>
</properties>
<dependencies>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter</artifactId>
<version>5.13.4</version>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<artifactId>maven-surefire-plugin</artifactId>
<version>3.5.4</version>
</plugin>
</plugins>
</build>
</project>With Gradle in the Kotlin DSL, the equivalent is shorter.
plugins { java }
repositories { mavenCentral() }
dependencies {
testImplementation("org.junit.jupiter:junit-jupiter:5.13.4")
testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}
tasks.test { useJUnitPlatform() }Both files use the aggregate artifact junit-jupiter, which brings the API for writing tests, the engine that runs them and the parameterised-test support in one dependency. The test scope in Maven and testImplementation in Gradle keep JUnit out of the production jar. Pinning the Surefire version matters in Maven, because an old default plugin does not recognise JUnit 5. The Gradle line useJUnitPlatform() is the one beginners forget; without it Gradle runs no JUnit 5 tests and reports success, the symptom described in tests not running in Maven and, for Gradle, in running JUnit 5 from Gradle.
Write the class under test
package dev.javahacks;
public record Money(long cents, String currency) {
public Money plus(Money other) {
if (!currency.equals(other.currency)) {
throw new IllegalArgumentException("currency mismatch");
}
return new Money(cents + other.cents, currency);
}
}Money is stored as whole cents in a long, which avoids the rounding errors of double. The record gives you a constructor, accessors, equals, hashCode and toString for free, and the compact design leaves one behaviour worth testing: adding two amounts, and refusing to mix currencies.
Write the first test
package dev.javahacks;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
import org.junit.jupiter.api.Test;
class MoneyTest {
@Test
void addsAmountsInTheSameCurrency() {
Money total = new Money(250, "USD").plus(new Money(150, "USD"));
assertEquals(new Money(400, "USD"), total);
}
@Test
void rejectsDifferentCurrencies() {
assertThrows(IllegalArgumentException.class,
() -> new Money(1, "USD").plus(new Money(1, "EUR")));
}
}The class and its methods are package-private, which Jupiter allows; unlike JUnit 4, nothing needs to be public. The @Test annotation marks a method as a test, and the file lives under src/test/java in the same package as the class it exercises. The record's generated equals is what lets the first assertion compare two Money values by content. Each test follows the same shape: arrange the inputs, act by calling the method, assert on the outcome. Method names describe behaviour in plain words, so a failing report reads like a sentence.
Run it
mvn testgradle testIn Maven you will see a summary like Tests run: 2, Failures: 0, Errors: 0, Skipped: 0 and BUILD SUCCESS. Gradle prints BUILD SUCCESSFUL and writes an HTML report to build/reports/tests/test/index.html. To run a single class in Maven, use mvn -Dtest=MoneyTest test. If the summary says Tests run: 0, the build is green and nothing ran, and the cause is almost always one of the two build-file lines described above.
See a failure on purpose
Change the expected value to new Money(401, "USD") and run again. The failure message prints both values.
org.opentest4j.AssertionFailedError: expected: <Money[cents=401, currency=USD]> but was: <Money[cents=400, currency=USD]>Reading that output is the skill that matters most in the first week. The expected value comes first in assertEquals, so the message labels each side correctly; swap the arguments and the message lies, and you will debug the wrong side. Break the second test too, by removing the check in plus, and see that assertThrows fails with a message saying no exception was thrown. Put the correct code back afterwards.
What to learn next
Tests that differ only in their input want @ParameterizedTest. Shared setup wants @BeforeEach, covered in lifecycle annotations and execution order. Readable failures want better assertions, in readable assertions. The commands for the build tools themselves are in the Maven tutorial for beginners.
Keeping tests next to the code they test
Put tests in the same package as the class, under src/test/java, so package-private members are reachable and a rename moves both. Name the test class after the subject with a Test suffix, and Surefire and Gradle both find it by default. Avoid sharing mutable state between tests: JUnit creates a new instance of the class for each method, so a field set in one test is gone in the next, which keeps tests independent.
A habit worth starting on day one
Write the test before or with the code. After the failing run in the section above, change one line of the production code and watch the test go red, then fix it. That loop teaches more than any explanation. Commit the test with the code it covers, and let CI run mvn test or gradle test on every push, so a teammate sees the same result you do.
Understanding the build output
Both tools print more than the pass count. Maven lists the plugin goals it ran, and the surefire:test line is the one that ran your tests; if it is missing, the phase never reached it. Gradle prints a task graph with > Task :test, and shows UP-TO-DATE when nothing changed since the last run, which is a feature, not a bug: add --rerun to force the tests. Open the HTML report once. It shows each test method, how long it took and the output of failures, and it is the page you will share when asking a teammate for help.
Common beginner errors
A cannot find symbol on Test means the dependency is missing or has the wrong scope, and the import line shows red in the IDE. No tests found in Gradle is the missing useJUnitPlatform(). A test that passes in the IDE and fails on the command line often depends on the working directory or on a file the IDE found for you, so keep test resources under src/test/resources and load them from the classpath. And a test class named MoneyTests with an s is still found by Gradle but not by an older Surefire default, so stay with the Test suffix.
When this setup is too small
A real project adds Mockito for collaborators, AssertJ for fluent assertions and a coverage plugin. A Spring Boot project gets the first two from spring-boot-starter-test. The JUnit user guide has the full list of annotations, and the Maven Surefire documentation explains the test selection options.


