Complete Guide to Maven Surefire Plugin
In this short tutorial, we are going to shed light on Maven Surefire plugin.
First, we will start with a little bit of insight into what is the Surefire plugin. Then, we are going to show how to configure this plugin to customize tests execution.
What is Maven Surefire Plugin?
Surefire is a special plugin used during the test phase of the default maven build lifecycle to run the tests of a project.
By default, it generates report files in XML/text format under the target/surefire-reports directory.
This plugin is called implicitly, though we can configure it explicitly in the pom.xml to add some sort of configuration options:
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>3.0.0-M5</version>
</plugin>
</plugins>
We can find the latest release of surefire here.
Please bear in mind that we need Maven 3.x and JDK 1.7 or higher to work with the surefire plugin.
Plugin Goals Overview
Maven Surefire plugin comes with two goals: test and help
The surefire:test goal, as the name indicates, is mainly used to execute tests with surefire.
To exemplify our goal, we will rely on the same project used in the Maven Spring Boot run article.
First, we need to create a new unit test:
@Test
public void myUnitTest() {
assertFalse(false);
}
Now, let’s execute the surefire:test goal:
C:\Users\Asus\GIT\spbootexample>mvn surefire:test
[INFO] Scanning for projects...
[INFO]
[INFO] --------------------< com.devwithus:spbootexample >---------------------
[INFO] Building spbootexample 0.0.1-SNAPSHOT
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- maven-surefire-plugin:2.22.2:test (default-cli) @ spbootexample ---
[INFO]
[INFO] -------------------------------------------------------
[INFO] T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.devwithus.spbootexample.SpbootexampleApplicationTests
...
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 4.048 s - in com.devwithus.spbootexample.SpbootexampleApplicationTests
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 19.362 s
[INFO] Finished at: 2021-08-26T16:30:56+02:00
[INFO] ------------------------------------------------------------------------
As shown above, our unit test is executed with surefire. By default, surefire generates a report file containing the tests execution results.
We can find it under target/surefire-reports:
more com.devwithus.spbootexample.SpbootexampleApplicationTests.txt
-------------------------------------------------------------------------------
Test set: com.devwithus.spbootexample.SpbootexampleApplicationTests
-------------------------------------------------------------------------------
Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 4.048 s - in com.devwithus.spbootexample.SpbootexampleApplicationTests
Please keep in mind that the test goal is called implicitly whenever a maven test goal is executed using mvn test or mvn install
The surefire:help goal, as the name implies, prints help information about the plugin and its goals:
C:\Users\Asus\GIT\spbootexample>mvn surefire:help
[INFO] Scanning for projects...
[INFO]
[INFO] --------------------< com.devwithus:spbootexample >---------------------
[INFO] Building spbootexample 0.0.1-SNAPSHOT
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- maven-surefire-plugin:2.22.2:help (default-cli) @ spbootexample ---
[INFO] Maven Surefire Plugin 2.22.2
Maven Surefire MOJO in maven-surefire-plugin.
This plugin has 2 goals:
surefire:help
Display help information on maven-surefire-plugin.
Call mvn surefire:help -Ddetail=true -Dgoal=<goal-name> to display parameter
details.
surefire:test
Run tests using Surefire.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1.639 s
[INFO] Finished at: 2021-08-26T15:19:30+02:00
[INFO] ------------------------------------------------------------------------
As we can see, we can use mvn surefire:help -Ddetail=true -Dgoal=
Configuration
The most interesting part about surefire is that it can work with the test frameworks such as JUnit and TestNG. It behaves in the same way no matter which framework is used.
By default, surefire will automatically scan src/test/java directory. Then it will pick up and execute all test filenames that start with Test or end with Test, Tests or, TestCase.
Include and Exclude Tests
We can configure the maven surefire plugin to include some test classes. For example, classes that do not follow naming conventions.
To do so, we can use the include namespace:
<plugin>
...
<configuration>
<includes>
<include>MyTestSample.java</include>
</includes>
</configuration>
</plugin>
Surefire provides another important namespace called exclude to exclude tests.
We can always choose to exclude classes that are causing the build to fail:
<plugin>
...
<configuration>
<excludes>
<exclude>MyTestSample.java</exclude>
</excludes>
</configuration>
</plugin>
Another important thing to mention is that include and exclude namespaces support regular expressions.
We can use %regex[expr] to specify a regular expression to include or exclude test classes.
Surefire provides a convenient way to ignore some tests. Our article about how to skip tests with Maven does a good job in covering this topic.
Conclusion
To sum it up, we have covered in-depth Maven surefire plugin. We explained in detail its goals.
Then, we showed how to configure the plugin to include or exclude some test classes.