Switch branches/tags
Nothing to show
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
..
Failed to load latest commit information.
src/main
README.md
pom.xml

README.md

Ant tasks

GZoltar comes with Ant tasks to launch Java programs or unit test cases (either JUnit or TestNG) of a Java project and gather their code coverage, and for creating fault localization reports from the collected coverage. Coverage data can be collected with the coverage task, and fault localization reports can be created with the fl-report task.

All tasks are defined in the gzoltarant.jar (which is part of the GZoltar's distribution package) and can be included in your Ant scripts with the usual taskdef declaration. For example:

<project name="Project Example" xmlns:gzoltar="antlib:com.gzoltar.ant">

  <taskdef uri="antlib:com.gzoltar.ant" resource="antlib.xml">
    <classpath path="${gzoltar-ant.jar}"/>
  </taskdef>

  ...
</project>

Where ${gzoltar-ant.jar} should point to the gzoltarant.jar file (which is part of the GZoltar's distribution package).

A simple working Ant project can be found in here.

Coverage task

The standard Ant tasks to launch Java programs are java, junit, and testng. To allow code coverage collecting to these tasks they only need to be wrapped with the GZoltar's coverage task as shown in the following example:

<gzoltar:coverage
    buildLocation="_build_directory_/classes"
    destfile="gzoltar.ser">
  <junit haltonfailure="no" haltonerror="no" fork="yes">
    <classpath>
      <pathelement location="build"/>
    </classpath>
    <test name="com.gzoltar.examples.ProjectExampleTest"/>
    <formatter classname="com.gzoltar.ant.listener.JUnitFormatter"
      usefile="no"/>
  </junit>
</gzoltar:coverage>

In order to be able to collect any coverage, the target classes must be compiled with debug information.

The nested task (i.e., either java, junit, or testng) always has to declare fork="yes", otherwise the coverage task will not be able to collect any coverage.

By default, GZoltar's coverage task (1) instruments all classes loaded by any test case and located inside _build_directory_/classes, (2) collects coverage at line level during the execution of all existing unit test cases, and (3) serializes all data to a file (gzoltar.ser) when the JVM terminates.

Report task

Once the coverage has been collected, different types of fault localization reports can be generated by GZoltar. In order to do it, you will need to configure GZoltar's fl-report task as shown in the following example:

<gzoltar:fl-report
    buildLocation="_build_directory_/classes"
    dataFile="gzoltar.ser"
    outputDirectory="fault-localization-reports">
  <flFamilies>
    <flFamily name="sfl">
      <formulas>
        <formula name="barinel"/>
        <formula name="dstar"/>
        <formula name="ochiai"/>
        <formula name="tarantula"/>
        ...
      </formulas>
      <metrics>
        <metric name="rho"/>
        <metric name="uniqueness"/>
        <metric name="entropy"/>
        ...
      </metrics>
      <formatters>
        <txt/>
        <html views="sunburst:vertical_partition"/>
      </formatters>
    </flFamily>
  </flFamilies>
</gzoltar:fl-report>

The above configuration will generate two Spectrum-based Fault Localization reports (a text-based report and a html-based report) for the following fault localization formulas:

  • Barinel
  • DStar
  • Ochiai
  • Tarantula

to a default directory fault-localization-reports. For instance the text-based report for the Ochiai formula can be found in fault-localization-reports/sfl/txt/ochiai.ranking.csv and the html-based report for the same formula in fault-localization-reports/sfl/html/ochiai/sunburst.html.

In fault-localization-reports/sfl/txt/ four additional files can also be found:

  • matrix.txt - a binary coverage matrix produced by GZoltar where each row represents the coverage of each individual test case and its outcome ("-" if the test case failed, "+" otherwise), and each column a component (e.g., line of code). 1 means that a test case covered a component, 0 otherwise.
  • spectra.csv - a list of all components identified by GZoltar (one per row) of all instrumented classes.
  • tests.csv - a list of all test cases listened by GZoltar's listener (one per row).
  • statistics.csv - a set of metrics (default: matrix density (rho), component ambiguity score (ambiguity), and entropy) for each fault localization formula. Each row represents a metric of a formula (e.g., the entropy of the ranking returned by Ochiai formula). Thus, the total number of rows in this file is number of fault localization formulas * number of metrics.