PIT Mutation Testing for Java: Maven, Gradle, and JUnit Integration

PIT (PITest) is the standard mutation testing tool for Java. It's fast, integrates cleanly with Maven and Gradle, and generates detailed HTML reports that overlay mutation results directly onto your source code. Here's how to get it running and use the output effectively.

Why PIT Over Other Java Mutation Tools

PIT runs mutations directly on bytecode rather than source code. This means:

• No recompilation per mutant — dramatically faster than source-level tools
• Works with any JVM language (Kotlin, Groovy, Scala) without source changes
• Integrates with the test runner you already use (JUnit 4, JUnit 5, TestNG)
• Supports incremental analysis to avoid re-running unchanged code

For most Java projects, PIT is the first and only mutation tool you need to evaluate.

Maven Setup

Add the PIT plugin to your pom.xml:

<build>
  <plugins>
    <plugin>
      <groupId>org.pitest</groupId>
      <artifactId>pitest-maven</artifactId>
      <version>1.15.3</version>
      <dependencies>
        <!-- Required for JUnit 5 support -->
        <dependency>
          <groupId>org.pitest</groupId>
          <artifactId>pitest-junit5-plugin</artifactId>
          <version>1.2.1</version>
        </dependency>
      </dependencies>
      <configuration>
        <targetClasses>
          <param>com.example.service.*</param>
          <param>com.example.domain.*</param>
        </targetClasses>
        <targetTests>
          <param>com.example.*Test</param>
          <param>com.example.*Tests</param>
        </targetTests>
        <mutators>
          <mutator>DEFAULTS</mutator>
        </mutators>
        <outputFormats>
          <outputFormat>HTML</outputFormat>
          <outputFormat>XML</outputFormat>
        </outputFormats>
        <withHistory>true</withHistory>
        <threads>4</threads>
        <mutationThreshold>70</mutationThreshold>
        <coverageThreshold>80</coverageThreshold>
      </configuration>
    </plugin>
  </plugins>
</build>

Key configuration options:

• targetClasses — glob patterns for classes to mutate. Always exclude test classes, generated code, and framework boilerplate (DTOs, mappers).
• targetTests — which test classes to run. If omitted, PIT runs all tests it finds, which is slow.
• mutators — which mutation operators to apply. DEFAULTS is the standard set. Use ALL for maximum coverage but longer runtime.
• withHistory — enables incremental mutation testing. PIT stores previous results and only re-runs mutations on changed classes.
• threads — parallel test runner threads. Set to CPU cores minus one.
• mutationThreshold — fails the build if mutation score drops below this percentage.

Run mutation tests with:

mvn test-compile org.pitest:pitest-maven:mutationCoverage

Or add it to the verify lifecycle:

<executions>
  <execution>
    <id>pit-report</id>
    <phase>verify</phase>
    <goals>
      <goal>mutationCoverage</goal>
    </goals>
  </execution>
</executions>

Then: mvn verify

Gradle Setup

Add PIT to your build.gradle:

plugins {
    id 'info.solidsoft.pitest' version '1.15.0'
}

dependencies {
    testImplementation 'org.junit.jupiter:junit-jupiter:5.10.0'
    pitest 'org.pitest:pitest-junit5-plugin:1.2.1'
}

pitest {
    junit5PluginVersion = '1.2.1'
    targetClasses = ['com.example.service.*', 'com.example.domain.*']
    targetTests = ['com.example.*Test', 'com.example.*Tests']
    mutators = ['DEFAULTS']
    outputFormats = ['HTML', 'XML']
    withHistory = true
    threads = 4
    mutationThreshold = 70
    coverageThreshold = 80
    failWhenNoMutations = false
}

For Gradle Kotlin DSL (build.gradle.kts):

plugins {
    id("info.solidsoft.pitest") version "1.15.0"
}

configure<PitestPluginExtension> {
    junit5PluginVersion.set("1.2.1")
    targetClasses.set(setOf("com.example.service.*", "com.example.domain.*"))
    targetTests.set(setOf("com.example.*Test"))
    mutators.set(setOf("DEFAULTS"))
    outputFormats.set(setOf("HTML", "XML"))
    withHistory.set(true)
    threads.set(4)
    mutationThreshold.set(70)
}

Run with:

./gradlew pitest

