PIT

https://pitest.org/quickstart
Admin
PIT is a mutation testing framework for Java that automatically tests the quality of test suites by...
Tokens:12,238
Snippets:204
Trust Score:9.4
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example Mutation Interceptor Configuration

Source: https://pitest.org/quickstart/advanced

This example shows how to enable a feature called FOO with specific parameters using PIT's feature language.

```bash
+FOO(max[42] allow[cats] allow[dogs])
```

--------------------------------

### Clone PITest Ant Example Project

Source: https://pitest.org/quickstart/ant

Clone the example project from GitHub to evaluate PITest with Ant. This provides a ready-to-run setup for testing.

```bash
git clone https://github.com/hcoles/pitest-ant-example.git
```

--------------------------------

### Example of integer threshold blind spot

Source: https://pitest.org/quickstart/commandline

Demonstrates how integer thresholds for coverage can lead to silent regressions. This example shows scenarios where coverage can decrease significantly without triggering a build failure due to rounding.

```text
(i.)   Lose 97 covered lines (6,147 -> 6,050):
       actual = 60.50%  ->  rounds to 61%  ->  build PASSES
       A silent regression of nearly 100 lines.

(ii.)  Add 163 untested lines:
       actual = 60.50%  ->  rounds to 61%  ->  build PASSES
       163 lines with no tests, no problem.

(iii.) Add 164 untested lines:
       actual = 60.49%  ->  rounds to 60%  ->  build FAILS
       Just 1 line difference from the scenario above.

(iv.)  Add 50 covered lines (6,147 -> 6,197):
       actual = 61.97%  ->  rounds to 62%  ->  jumps a whole percent
       A single percentage point jump for 50 lines.


```

--------------------------------

### Multiple Target Classes Globs Example

Source: https://pitest.org/quickstart/commandline

Demonstrates specifying multiple, distinct glob patterns for class mutation.

```bash
com.mycompany.package.*, com.mycompany.packageB.Foo, com.partner.*

```

--------------------------------

### Math Mutator Example for Arithmetic Operations

Source: https://pitest.org/quickstart/mutators

Demonstrates the Math mutator's replacement of binary arithmetic operations.

```Java
int a = b + c;
```

```Java
int a = b - c;
```

--------------------------------

### Equivalent Logical Statements Example

Source: https://pitest.org/quickstart/basic_concepts

Illustrates two logically equivalent statements. This highlights how some mutations might not be detected because they result in functionally identical code.

```java
int i = 2;
if ( i >= 1 ) {
    return "foo";
}


```

```java
int i = 2;
if ( i > 1 ) {
    return "foo";
}

```

--------------------------------

### Increments Mutator Example

Source: https://pitest.org/quickstart/mutators

Shows the Increments mutator's effect on local variable increments and decrements.

```Java
public int method(int i) {
  i++;
  return i;
}
```

```Java
public int method(int i) {
  i--;
  return i;
}
```

--------------------------------

### Conditionals Boundary Mutator Example

Source: https://pitest.org/quickstart/mutators

Demonstrates how the Conditionals Boundary mutator transforms relational operators.

```Java
if (a < b) {
  // do something
}
```

```Java
if (a <= b) {
  // do something
}
```

--------------------------------

### Invert Negatives Mutator Example

Source: https://pitest.org/quickstart/mutators

Illustrates the Invert Negatives mutator's transformation of negative variable negations.

```Java
public float negate(final float i) {
  return -i;
}
```

```Java
public float negate(final float i) {
  return i;
}
```

--------------------------------

### Run PIT Target

Source: https://pitest.org/quickstart/ant

Execute the 'pit' target in the cloned example project using Ant. This will run mutation testing and generate HTML reports.

```bash
ant pit
```

--------------------------------

### Example of inlined code detection

Source: https://pitest.org/quickstart/commandline

Illustrates how PIT detects inlined code generated by the Java compiler for finally blocks. The first example shows two separate inlined instructions, while the second shows similar instructions on the same line, which PIT assumes is not inlined.

```java
finally {
  int++;
  int++;
}

```

