Step-by-Step Guide: Setting Up PIT Mutation Testing in a Multi-Module Maven Project

Writing unit tests is a crucial part of software development, but how do we know if they truly improve code quality? This is where Mutation Testing helps—it goes beyond traditional test coverage by detecting weak test cases and untested code paths.

It introduces small changes to your code (called mutants) and checks if your tests detect them. If they don’t, it means your test suite isn’t strong enough!

Read about Mutation Testing for more details.

In this guide, we’ll walk through setting up PIT Mutation Testing in a multi-module Maven project, ensuring that your tests are as robust as possible.

How Does Mutation Coverage Work?

Mutation Testing allows for finding missed assertions in test and bugs in code. This is how it works:

• We write test against a piece of code.
• When the code changes, the test should fail.

Mutation Testing changes the code a little and sees if our existing tests fail. It calls each change a mutant.

• If the test fails, we say mutant is killed. This is good.
• If the test still passes, we say mutant survived. This is bad.
• Our aim is to reduce survived mutants.

Original Code → Modified Code (Mutant) → Run Tests → Pass? (Bad) / Fail? (Good)

This will ensure our code is bug free and our test is high quality.

How to Set Up PIT Mutation Testing in a Multi-Module Maven Project?

To setup mutation testing for your Maven Multimodule project, this is how you can do it.

Step 1: Add the following to the pom.xml of the your module.

<plugins>
    <plugin>
        <groupId>org.pitest</groupId>
        <artifactId>pitest-maven</artifactId>
        <version>{check version info below}</version>
        <dependencies>
            <dependency>
                <groupId>org.pitest</groupId>
                <artifactId>pitest-junit5-plugin</artifactId>
                <version>{check version info below}</version>
            </dependency>
        </dependencies>
        <configuration>
            <targetClasses>
                <param>com.your.package.path.*</param>
            </targetClasses>
            <targetTests>
                <param>com.your.test.package.path.*</param>
            </targetTests>
            <excludeTestClasses>
                <param>com.your.test.package.path.*Integration*</param>
            </excludeTestClasses>
        </configuration>
    </plugin>
</plugins>

For version numbers checkout the following links:

• pitest-maven on mvn repository
• pitest-junit5-plugin on mvn repository

Step 2: Skip all integration tests

Ensure that you don’t run Integration Tests. The excludeTestClasses will help you filter them out.

I add ‘Integration’ to my Integration test names so that the test framework can skip them using the *Integration* pattern.

Step 3: Ensure all your tests pass.

pitest won’t run unless your test passes.

Step 4: Run mvn install -DskipTests

This will create bytecode files that pitest will read. -DskipTests skips running all the tests again.

Step 5: Run mvn org.pitest:pitest-maven:mutationCoverage

If you want to run in a specific module, then you can add the module name in the end

mvn org.pitest:pitest-maven:mutationCoverage -pl {module-name}

Step 6: Find the report in /target/pit-reports/index.html

Step 7: Open the index.html file in the browser.

Concluding

Mutation Testing is an automated way to check the effectiveness of your test suite. Unlike traditional code coverage, that tells you which lines of code test executed it also checks if your tests are strong enough to detect actual code changes.

By integrating PIT in your Maven multi-module project, you ensure that your tests provide real value, catching missed assertions and hidden bugs before they reach production.

Have you used PIT for Mutation Testing? Share your experience in the comments! Also, read my other blogposts TDD.