Requires pitest 1.15.0 or above.
See maven setup for general instructions on how to configure pitest for a maven project.
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
Or for gradle
pitest 'com.arcmutate:pitest-git-plugin:version number'
See gradle-pitest-plugin documentation for more details.
The plugin provides three modes of operation
- Change based (activated with the
+gitpitest feature string)
- Test based (activated with the
- Mixed mode (activated with the
Only one mode should be activated at a time.
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 certain which mode to use, this is probably the one you want.
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.
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.
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
mvn -Dfeatures="+GIT" -Ppitest
To analyse changes compared to master
mvn -Dfeatures="+GIT(from[master])" -Ppitest
To analyse changes since a particular commit
mvn -Dfeatures="+GIT(from[c3174266f8e71abc8092f54398c93cd74c1b5f84])" -Ppitest
Files detected as being renamed will be ignored.
In both change based mode and test based mode, the commits to analyse are controlled by the
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
to default to
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.
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)
mvn -Dfeatures="+GIT(scope[class])" -Ppitest
The output is enabled automatically when the git feature is activated, but can also be enabled explicitly via a feature named
mvn -Dfeatures="+gitci" -Ppitest
The feature accepts a parameter named
LEVEL which recognises the following values
- warning (default)
mvn -Dfeatures="+GITCI(level[error])" -Ppitest
For some CI integrations setting this parameter affects how the mutations are presented to the user.