```java
finally {
  int++; int++;
}

```

--------------------------------

### Target Classes Glob Example

Source: https://pitest.org/quickstart/commandline

Specifies classes to be mutated using glob patterns. Use comma-separated globs for multiple targets.

```bash
com.mycompany.*

```

--------------------------------

### Equivalent Mutation with Default Initialization

Source: https://pitest.org/quickstart/mutators

This example illustrates a scenario where the experimental member variable mutator might create an equivalent mutation if a member variable is already initialized with its Java default value.

```Java
public class EquivalentMutant {
    private int x = 0;
}
```

--------------------------------

### Constructor Call Mutator Example

Source: https://pitest.org/quickstart/mutators

Replaces constructor calls with null values. This mutation is unstable and may cause NullPointerExceptions.

```java
public Object foo() {
  Object o = new Object();
  return o;
}
```

```java
public Object foo() {
  Object o = null;
  return o;
}
```

--------------------------------

### Negate Conditionals Mutator Example

Source: https://pitest.org/quickstart/mutators

Demonstrates how the NEGATE_CONDITIONALS mutator changes conditional statements. It replaces operators like '==' with '!='.

```java
if (a == b) {
  // do something
}
```

```java
if (a != b) {
  // do something
}
```

--------------------------------

### Negation Mutator Example

Source: https://pitest.org/quickstart/mutators

Replaces a numeric variable with its negation. This mutator is useful for testing how code handles negative values.

```java
public float get(final float i) {
  return i;
}
```

```java
public float get(final float i) {
  return -i;
}
```

--------------------------------

### Math Mutator Example for Non-Local Variable Increments

Source: https://pitest.org/quickstart/mutators

Illustrates how the Math mutator transforms increments/decrements of non-local (member) variables.

```Java
public class A {
  private int i;

  public void foo() {
    this.i++;
  }
}
```

```Java
public class A {
  private int i;

  public void foo() {
    this.i = this.i - 1;
  }
}
```

--------------------------------

### Activate Extra Features via Command Line

Source: https://pitest.org/quickstart/maven

The `extraFeatures` parameter allows activating additional features from the command line without overwriting existing configurations in build scripts. This example activates arcmutate's git integration and history implementations.

```bash
mvn -Ppitest -DextraFeatures="+GIT(from[HEAD~1]), +arcmutate_history(run_tests[false])" test-compile
```

--------------------------------

### Return Values Mutator Example (Object)

Source: https://pitest.org/quickstart/mutators

Illustrates the RETURN_VALS mutator's behavior for Object return types. It mutates non-null return values to null.

```java
public Object foo() {
  return new Object();
}
```

```java
public Object foo() {
  new Object();
  return null;
}
```

--------------------------------

### Conditional Boundary Mutation Example

Source: https://pitest.org/quickstart/basic_concepts

Demonstrates how the CONDITIONALS_BOUNDARY_MUTATOR modifies a conditional statement. This operator changes boundary conditions in if statements.

```java
if ( i >= 0 ) {
    return "foo";
} else {
    return "bar";
}

```

```java
if ( i > 0 ) {
    return "foo";
} else {
    return "bar";
}

```

--------------------------------

### Void Method Call Mutation Example

Source: https://pitest.org/quickstart/mutators

Demonstrates how the VOID_METHOD_CALLS mutator removes calls to void methods. This mutator is active by default.

```java
public void someVoidMethod(int i) {
  // does something
}

public int foo() {
  int i = 5;
  someVoidMethod(i);
  return i;
}

```

```java
public void someVoidMethod(int i) {
  // does something
}

public int foo() {
  int i = 5;
  return i;
}

```

--------------------------------

### Configure Target Classes for Mutation

Source: https://pitest.org/quickstart/maven

Specify the classes to be mutated using globs within the `<targetClasses>` tag. If not provided, PITest automatically determines classes from the Maven output directory. This example targets all classes in `com.mycompany.*`.

```xml
<targetClasses>
    <param>com.mycompany.*</param>
</targetClasses>
```

--------------------------------

