Maven Surefire Plugin

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.

Introduction to Maven Surefire Plugin

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.

Setting Up the Maven Surefire Plugin

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

• <groupId>: Specifies the group ID for the Maven Surefire Plugin.
• <artifactId>: Specifies the Maven Surefire Plugin.
• <version>: The version of the plugin you are using. Ensure you use the latest version.

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] ------------------------------------------------------------------------

Advanced Configuration

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>

Conclusion

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.