Before building this project, you should install the fault-localization dependency into your local Maven repository.
mvn clean package
Use the JAR file that has the -jar-with-dependencies
suffix as it includes all the required dependencies.
- Use the
<argLine>
tag to add the agent JAR to the arguments of the JVM used by the Surefire plugin. - Configure which classes will be instrumented with the
includes=[regex]
option (e.g.includes=.*org.joda.time.*
). - Attach the JUnit run listener by adding a new property.
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
...
<configuration>
...
<argLine>-javaagent:/home/example/java-instrumenterAgent/target/method-agent-0.0.4-jar-with-dependencies.jar=includes=.*some.package.*</argLine>
<properties>
<property>
<name>listener</name>
<value>hu.szte.sed.JUnitRunListener</value>
</property>
</properties>
...
</configuration>
</plugin>
Note: JUnit version on the classpath should be at least 4.0 (this is the first version that supports run listeners). You can set the desired version by configuring the dependencies of PUT or adding an appropriate provider to the Surefire plugin.
Note: The
includes=[regex]
option should match the full name of classes which is a file URI (for example:file:/home/example/target/classes/org/joda/time/Partial
). The${project.build.outputDirectory}
Maven property can be used to make sure that only production classes are included.
<dependencies>
...
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.13</version>
<scope>test</scope>
</dependency>
...
</dependencies>
<plugins>
...
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>3.0.0-M3</version>
<dependencies>
<dependency>
<groupId>org.apache.maven.surefire</groupId>
<artifactId>surefire-junit47</artifactId>
<version>3.0.0-M3</version>
</dependency>
</dependencies>
</plugin>
...
</plugins>
mvn clean test -Dmaven.test.failure.ignore=true
Results will be generated into the coverage
directory inside the root directory of the project (${project.basedir}/coverage
).
The trace.trc.names
file contains the list of the instrumented methods in the <ID>:<FULLY_QUALIFIED_METHOD_NAME>
format.
One or more .trc
files are generated for each unit test.
File names follow this template: <TEST_NAME>-<TEST_RESULT>.<THREAD_ID>.trc
(e.g. org.joda.time.tz.TestCompiler.testCompile-PASS.1.trc
).
These files contain the call chains in binary format.
Each file starts with 4 bytes of magic: 53 6f 44 41
('S'
, 'o'
, 'D'
, 'A'
).
The 5th byte identifies the granularity used during the measurement and thus determines the format of the following part of the file.
With the granularity
option of the agent you can specify the granularity of the collected coverage data.
Possible values for this argument are the following:
Option | Description | 5th Byte | Data Format |
---|---|---|---|
binary |
Classic hit/miss coverage. | 1 |
For each test the output files contain the ids (short integer, 2 bytes) of the covered code elements. |
count |
The extended version of the binary coverage. | 2 |
For each test the output files contain a list of (id,count) tuples where id (short integer, 2 bytes) is the identifier of a covered code element and count represents how many times a particular test has executed the given code element. |
chain |
Count interpreted on call chains. | 4 |
For each test the output files contain a list of (length,chain,count) tuples where length (integer, 4 bytes) is the length of the call chain, chain is a list of code element ids (short integer, 2 bytes) and count represents how many times a particular test has yielded the given call chain. |