### Enable Dry Run Mode via Maven Command Line

Source: https://pitest.org/quickstart/maven

Activate Pitest's dry run mode using a Maven command-line property. This is useful for initial setup to identify Pitest configuration issues.

```bash
mvn -Ppitest -Dpit.dryRun=true test
```

--------------------------------

### Math Mutator Example for String Concatenation

Source: https://pitest.org/quickstart/mutators

Shows that the Math mutator does not affect string concatenation, which is handled differently by the compiler.

```Java
String a = "foo" + "bar";
```

```Java
String a = new StringBuilder("foo").append("bar").toString();
```

--------------------------------

### Mutating Member Variable Initialization

Source: https://pitest.org/quickstart/mutators

This example shows how the experimental member variable mutator changes an explicitly initialized member variable to its Java default value.

```Java
public class MutateMe {
    private final int x = 5;
    //...
}
```

```Java
public class MutateMe {
    private final int x = 0;
    ...
}
```

--------------------------------

### Arithmetic Operator Deletion Example 2

Source: https://pitest.org/quickstart/mutators

Replaces an arithmetic operation with its second member. This is another variation for testing simplification scenarios.

```java
int a = b + c;
```

```java
int a = c;
```

--------------------------------

### Inline Constant Mutator Example (Integer)

Source: https://pitest.org/quickstart/mutators

Mutates inline integer constants. The mutation rule for integers is to replace the unmutated value with 0, -1 with 1, 5 with -1, or otherwise increment the unmutated value by one.

```java
public int foo() {
  int i = 42;
  return i;
}
```

```java
public int foo() {
  int i = 43;
  return i;
}
```

--------------------------------

### Arithmetic Operator Deletion Example 1

Source: https://pitest.org/quickstart/mutators

Replaces an arithmetic operation with its first member. This mutator helps test scenarios where an operation might be unexpectedly simplified.

```java
int a = b + c;
```

```java
int a = b;
```

--------------------------------

### Enable and Disable PITest Features

Source: https://pitest.org/quickstart/maven

Use the `<features>` tag to enable or disable specific PITest features. Features prefixed with '-' are disabled, and those with '+' are enabled. For example, disabling junk mutation filtering for Java records and enabling automatic thread count adjustment.

```xml
<features>
  <feature>-frecord</feature>
  <feature>+auto_threads</feature>
</features>
```

--------------------------------

### Launch Mutation Coverage Report

Source: https://pitest.org/quickstart/commandline

Launches a mutation coverage report from the command line. Ensure the classpath includes the pit jar, dependencies, and the necessary report generation classes. Specify report directory, target classes, target tests, and source directories.

```bash
java -cp <your classpath including pit jar and dependencies> \
    org.pitest.mutationtest.commandline.MutationCoverageReport \
    --reportDir <outputdir> \
    --targetClasses com.your.package.tobemutated* \
    --targetTests com.your.package.* \
    --sourceDirs <pathtosource>
```

--------------------------------

### Run PITest with History for Faster Analysis

Source: https://pitest.org/quickstart/maven

Enable the 'withHistory' parameter when running the mutationCoverage goal to speed up repeated analysis by leveraging historical data.

```bash
mvn -DwithHistory test-compile org.pitest:pitest-maven:mutationCoverage
```

--------------------------------

### Run PITest Mutation Coverage Goal

Source: https://pitest.org/quickstart/maven

Execute the mutationCoverage goal directly from the command line to analyze your codebase and generate an HTML report.

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

--------------------------------

### Configure JVM Arguments for Child Processes

Source: https://pitest.org/quickstart/maven

Provide a list of arguments to be used when PIT launches child processes. This is often used to increase available memory or pass specific JVM flags.

```xml
<jvmArgs>
    <jvmArg>-XX:-UseSplitVerifier</jvmArg>
</jvmArgs>
```

--------------------------------

### PIT Site Report Configuration with All Options

Source: https://pitest.org/quickstart/maven