Reports land in build/reports/pitest/.

Reading the PIT HTML Report

Open target/pit-reports/{timestamp}/index.html (Maven) or build/reports/pitest/index.html (Gradle).

Package summary — top-level view showing mutation score per package. Click through to individual classes.

Class view — shows the class source with mutation markers in the gutter. Each line that was mutated has colored indicators:

• Green dot = all mutants on this line were killed
• Red dot = at least one mutant survived
• Yellow dot = no test covers this line

Click a mutation indicator to expand the details: what the original code was, what the mutant changed it to, and which tests ran against it.

Coverage numbers — PIT reports both line coverage and mutation coverage. A line can have 100% line coverage and 0% mutation coverage if tests execute the line but never assert on its output.

Common Java Mutators

The DEFAULTS mutator set includes these operators:

CONDITIONALS_BOUNDARY — shifts < to <=, > to >=, etc.

// Original
if (attempts < MAX_RETRIES) { retry(); }

// Mutant
if (attempts <= MAX_RETRIES) { retry(); }

NEGATE_CONDITIONALS — inverts boolean expressions

// Original
if (user.isEnabled()) { allow(); }

// Mutant
if (!user.isEnabled()) { allow(); }

MATH — swaps arithmetic operators

// Original
double interest = principal * rate * years;

// Mutant
double interest = principal / rate * years;

INCREMENTS — changes i++ to i-- and vice versa

// Original
for (int i = 0; i < items.size(); i++) { ... }

// Mutant: i-- causes infinite loop or wrong iteration

INVERT_NEGS — negates numeric values

// Original
return -amount; // debit

// Mutant
return amount; // no longer a debit

RETURN_VALS — changes return values to primitives or null

// Original
return Optional.of(user);

// Mutant
return Optional.empty();

VOID_METHOD_CALLS — removes calls to void methods

// Original
auditLog.record(event);

// Mutant: audit logging silently dropped

This last one is important for side-effect-heavy code. If you never assert that a void method was called (via a mock verify), PIT will find many surviving void-call mutants.

JUnit 5 Integration Tips

PIT requires the pitest-junit5-plugin for JUnit 5 projects. Without it, PIT silently falls back to JUnit 4 compatibility mode and may not run any tests.

Verify it's working by checking the console output:

PIT >> INFO : Sending 42 test classes to minions
PIT >> INFO : Mutation testing complete

If "0 test classes" appears, the plugin isn't loaded correctly.

For parameterized tests, PIT treats each test case as a separate test, which improves per-mutant test selection accuracy. This is a strong reason to use @ParameterizedTest for boundary conditions — PIT will only run the relevant parameter combination for each mutant.

Excluding Code from Mutation

Exclude generated code, value objects, and framework glue:

<excludedClasses>
  <param>com.example.generated.*</param>
  <param>com.example.*Config</param>
  <param>com.example.*DTO</param>
</excludedClasses>

Exclude specific methods with an annotation. Create a custom annotation:

@Retention(RetentionPolicy.RUNTIME)
@interface ExcludeFromMutationTesting {}

Then configure PIT to skip annotated methods:

<avoidCallsTo>
  <avoidCallsTo>java.util.logging</avoidCallsTo>
  <avoidCallsTo>org.slf4j</avoidCallsTo>
</avoidCallsTo>

The avoidCallsTo option removes void-call mutations for logging statements, which are almost always equivalent mutants — you don't want to assert on every log line.

CI Pipeline Integration

In CI, add the mutationThreshold to break the build on regression:

# GitHub Actions
- name: Run PIT mutation tests
  run: mvn test-compile org.pitest:pitest-maven:mutationCoverage

- name: Upload mutation report
  uses: actions/upload-artifact@v3
  with:
    name: pit-report
    path: target/pit-reports/

For large projects, run PIT on a schedule rather than every PR. Use withHistory=true and cache the .pitest-history.bin file between runs to enable incremental analysis.

PIT's incremental mode checks which source classes changed since the last run and only re-mutates those classes. On a large codebase where you changed three files, incremental PIT runs in minutes rather than hours.

Mutation testing with PIT gives you actionable data about your Java test suite that no coverage tool can provide. The HTML report makes it concrete: click any red marker, see exactly what bug was introduced, and write the test that would have caught it.