The Maven Surefire Plugin is one of the most important plugins in the Maven ecosystem. It is used primarily for running unit tests in a Maven project. This guide will cover the setup and usage of the Maven Surefire Plugin, along with a practical example to help you get started.
The Maven Surefire Plugin is designed to execute unit tests during the build lifecycle. It is typically bound to the test phase of the Maven build lifecycle, ensuring that tests are run after the compilation and before the packaging of the project.
Latest Version
As of this writing, the latest version of the Maven Surefire Plugin is 3.0.0-M8. Using the latest version ensures access to the newest features and improvements.
To use the Maven Surefire Plugin, you need to configure it in your project's pom.xml file. Let's go through the steps to set up a Maven project with the Surefire Plugin.
Step 1: Create a Maven Project
Run the following command to create a new Maven project:
mvn archetype:generate -DgroupId=com.example -DartifactId=surefire-plugin-demo -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
This command will generate a simple Maven project with the following structure:
surefire-plugin-demo
|-- src
| |-- main
| | `-- java
| | `-- com
| | `-- example
| | `-- App.java
| `-- test
| `-- java
| `-- com
| `-- example
| `-- AppTest.java
|-- pom.xml
`-- target
Step 2: Add Maven Surefire Plugin Configuration
Navigate to the project directory and open the pom.xml file. Add the Maven Surefire Plugin configuration inside the <build> section:
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>surefire-plugin-demo</artifactId>
<version>1.0-SNAPSHOT</version>
<dependencies>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter-api</artifactId>
<version>5.8.2</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter-engine</artifactId>
<version>5.8.2</version>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>3.0.0-M8</version>
</plugin>
</plugins>
</build>
</project>
Explanation
Step 3: Create Unit Test
Create a unit test in the src/test/java directory. For example, create a file named AppTest.java:
package com.example;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertTrue;
public class AppTest {
@Test
void sampleTest() {
System.out.println("Running unit test...");
assertTrue(true);
}
}
Step 4: Build and Run Unit Tests
To build the project and run the unit tests, use the following command:
mvn clean test
After the build completes, the unit tests will be run during the test phase.
Step 5: Check Results
The output will include the results of the unit tests:
-------------------------------------------------------
T E S T S
-------------------------------------------------------
Running com.example.AppTest
Running unit test...
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.001 sec
Results :
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
The Maven Surefire Plugin provides various configuration options to customize the behavior of your tests. Here are some commonly used configurations:
Specifying Test Includes/Excludes
You can specify which tests to include or exclude by adding the following configuration inside the <plugin> section:
<configuration>
<includes>
<include>**/*Test.java</include>
<include>**/*Tests.java</include>
<include>**/*TestCase.java</include>
</includes>
<excludes>
<exclude>**/*IntegrationTest.java</exclude>
</excludes>
</configuration>
Setting System Properties
You can set system properties that will be available to your tests:
<configuration>
<systemPropertyVariables>
<propertyName>propertyValue</propertyName>
<systemPropertyVariables>
</configuration>
Running Tests in Parallel
You can run tests in parallel to speed up the testing process:
<configuration>
<parallel>methods</parallel>
<threadCount>4</threadCount>
</configuration>
The Maven Surefire Plugin is an essential tool for running unit tests in a Maven project. By using this plugin, you can ensure that your unit tests are run during the build process, helping to maintain code quality and catch issues early. This guide provided a comprehensive overview of setting up and using the Maven Surefire Plugin, along with a practical example to help you get started. With this knowledge, you can effectively manage and run your unit tests in a Maven project.