Mutation Exclusions

Requires pitest 1.15.0 or above.

Provided by the arcmutate-base plugin.

Background

Pitest provides two built in mechanisms to exclude mutations from analysis

• By method name
• By annotation

Although straight forward to use, both mechanisms are coarse grained, excluding all mutations from entire classes or methods.

Arcmutate Exclusions

Arcmutate provides two additional methods to exclude mutants.

• By code comment
• By external file

Both mechanisms allow more fine grained exclusion of mutations.

Excluding by Code Comment

Excluding by code comment is enabled with the exclusionscan feature.

<plugin>
  <groupId>org.pitest</groupId>
  <artifactId>pitest-maven</artifactId>
  <version>1.16.0</version>
    <dependencies>
      <dependency>
        <groupId>com.arcmutate</groupId>
        <artifactId>base</artifactId>
        <version>1.3.0</version>
      </dependency>
    </dependencies>
    <configuration>
      <features>
        <feature>+exclusionscan</feature>
      </features>
    </configuration>
</plugin>

Mutations can then be prevented by placing a trailing comment on any line of code

void foo(int a) {
  if (a > 10) {
     System.out.println("will not be mutated"); // NO PITEST
  }
}

Comments can take the form

• NOPITEST
• NO PITEST

Both java and kotlin are supported.

Excluding by External File

Excluding by external file is enabled with the exclusion feature.

<plugin>
  <groupId>org.pitest</groupId>
  <artifactId>pitest-maven</artifactId>
  <version>1.16.0</version>
    <dependencies>
      <dependency>
        <groupId>com.arcmutate</groupId>
        <artifactId>base</artifactId>
        <version>1.3.0</version>
      </dependency>
    </dependencies>
    <configuration>
      <features>
        <feature>+exclusion</feature>
      </features>
    </configuration>
</plugin>

The plugin will then search both the test source tree and the pitest reports directory for files with the extension .pitest.

Handed edited exclusion files should be placed in the source tree. Programmatically generated files which you do not wish to check into source control can be placed in the reports directory.

The exclusion file have a simple csv format

file, clazz, method, mutator, line start, line end

Where each field is glob.

To disable all mutations within a project wildcard globs could be used

*, *, *, *, *, *

More usefully, all mutations on line 7 of the class Foo might be disabled.

*, com.example.Foo, *, *, 7, 7

Or only mutations from certain mutators in certain files.

Foo.java, *, *, RETURN_VALS, *, *
*Repository*.java, *, *, NULL_RETURNS, *, *

Note that the filename does not include a path. If the same filename is used within multiple directories, the exclusion will apply to all matching files. It is not possible to use full paths in this field as only the filename is retained in the Java bytecode. In most cases it is therefore preferable to match using class name, as this is fully qualified.

You may also wish to include a second wildcard entry to catch any mutations declared within inner classes.

*, com.example.Foo, *, RETURN_VALS, *, *
*, com.example.Foo$*, *, RETURN_VALS, *, *

Lines starting with a # character are treated as comments.

# Remove conditionals created issues in defensive code we are scared to remove for this class
*, com.example.Foo*, *, REMOVE_CONDITIONALS*, *, *