Home

Getting Started

Welcome to the flacoco wiki!

flacoco is a fault localization tool for Java based on Jacoco and test-runner that aims at encompassing several fault localization techniques.

Installation

flacoco's releases are available on Maven Central:

<dependency>
  <groupId>com.github.spoonlabs</groupId>
  <artifactId>flacoco</artifactId>
  <version>1.0.6</version>
</dependency>

flacoco's snapshots are deployed on par with master on Sonatype:

<repositories>
  <repository>
    <id>sonatype</id>
    <url>https://oss.sonatype.org/content/repositories/snapshots</url>
    <snapshots />
  </repository>
</repositories>

<dependency>
  <groupId>com.github.spoonlabs</groupId>
  <artifactId>flacoco</artifactId>
  <version>1.0.7-SNAPSHOT</version>
</dependency>

Usage

flacoco can currently be used through the API or the command line interface.

Usage through the API

The following example illustrates a common usage of the flacoco API, where we run flacoco on a test project using spectrum-based fault localization with the Ochiai formula. As a result, we obtain a mapping between suspicious lines and suspiciousness scores.

Example usage:

FlacocoConfig config = new FlacocoConfig();
config.setProjectPath("./examples/exampleFL1/FLtest1");
config.setClasspath(classpath);
config.setFamily(FlacocoConfig.FaultLocalizationFamily.SPECTRUM_BASED);
config.setSpectrumFormula(SpectrumFormula.OCHIAI);

Flacoco flacoco = new Flacoco(config);

FlacocoResult result = flacoco.run();

Set<TestMethod> failingTests = result.getFailingTests();
Map<Location, Suspiciousness> mapping = result.getDefaultSuspiciousnessMap();

Full reference can be found under API.

Usage through the CLI

Currently, there are two ways of using the flacoco cli. The following examples illustrate the aforementioned example. Note that we omitted the family and spectrum formula options since they are the default.

java -cp 'target/flacoco-1.0.6-jar-with-dependencies.jar' fr.spoonlabs.flacoco.cli.FlacocoMain --projectpath examples/exampleFL1/FLtest1/

java -jar target/flacoco-1.0.6-jar-with-dependencies.jar --projectpath examples/exampleFL1/FLtest1/

Full reference can be found under CLI.

Development Environment

To run the test suite locally, it is necessary to take two steps beforehand.

First, we must set the environment variable SRC_VERSION. This is necessary as flacoco's development setup compiles and tests examples with different target versions. See our CI config for further info on the range of target versions.

Secondly, we must install the example projects on which flacoco will be run.

For example, if we want to run the test suite with Java 8 as the target version, we must run:

export SRC_VERSION=8
./.github/install_examples.sh
mvn test