Maven plugin to handle multi module projects for PiTest
on command line
mvn install
mvn eu.stamp-project:pitmp-maven-plugin:run
mvn eu.stamp-project:pitmp-maven-plugin:descartes
with Maven
Modify your pom.xml
,
<plugin>
<groupId>eu.stamp-project</groupId>
<artifactId>pitmp-maven-plugin</artifactId>
<version>1.3.7</version>
</plugin>
<plugin>
<groupId>eu.stamp-project</groupId>
<artifactId>pitmp-maven-plugin</artifactId>
<version>1.3.7</version>
<configuration>
<mutationEngine>descartes</mutationEngine>
</configuration>
</plugin>
PitMP works only from the top level directory of your project.
"cd <my_directory> ; mvn eu.stamp-project:pitmp-maven-plugin:run" will NOT work.
c.f. properties targetModules and skippedModules to specify in which directories you want to run PitMP.
PitMP (PIT for Multi-module Project) is a Maven plugin able to run PIT on multi-module projects. PIT is a mutation testing system for Java applications, which allows you to evaluate the quality of your test suites.
To know more about PIT: http://pitest.org
PIT takes a test suite, a set of classes to be mutated and a set of mutation operators
and computes a line coverage and a mutation coverage:
PIT mutates only the classes defined in the same module than the
test suite:
PitMP runs PIT on every test suite, mutating classes of all dependencies of modules
located in the same project tree:
then:
etc...
PitMP just extends PIT, it doesn't rewrite any feature, so all PIT's properties can be used. PitMP runs test suite as PIT does, just extending the list of classes to be mutated to the whole project tree, instead of mutating only the classes of the test suite module.
PIT produces a report that includes:
Go to the project on which you want to apply PIT
Compile your project
mvn install
mvn eu.stamp-project:pitmp-maven-plugin:run
Since 1.1.4 PitMP is available on Maven Central, so this step is required only for releases before 1.1.4.
git clone https://github.com/STAMP-project/pitmp-maven-plugin.git
cd pitmp-maven-plugin
mvn install
You can configure your project in the root pom.xml, in the section <plugins>:
<plugin>
<groupId>eu.stamp</groupId>
<artifactId>pitmp-maven-plugin</artifactId>
<version>release.you.want</version>
<!-- List all the packages of the project that contain classes you want
to be mutated.
All PIT's properties can be used.
-->
<configuration>
<targetClasses>
<param>a.package.of.classes*</param>
<param>another.package.of.classes*</param>
</targetClasses>
</configuration>
</plugin>
targetModules: to run PIT only on specified modules, this
attribute filters directories where to run PIT, not classes
to be mutated
You can use the property "targetModules" in the pom.xml:
<targetModules>
<param>yourFirstModule</param>
<param>anotherModule</param>
</targetModules>
or on the command line, use:
mvn "-DtargetModules=yourFirstModule,anotherModule" pitmp:run
Running PitMP from a module directory will NOT work.
skippedModules: to skip specified modules when running PIT, this
attribute filters directories where to run PIT, not classes
to be mutated
You can use the property "skippedModules" in the pom.xml:
<skippedModules>
<param>aModuleToSkip</param>
<param>anotherModuleToSkip</param>
</skippedModules>
or on the command line, use:
mvn "-DtargetModules=aModuleToSkip,anotherModuleToSkip" pitmp:run
targetDependencies: take only into account classes of targetDependencies, i.e.
only code in targetDependencies will be mutated; it impacts PIT's targetClasses
Note that only targetDependencies shall contains only modules of the project
ignoredDependencies: ignore classes of ignoredDependencies, i.e. code in targetDependencies will not be mutated; it impacts PIT's targetClasses If a module is both in targetDependencies and ignoredDependencies, it will be ignored.
continueFromModule: to run PIT starting from a given project (because continuing an aborted execution with Maven -rf is not working)
<continueFromModule>aModule</continueFromModule>
If you want to run Descartes:
mvn eu.stamp-project:pitmp-maven-plugin:descartes
If you want to configure Descartes, add to your root project pom.xml, in the section <plugins>:
<plugin>
<groupId>eu.stamp</groupId>
<artifactId>pitmp-maven-plugin</artifactId>
<version>release.you.want</version>
<!-- list all the packages of the project that contain classes you want to be mutated -->
<configuration>
<targetClasses>
<param>a.package.of.classes*</param>
<param>another.package.of.classes*</param>
</targetClasses>
<mutationEngine>descartes</mutationEngine>
</configuration>
</plugin>
For complete instructions about Descartes see the Descartes github.
For an example of multi module project using PitMP see the dnoo github.
If you want to check the number of Pseudo Tested Methods and/or Partially Tested Methods, you can add specific thresholds pseudoTestedThreshold and/or partiallyTestedThreshold in the configuration:
<plugin>
<groupId>eu.stamp</groupId>
<artifactId>pitmp-maven-plugin</artifactId>
<version>release.you.want</version>
<configuration>
<!-- Check Pseudo/Partially Tested Methods -->
<pseudoTestedThreshold>1</pseudoTestedThreshold>
<partiallyTestedThreshold>1</partiallyTestedThreshold>
<targetClasses>
<param>a.package.of.classes*</param>
<param>another.package.of.classes*</param>
</targetClasses>
<mutationEngine>descartes</mutationEngine>
</configuration>
</plugin>
The plugin can break the build, when the mutation score and/or line coverage is considered too poor. The example below breaks the build if mutation score is less than 40% or line coverage less than 60 %, according to "mutationThreshold" and "coverageThreshold" options:
<plugin>
<groupId>eu.stamp-project</groupId>
<artifactId>pitmp-maven-plugin</artifactId>
<version>release.you.want</version>
<configuration>
<mutationEngine>descartes</mutationEngine>
<skip>false</skip>
<failWhenNoMutations>false</failWhenNoMutations>
<mutationThreshold>40</mutationThreshold>
<coverageThreshold>60</coverageThreshold>
</configuration>
</plugin>
Notes concerning additional options:
For PIT release... | use PitMP release... | how to use PitMP |
---|---|---|
1.4.7 | 1.3.7 | Maven Central |
1.4.2 | 1.3.5, 1.3.6 | Maven Central |
1.4.0 | 1.3.4, 1.3.3, 1.3.2, 1.3.1, 1.3.0, 1.2.0 | Maven Central |
1.3.2 | 1.1.6, 1.1.5 | Maven Central |
1.3.1 | 1.1.4 | Maven Central |
1.2.1, 1.2.2, 1.2.4, 1.2.5, 1.3.0 | not tested | |
1.2.0, 1.2.3 | 1.0.1 | git clone & mvn install |
pitmp-maven-plugin-1.3.7
pitmp-maven-plugin-1.3.6
pitmp-maven-plugin-1.3.5
pitmp-maven-plugin-1.3.4
pitmp-maven-plugin-1.3.3
pitmp-maven-plugin-1.3.2
pitmp-maven-plugin-1.3.1
pitmp-maven-plugin-1.3.0
pitmp-maven-plugin-1.2.0
pitmp-maven-plugin-1.1.6
pitmp-maven-plugin-1.1.5
v1.1.0, pitmp-maven-plugin-1.1.4
v1.0.1
Feedbacks are welcome ! :-)