This POM configuration demonstrates how to customize the PIT site report using various parameters like skip, reportsDirectory, sourceDataFormats, siteReportName, siteReportDescription, and siteReportDirectory. Ensure the mutationCoverage goal has already produced an HTML report in the specified or default directory.

```xml
<reporting>
    <plugins>
        <plugin>
            <groupId>org.pitest</groupId>
            <artifactId>pitest-maven</artifactId>
            <version>LATEST</version>
            <configuration>
                <skip>false</skip>
                <reportsDirectory>${project.build.directory}/pit-custom-output-dir</reportsDirectory>
                <sourceDataFormats>
                    <sourceDataFormat>HTML</sourceDataFormat>
                </sourceDataFormats>
                <siteReportName>my-pit-report-name</siteReportName>
                <siteReportDescription>my pit report custom description</siteReportDescription>
                <siteReportDirectory>pit-custom-site-directory</siteReportDirectory>
            </configuration>
            <reportSets>
                <reportSet>
                    <reports>
                        <report>report</report>
                    </reports>
                </reportSet>
            </reportSets>
        </plugin>
    </plugins>
</reporting>

```

--------------------------------

### Execute PIT Mutation Coverage and Site Report

Source: https://pitest.org/quickstart/maven

This command cleans the project, executes the pitest-maven mutationCoverage goal, and then generates the Maven site report. Ensure the mutationCoverage goal has already produced an HTML report.

```bash
mvn clean org.pitest:pitest-maven:mutationCoverage site

```

--------------------------------

### Configure Multiple Target Classes

Source: https://pitest.org/quickstart/maven

Provide multiple `<param>` entries within `<targetClasses>` to specify different globs for classes to be mutated. This allows for granular control over which packages and specific classes are targeted.

```xml
<targetClasses>
    <param>com.mycompany.package.*</param>
    <param>com.mycompany.packageB.Foo*</param>
    <param>com.partner.*</param>
</targetClasses>
```

--------------------------------

### Bitwise OR to AND Mutation

Source: https://pitest.org/quickstart/mutators

Demonstrates mutation of a bitwise OR operator to an AND operator.

```Java
a | b;
```

--------------------------------

### Bitwise AND to OR Mutation

Source: https://pitest.org/quickstart/mutators

Demonstrates mutation of a bitwise AND operator to an OR operator.

```Java
a & b;
```

--------------------------------

### Configure CLASSLIMIT Feature

Source: https://pitest.org/quickstart/commandline

Replaces the deprecated --maxMutationsPerClass argument by enabling the CLASSLIMIT feature with a specific limit.

```bash
features="+CLASSLIMIT(limit[42])"

```

--------------------------------

### Create Mutation Coverage Target

Source: https://pitest.org/quickstart/ant

Create an Ant target to run PITest. Configure classpaths for PIT and your application, specify target classes and tests, and set report and source directories.

```xml
<target name="mutationCoverage">
    <pitest
        pitClasspath="pit.path"
        classPath="mutation.path"
        targetClasses="com.yourcodebase.*"
        targetTests="com.yourcodebase.*"
        reportDir="pathToWhereYouWantOutput"
        sourceDir="pathToYourSource"/>
</target>
```

--------------------------------

### Maven Configuration for Coverage Threshold

Source: https://pitest.org/quickstart/maven

Sets the coverage threshold to 61.5% and precision to 1 decimal place for finer-grained analysis. This helps avoid the integer threshold blind spot.

```xml
<configuration>
    <coverageThreshold>61.5</coverageThreshold>
    <thresholdPrecision>1</thresholdPrecision>
</configuration>
```

--------------------------------

### Bitwise AND to First Operand Mutation

Source: https://pitest.org/quickstart/mutators

Demonstrates mutation of a bitwise AND operator to its first operand.

```Java
a;
```

--------------------------------

### Bitwise AND to Second Operand Mutation

Source: https://pitest.org/quickstart/mutators

Demonstrates mutation of a bitwise AND operator to its second operand.

```Java
b;
```

--------------------------------

### Configure Packages to Avoid Calls

Source: https://pitest.org/quickstart/maven

Specify packages and classes that should be excluded from mutation analysis. This prevents mutation of code within these specified areas.

