CLI

Displayed below is the full reference of flacoco CLI. You can always obtain this information by running flacoco with the option --help.

Usage: FlacocoMain [-hVv] [--coverTest] [--includeZeros] [--testRunnerVerbose]
                   [-o[=<output>]] [-c=<classpath>]
                   [--complianceLevel=<complianceLevel>] [-f=<spectrumFormula>]
                   [--jacocoClasspath=<customJacocoClasspath>]
                   [--junitClasspath=<customJUnitClasspath>]
                   [--mavenHome=<mavenHome>] [-p=<projectPath>]
                   [--testDetectionStrategy=<testDetectionStrategy>]
                   [--testRunnerJVMArgs=<testRunnerJVMArgs>]
                   [--testRunnerTimeoutInMs=<testRunnerTimeoutInMs>]
                   [--threshold=<threshold>] [-w=<workspace>]
                   [--ignoredTests=<ignoredTests>]...
                   [--jacocoExcludes=<jacocoExcludes>]...
                   [--jacocoIncludes=<jacocoIncludes>]... [--binJavaDir
                   [=<binJavaDir>...]]... [--binTestDir[=<binTestDir>...]]...
                   [--srcJavaDir[=<srcJavaDir>...]]... [--srcTestDir
                   [=<srcTestDir>...]]... [[--format=<format>] |
                   --formatter=<customExporter>]
                   [[--junit4tests=<jUnit4Tests>]...
                   [--junit5tests=<jUnit5Tests>]...]
Flacoco: fault localization
      --binJavaDir[=<binJavaDir>...]
                            Paths to the directories containing java class
                              files. Defaults to {projectpath}/target/classes
      --binTestDir[=<binTestDir>...]
                            Paths to the directories containing java test class
                              files. Defaults to {projectpath}
                              /target/test-classes
  -c, --classpath=<classpath>
                            Classpath of the project under analyzis.
      --complianceLevel=<complianceLevel>
                            Compliance level for Spoon. Default value is 8
      --coverTest           Indicates if coverage must also cover the tests.
  -f, --formula=<spectrumFormula>
                            Spectrum formula to use. Valid values: OCHIAI
      --format=<format>     Format of the output. Valid values: CSV, JSON
      --formatter=<customExporter>
                            Path to java file of a custom FlacocoExporter.
  -h, --help                Show this help message and exit.
      --ignoredTests=<ignoredTests>
                            Tests to be ignored during test execution. Both
                              qualified class and qualified method names are
                              supported.
      --includeZeros        Flag for including lines with a suspiciousness sore
                              of 0.
      --jacocoClasspath=<customJacocoClasspath>
                            Classpath to jacoco dependencies.
      --jacocoExcludes=<jacocoExcludes>
                            Class patterns to be excluded by jacoco
      --jacocoIncludes=<jacocoIncludes>
                            Class patterns to be recorded in by jacoco
      --junitClasspath=<customJUnitClasspath>
                            Classpath to junit dependencies.
      --mavenHome=<mavenHome>
                            Path to maven home.
  -o, --output[=<output>]   Path to the output file. If no path is provided but
                              the flag is, the result will be stored in
                              flacoco_result.{extension}
  -p, --projectpath=<projectPath>
                            Path to the project to analyze.
      --srcJavaDir[=<srcJavaDir>...]
                            Paths to the directories containing java source
                              files. Defaults to {projectpath}/src/main/java
      --srcTestDir[=<srcTestDir>...]
                            Paths to the directories containing java test
                              source files. Defaults to {projectpath}/src/test
      --testDetectionStrategy=<testDetectionStrategy>
                            Strategy for test detection stage. Defaults to
                              CLASSLOADER. Valid values: TEST_RUNNER,
                              CLASSLOADER
      --testRunnerJVMArgs=<testRunnerJVMArgs>
                            JVM args for test-runner's test execution VMs.
      --testRunnerTimeoutInMs=<testRunnerTimeoutInMs>
                            Timeout for each test execution with test-runner.
                              Must be greater than 0. Default value is 1000000
      --testRunnerVerbose   Test-runner verbose mode.
      --threshold=<threshold>
                            Threshold for suspiciousness score. Flacoco will
                              only return suspicious results with score >=
                              threshold. Results with a score of 0 are only
                              included if the -includeZeros flag is set.
  -v                        Verbose mode.
  -V, --version             Print version information and exit.
  -w, --workspace=<workspace>
                            Path to the workspace directory of flacoco.
Setting any of these options will result in test detection being bypassed.     
      --junit4tests=<jUnit4Tests>
                            JUnit4 or JUnit3 tests to be ran.
      --junit5tests=<jUnit5Tests>
                            JUnit5 tests to be ran.

Default Exporters

By default, Flacoco can output the results in the JSON and CSV formats.

The format is selected by using the --format option, followed by either JSON or CSV.

JSON example

[{"className":"fr.spoonlabs.FLtest1.Calculator","lineNumber":15,"suspiciousness":1.0},{"className":"fr.spoonlabs.FLtest1.Calculator","lineNumber":14,"suspiciousness":0.7071067811865475},{"className":"fr.spoonlabs.FLtest1.Calculator","lineNumber":12,"suspiciousness":0.5773502691896258},{"className":"fr.spoonlabs.FLtest1.Calculator","lineNumber":5,"suspiciousness":0.5},{"className":"fr.spoonlabs.FLtest1.Calculator","lineNumber":6,"suspiciousness":0.5},{"className":"fr.spoonlabs.FLtest1.Calculator","lineNumber":10,"suspiciousness":0.5}]

CSV example

fr.spoonlabs.FLtest1.Calculator,15,1.0
fr.spoonlabs.FLtest1.Calculator,14,0.7071067811865475
fr.spoonlabs.FLtest1.Calculator,12,0.5773502691896258
fr.spoonlabs.FLtest1.Calculator,5,0.5
fr.spoonlabs.FLtest1.Calculator,6,0.5
fr.spoonlabs.FLtest1.Calculator,10,0.5

Custom FlacocoExporter

If the exporting options do not fit your needs, you can write your own FlacocoExporter and pass it to flacoco in runtime.

For example, below, we have implemented OneLineExporter, a FlacocoExporter implementation that writes the results all in one line:

import fr.spoonlabs.flacoco.api.result.FlacocoResult;
import fr.spoonlabs.flacoco.api.result.Location;
import fr.spoonlabs.flacoco.api.result.Suspiciousness;

import java.io.IOException;
import java.io.OutputStreamWriter;
import java.util.Map;

public class OneLineExporter implements fr.spoonlabs.flacoco.cli.export.FlacocoExporter {

	@Override
	public void export(FlacocoResult result, OutputStreamWriter outputStream) throws IOException {
		for (Map.Entry<Location, Suspiciousness> entry : result.getDefaultSuspiciousnessMap().entrySet()) {
			outputStream.write(entry.getKey() + "," + entry.getValue().getScore());
		}
	}

	@Override
	public String extension() {
		return "custom";
	}
}

To use this formatter in runtime, we can simply provide the path to the .java file to flacoco:

java -jar target/flacoco-1.0.0-jar-with-dependencies.jar -p "examples/exampleFL1/FLtest1/" --formatter "src/test/resources/OneLineExporter.java"