Copyright © 2007 - 2008 Retroduction.org
Last update: 2008-04-03
Table of Contents
This guide explains the use of Carma on a java project using Apache Maven 2 as build tool.
We are going to use the following stuff for the Carma run:
As the Carma binaries are available via the Retroduction repository you do not need to download them yourself. Just download Maven and a trunk copy of Commons CLI to your harddisk.
These are the things to setup your environment.
The installation is explained on the Maven website. You should be able to execute
mvn -version
after the installation.
The are two aspects regarding configuration of Carma. The first one covers the configuration Carma itself (e.g. how to associate classes and test classes, which classes should be completely excluded etc.).
The second aspect is the integration of Carma into the build process which in this guide will be Apache Maven 2 as Commons CLI uses Maven 2 as build tool.
For our Carma run we define the following attributes for the run:
The configuration must be done in a file named carma.properties. This file is part of the Carma bundle and serves in it's bundled state aas template for configuration. Copy the template for carma.properties to /home/carmauser/commons-cli/carma.properties and adapt the content that it carries this content:
resolver.name = resolver.classmatch resolver.includePattern = (.*) resolver.excludePattern = # ---------------------------------------------------- # settings for class match resolver # ---------------------------------------------------- resolver.classmatch.testNameSuffix = Test project.testclassesdir =./commons-cli/target/tests project.classesdir =./commons-cli/target/classes
As you can see there are two lines which point into the Commons CLI folder (project.classesDir and project.testclassesdir). These two attributes describe where exactly the Commons CLI classes and test classes are located. This information is important for Carma to properly be able to mutate the Commons CLI later on. So just take over these lines as well. If you have extracted the Commons CLI bundle to a different location as above mentioned adapt these lines accordingly.
As covered by the Carma documentation the pom.xml of the target project must be enhanced by a new plugin definition for Carma and the repository location where the Carma binaries reside. Just add the following snippet into the pom.xml of the Commons CLI project so that the Carma binaries can be properly resolved and downloaded to your local maven repository:
<pluginRepositories>
<pluginRepository>
<id>repo.retroduction.org-plugins</id>
<url>http://repository.retroduction.org/</url>
</pluginRepository>
</pluginRepositories>
Second the Maven plugin of Carma must be added to the build:
<!-- enable Carma report -->
<plugin>
<groupId>com.retroduction.carma</groupId>
<artifactId>MavenPlugin</artifactId>
<version>0.2</version>
<executions>
<execution>
<id>mutationtest</id>
<goals>
<goal>mtest</goal>
</goals>
</execution>
<execution>
<id>mutationreport</id>
<goals>
<goal>mreport</goal>
</goals>
</execution>
</executions>
</plugin>
Compared to the Ant variant the Maven plugin needs much less configuration as most information is automatically available from Maven's build infrastructure. Even the project dependencies are automatically resolved and passed to the plugin.
Carma can be run by calling
mvn test
in the root folder of the Commons CLI project. You should see some intermediate output on the console and after half a minute or so you should get a final statement on the results.
[carmatest] # --------------------------------------------------------------------------
[carmatest] # TEST RESULTS SUMMARY
[carmatest] # Total time : 1.19 sec.
[carmatest] # Classes/Tests : 1/1
[carmatest] # Tests Per Class : 1.00
[carmatest] # Mutants/Class : 3.00
[carmatest] # Mutants/Survivors : 3/2
[carmatest] # MutationCoverageRatio : 33.33 %
[carmatest] # --------------------------------------------------------------------------
You've successfully performed a Carma run on the Commons CLI project and should have a report.xml file in the Commons CLI's root folder. The data in this file is XML and if you like - just have a look on its content. To get some nifty HTML report run:
mvn site
Then beside the console output you should find several HTML files in ./target/mutationtest/). Just click on the index.html file and you see a general overview of the Carma results.