```xml
<avoidCallsTo>
    <avoidCallsTo>java.util.logging</avoidCallsTo>
    <avoidCallsTo>org.apache.log4j</avoidCallsTo>
    <avoidCallsTo>org.slf4j</avoidCallsTo>
    <avoidCallsTo>org.apache.commons.logging</avoidCallsTo>
</avoidCallsTo>
```

--------------------------------

### Run Mutation Tests with Specific Test Suite

Source: https://pitest.org/quickstart/commandline

Mutates specific classes using tests from a designated test suite. This is useful when you want to ensure that mutations are tested by a targeted set of tests. Replace <your classpath> and directory paths with actual values.

```bash
java -cp <your classpath> \
     org.pitest.mutationtest.commandline.MutationCoverageReport \
    --reportDir c:\\mutationReports \
    --targetClasses example.foo.Specfic, example.foo.Other \
    --targetTests example.ReflectionSuite
    --sourceDirs c:\\myProject\\src \


```

--------------------------------

### Run Mutation Tests with Exclusions

Source: https://pitest.org/quickstart/commandline

Mutates all classes in a specified package and its subpackages using multiple threads. Excludes specific methods like hashCode and equals from mutation. Ensure to replace <your classpath> and directory paths with actual values.

```bash
java -cp <your classpath> \
     org.pitest.mutationtest.commandline.MutationCoverageReport \
    --reportDir c:\\mutationReports \
    --targetClasses example.foo.* \
    --sourceDirs c:\\myProject\\src \
    --targetTests example.foo*
    --threads 2
    --excludedMethods hashCode,equals

```

--------------------------------

### Minimum POM Configuration for PIT Site Report

Source: https://pitest.org/quickstart/maven

This is the essential configuration required within the `<reporting>` section of your pom.xml to enable the PIT site report generation. It specifies the pitest-maven plugin and the 'report' goal.

```xml
<reporting>
    <plugins>
        <plugin>
            <groupId>org.pitest</groupId>
            <artifactId>pitest-maven</artifactId>
            <version>LATEST</version>
            <reportSets>
                <reportSet>
                    <reports>
                        <report>report</report>
                    </reports>
                </reportSet>
            </reportSets>
        </plugin>
    </plugins>
</reporting>

```

--------------------------------

### Configure PITest with Target Classes and Tests

Source: https://pitest.org/quickstart/maven

Configure the PITest Maven plugin to specify which classes to mutate and which tests to run. This is useful for limiting the scope of mutation testing.

```xml
<plugin>
    <groupId>org.pitest</groupId>
    <artifactId>pitest-maven</artifactId>
    <version>LATEST</version>
    <configuration>
        <!-- no longer required -->
        <targetClasses>
            <param>com.your.package.root.want.to.mutate*</param>
        </targetClasses>
        <!-- no longer required -->
        <targetTests>
            <param>com.your.package.root*</param>
        </targetTests>
    </configuration>
</plugin>
```

--------------------------------

### Configure Class Mutation Limit

Source: https://pitest.org/quickstart/maven

Set a maximum limit for the number of mutations to be generated per class. This feature replaces the older 'maxMutationsPerClass' parameter.

```xml
features="+CLASSLIMIT(limit[42])"
```

--------------------------------

### Configure Mutators

Source: https://pitest.org/quickstart/maven

Define the specific mutation operators to be applied using the `<mutators>` tag. This allows for fine-tuning the types of mutations generated. Available mutators can be found in the mutation operators documentation.

```xml
<configuration>
    <mutators>
        <mutator>CONSTRUCTOR_CALLS</mutator>
        <mutator>NON_VOID_METHOD_CALLS</mutator>
    </mutators>
</configuration>
```

--------------------------------

### Define PITest Task

Source: https://pitest.org/quickstart/ant

Define the 'pitest' task in your Ant build file. Ensure the classpath includes pitest jars, plugins, and necessary libraries like xstream and xmlpull.

```xml
<taskdef name="pitest" classname="org.pitest.ant.PitestTask" classpathref="pit.path" />
```

