Git Integration

Requires pitest 1.22.0 or above.

See maven setup for general instructions on how to configure pitest for a maven project.

Installation

Before you can use the integration, you must first acquire a licence.

The licence file must be named arcmutate-licence.txt and placed at the root of the project.

The plugin must be placed on the classpath of the pitest tool (not on the classpath of the project being mutated).

E.g for maven

<plugin>
  <groupId>org.pitest</groupId>
  <artifactId>pitest-maven</artifactId>
  <version>1.25.7</version>
    <dependencies>
      <dependency>
        <groupId>com.arcmutate</groupId>
        <artifactId>pitest-git-plugin</artifactId>
        <version>2.3.3</version>
      </dependency>
    </dependencies>
</plugin>

Or for gradle

dependencies {
  pitest 'com.arcmutate:pitest-git-plugin:version number'
}

See gradle-pitest-plugin documentation for more details.

Change Based and Test Based Analysis

The plugin provides three modes of operation

• Change based (activated with the +git pitest feature string)
• Test based (activated with the +git_test feature string)
• Mixed mode (activated with the +git_mixed feature string)

Only one mode should be activated at a time.

Change Based Mode

In change based mode, only code modified between the specified git refs will be analysed. This mode is designed to be used when integrating pitest into pull requests, and for receiving fast feedback on local changes.

If you are not sure which mode to use, this is probably the one you want.

Test Based Mode

In test based mode, only classes where one or more lines of code are executed by modified tests will be analysed. This mode is intended for local use when refactoring or retrofitting tests to legacy code. Any modified classes will be ignored, unless at least one modified test executes code within them.

Mixed Mode

In mixed mode both modified code and code executed by modified tests will be analysed. Like test based mode, it is intended for local use.

Usage

Once installed the plugin must be activated as a pitest feature.

e.g to analyse only local uncommitted changes, assuming pitest has been bound to a profile named pitest

mvn -DextraFeatures="+GIT" -Ppitest

To analyse changes compared to master

mvn -DextraFeatures="+GIT(from[master])" -Ppitest

To analyse changes since a particular commit

mvn -DextraFeatures="+GIT(from[c3174266f8e71abc8092f54398c93cd74c1b5f84])" -Ppitest

Files detected as being renamed will be ignored.

From and To

In both change based mode and test based mode, the commits to analyse are controlled by the from and to parameters.

These may be a git ref (e.g HEAD~1) or one the special values

• -Local- - uncommitted changes (staged and unstaged)
• -Empty- - a notional empty/root tree

If not supplied from and to default to HEAD and -Local-.

If HEAD does not exist, -Empty- will be used in its place.

Note that analysis is always performed with the current code (not the code as it existed at the point of the commit). The git range is used purely to select which classes to mutate, not to retrieve historic code.

Scope

In change based mode, by default only mutations on lines that have been modified will be analysed. The scope can be widened to consider all mutations in a modified class with the scope parameter.

It accepts two values

• line (default)
• class

mvn -DextraFeatures="+GIT(scope[class])" -Ppitest

GitCi Output

The git plugin also enables a new output format gitci. This json output is used by the GitHub, Gitlab, Bitbucket and Azure DevOps integrations to integrate pitest into pull request workflows.

The output is enabled automatically when the git feature is activated, but can also be enabled explicitly via a feature named gitci.

mvn -DextraFeatures="+gitci" -Ppitest

The feature accepts a parameter named LEVEL which recognises the following values

• error
• warning (default)
• notice

e.g.

mvn -DextraFeatures="+GITCI(level[error])" -Ppitest

For some CI integrations setting this parameter affects how the mutations are presented to the user.

failWhenNoMutations

When the git feature is active, pitest’s failWhenNoMutations flag is automatically set to false. This ensures that an error is not raised if no source files are modified in the specified commits.