How to run Java tests with Maven

Run mvn test from a Maven project root before packaging, releasing, or handing a branch to CI so Java compile errors and unit-test failures stop the build early. The test phase uses the project pom.xml, test dependencies, and Maven plugins rather than a one-off IDE runner, so a passing result is easier to compare with CI output.

The test phase compiles main and test sources, then runs unit tests through Maven Surefire for common Java project packaging such as JAR and WAR builds. Surefire writes text and XML files under target/surefire-reports, which gives a second proof surface when terminal output is too long or CI collapses logs.

The commands assume Maven and a compatible JDK are already installed, the terminal is in the directory containing pom.xml, and the project keeps tests under src/test/java or another path already configured in the POM. Use mvn verify when integration tests are bound later in the lifecycle; mvn test is the smaller unit-test check that should finish before packaging.

1. Open a terminal in the project root that contains pom.xml.

   The usual Maven Java layout keeps application code under src/main/java and unit tests under src/test/java, but the POM can configure different source and test locations.

2. Confirm the Maven command and Java runtime that the project will use.

   $ mvn -version
   Apache Maven 3.9.11 (3e54c93a704957b63ee3494413a2b544fd3d825b)
   Maven home: /usr/share/maven
   Java version: 21.0.9, vendor: Eclipse Adoptium, runtime: /opt/java/openjdk
   Default locale: en, platform encoding: UTF-8
   OS name: "linux", version: "6.10.14-linuxkit", arch: "aarch64", family: "unix"

   If the Java version is not the one expected by the project, fix the active JDK before trusting the test result.

   Related: How to check the installed Java version on Linux

3. Run the Maven test phase.

   $ mvn test
   [INFO] Scanning for projects...
   [INFO] 
   [INFO] --------------------< com.example:maven-test-demo >---------------------
   [INFO] Building maven-test-demo 1.0.0
   [INFO]   from pom.xml
   [INFO] --------------------------------[ jar ]---------------------------------
   ##### snipped
   [INFO] --- surefire:3.6.0-M1:test (default-test) @ maven-test-demo ---
   [INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
   [INFO] 
   [INFO] -------------------------------------------------------
   [INFO]  T E S T S
   [INFO] -------------------------------------------------------
   [INFO] Running com.example.CalculatorTest
   [INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.026 s -- in com.example.CalculatorTest
   [INFO] 
   [INFO] Results:
   [INFO] 
   [INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
   [INFO] 
   [INFO] ------------------------------------------------------------------------
   [INFO] BUILD SUCCESS
   [INFO] ------------------------------------------------------------------------

   The first run on a fresh machine may download plugins and test dependencies before the test summary appears. The exact plugin version in the goal line depends on the project POM and Maven defaults.

4. Check the Surefire report files that Maven wrote for the test run.

   $ ls target/surefire-reports
   com.example.CalculatorTest.txt
   TEST-com.example.CalculatorTest.xml

   The XML file is useful for CI systems and test report parsers. The text file is easier to read from a terminal when confirming a local run.

5. Read the text report for a concise test count.

   $ cat target/surefire-reports/com.example.CalculatorTest.txt
   -------------------------------------------------------------------------------
   Test set: com.example.CalculatorTest
   -------------------------------------------------------------------------------
   Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.026 s -- in com.example.CalculatorTest

6. Re-run one test class when the full suite fails and the failing class is known.

   $ mvn -Dtest=CalculatorTest test
   [INFO] Scanning for projects...
   ##### snipped
   [INFO] Running com.example.CalculatorTest
   [ERROR] Tests run: 1, Failures: 1, Errors: 0, Skipped: 0, Time elapsed: 0.027 s <<< FAILURE! -- in com.example.CalculatorTest
   [ERROR] com.example.CalculatorTest.addsTwoNumbers -- Time elapsed: 0.018 s <<< FAILURE!
   org.opentest4j.AssertionFailedError: expected: <6> but was: <5>
           at com.example.CalculatorTest.addsTwoNumbers(CalculatorTest.java:11)
   
   [INFO] Results:
   [INFO] 
   [ERROR] Failures:
   [ERROR]   CalculatorTest.addsTwoNumbers:11 expected: <6> but was: <5>
   [INFO] 
   [ERROR] Tests run: 1, Failures: 1, Errors: 0, Skipped: 0
   [INFO] ------------------------------------------------------------------------
   [INFO] BUILD FAILURE
   [INFO] ------------------------------------------------------------------------
   [ERROR] Failed to execute goal org.apache.maven.plugins:maven-surefire-plugin:3.6.0-M1:test (default-test) on project maven-test-demo: There are test failures.
   [ERROR] 
   [ERROR] See /home/developer/app/target/surefire-reports for the individual test results.

   A BUILD FAILURE from Surefire returns a nonzero exit status. Do not hide that status with shell operators in CI unless the job intentionally collects failed-test artifacts before exiting.