--------------------------------

### Inline Constant Mutator with Compiler Optimization

Source: https://pitest.org/quickstart/mutators

Demonstrates how compiler optimizations for final variables can prevent mutation. The compiler may optimize final variables into constants, making them unmutable by the mutation engine.

```java
public class A {
  private static final int VAR = 13;
  
  public String foo() {
    final int i = 42;
    return "" + VAR + ":" + i;
  }
}
```

```java
public class A {
  public String foo() {
    return "13:42";
  }
}
```

--------------------------------

### Enable Dry Run Mode in Maven POM

Source: https://pitest.org/quickstart/maven

Configure Pitest to gather coverage and generate mutants without running tests against them by adding this element to your pom.xml.

```xml
<dryRun>true</dryRun>
```

--------------------------------

### Mutation of int return type

Source: https://pitest.org/quickstart/mutators

Demonstrates how a non-void method returning an int is mutated. The method call is replaced by the default int value (0).

```java
public int someNonVoidMethod() {
  return 5;
}

public void foo() {
  int i = someNonVoidMethod();
  // do more stuff with i
}
```

```java
public int someNonVoidMethod() {
  return 5;
}

public void foo() {
  int i = 0;
  // do more stuff with i
}
```

--------------------------------

### Registering a Custom Mutator Group

Source: https://pitest.org/quickstart/advanced

This snippet shows how to register a new group of mutators using the MutatorGroup interface. It groups several predefined mutators under a custom name 'MYGROUP'.

```java
public void register(Map<String, List<MethodMutatorFactory>> mutators) {

    mutators.put("MYGROUP", gather(mutators,"INVERT_NEGS",
            "RETURN_VALS",
            "MATH",
            "CONDITIONALS_BOUNDARY",
            "INCREMENTS"));

}
```

--------------------------------

### Add PITest Maven Plugin to pom.xml

Source: https://pitest.org/quickstart/maven

Include this plugin configuration in your project's pom.xml to add PITest as a build plugin.

```xml
<plugin>
    <groupId>org.pitest</groupId>
    <artifactId>pitest-maven</artifactId>
    <version>LATEST</version>
</plugin>
```

--------------------------------

### Mutation of Object return type

Source: https://pitest.org/quickstart/mutators

Illustrates the mutation of a non-void method returning an Object. The method call is replaced by the default Object value (null). Be aware of potential NullPointerExceptions.

```java
public Object someNonVoidMethod() {
  return new Object();
}

public void foo() {
  Object o = someNonVoidMethod();
  // do more stuff with o
}
```

```java
public Object someNonVoidMethod() {
  return new Object();
}

public void foo() {
  Object o = null;
  // do more stuff with o
}
```

--------------------------------

### Maven Configuration to Skip Pitest Plugin

Source: https://pitest.org/quickstart/maven

Skips the execution of the Pitest plugin within a Maven module. Useful for excluding specific modules from mutation testing.

```xml
<configuration>
    <skip>true</skip>
</configuration>
```

--------------------------------

### Handle Inlined Code in Finally Blocks

Source: https://pitest.org/quickstart/maven

Configure PIT to detect and handle inlined code generated by the Java compiler within finally blocks. This prevents multiple identical mutations from being created for the same logical instruction.

```java
finally {
    int++;
    int++;
}
```

```java
finally {
    int++; int++;
}
```

--------------------------------

### Basic Remove Conditionals Mutator

Source: https://pitest.org/quickstart/mutators

This mutator removes conditional statements, ensuring the guarded statements always execute. It primarily mutates equality checks.

```java
if (a == b) {
  // do something
}

```

```java
if (true) {
  // do something
}

```

--------------------------------

### Remove Conditionals Mutator - Force Else Branch

Source: https://pitest.org/quickstart/mutators

This specialized mutator ensures the 'else' block of a conditional statement always executes. It mutates equality checks.

```java
if (a == b) {
  // do something
} else {
  // do something else
}

```

```java
if (false) {
  // do something
} else {
  // do something else
}

```
Tokens:
Raw