jacoco2lcov - Translate JaCoCo execution data to lcov format

Manual section:

1

Manual group:

LCOV Tools

NAME

jacoco2lcov

Translate JaCoCo execution data to lcov format

SYNOPSIS

jacoco2lcov [--output mydata.info] [options] execfile+

DESCRIPTION

jacoco2lcov translates the execution data which JaCoCo collected while your Java tests ran into LCOV .info format.

It does none of the translation itself: it is a wrapper which runs, in order, the two commands you would otherwise run by hand -

  • java -jar jacococli.jar report ... --xml tmp.xml, to turn the .exec execution data files into a JaCoCo XML report, and

  • xml2lcov --format jacoco ... tmp.xml, to translate that report into LCOV .info format -

and then reads the LCOV format .info file generated by xml2lcov, applies the common LCOV options - filtering, exclusions, etc. - and writes the result to the output file. The data is read and written by the same code every other tool in the suite uses, so jacoco2lcov supports every common option - see OPTIONS.

The intermediate files are temporary and are removed when jacoco2lcov finishes; use --xml to keep the XML report.

Either of the two steps can be run independently if you want or need to - say, because you need additional options or flags that are not supported by the script.

What JaCoCo needs to be told

A JaCoCo .exec file holds execution data but not the names of the classes it refers to or their source. Thus, at least one class location has to be named, with --classpath: JaCoCo reads the coverage counts out of the class files, and cannot write a report without them. At least one source directory has to be named as well, with --source-directory, because a JaCoCo report names no search path of its own and xml2lcov has to find the sources to translate them. --plugin-directory is a shorthand for both when your code is laid out in the usual Eclipse or Maven way.

With none of --classpath, --source-directory and --plugin-directory given, the current directory is searched as --plugin-directory . would search it. That finds the source and class directories of a project laid out either of those ways - src/main/java and target/classes for Maven, src and bin for Eclipse - and of a directory holding several such projects, in which case each of them contributes the directories it has. jacoco2lcov says so when it does this, and stops if it finds nothing: a layout it does not recognize, or classes somewhere else your build put them, still has to be named. It is a convenience for the usual case, not a search: nothing is looked for outside the conventional places, and nothing is guessed from file extensions.

Coverage types

JaCoCo data always contains branch and function coverage - so jacoco2lcov enables both of them by default. Use command line and/or config file options to change this behaviour, if desired.

There is no MC/DC or condition coverage to write: JaCoCo does not collect it.

Source versions

A JaCoCo report does not say which version of the source it describes, so there is no version in the data to carry through - unlike a lcov --capture, which records the version of each file it finds. --version-script therefore means "compute the version", and jacoco2lcov turns compute_file_version on for you when you name one: the callback is applied to each file as the translated data is read back in, and the VER: records it returns are written to the output. Say --rc compute_file_version=0 if you want the callback used for nothing but comparisons.

Without a version script there is no version to record, and a report generated from the result has nothing to check the source it reads against - so genhtml(1) will stop with a version error if it is asked to compute versions itself.

Consistency

JaCoCo counts instructions and branches rather than executions, so the execution counts in the translated data are derived, and LCOV may consider the result internally inconsistent - most often because JaCoCo reports a line as covered whose branches it never saw evaluated. See the JaCoCo conversion notes section of xml2lcov(1) for why the derived data appears as it does. If you need to work around the inconsistent error which is reported, either exclude the offending code or add --ignore-errors inconsistent to your command line.

The same inconsistent error is generated when a function is marked "not executed" but contains a line which is covered - for example, function 'com.example.Widget.dead()V' is not hit but line 8 is. A JaCoCo method contains a 'begin' line but no information about where it ends - so the range of lines contained within the function is derived from the line data and source text. This can erroneously claim a line belonging to another method. The message can be suppressed via --ignore-errors inconsistent. See the JaCoCo conversion notes section of xml2lcov(1).

Merging

If you have execution data from more than one test run, hand all of the .exec files to a single jacoco2lcov command rather than translating each of them and merging the results with lcov -a: JaCoCo can combine per-branch data exactly and the translated data cannot. See Merging JaCoCo data in xml2lcov(1).

OPTIONS

In addition to the common options supported by the other tools in the LCOV suite (e.g., --exclude, --include, --filter, --substitute, --omit-lines, --erase-functions, --ignore-errors, --comment, --version-script, etc.), which are applied to the translated data, the tool options are the ones below.

Each of them is marked optional or required, and the default of each is given. Nothing but the .exec files is required unconditionally: the rest of what jacoco2lcov has to know it can get from the environment or from the layout of the directory it is run in.

execfile

One or more JaCoCo .exec execution data files or directories which are searched for .exec files. Every argument which is not an option is taken to name execution data, whatever it is called: .exec is a convention and nothing here depends on it. Required.

-o, --output file

Optional. Specify the output LCOV .info file. Default: jacoco2lcov.info in the current directory.

-t, --test-name, --testname name

Optional. Specify the test name for the TN: entry in the LCOV .info file. Default: none - the TN: entry is empty.

-d, --root-directory directory

Optional. The run directory and root of relative paths to source, class execution data files, and the output file. Default: the directory jacoco2lcov was run in.

-c, --classpath, --classfiles path

A directory or .jar file containing the class files whose coverage JaCoCo recorded. JaCoCo reads the coverage counts out of the class files, so it cannot write a report without them. Required, unless -p names them or the default search below finds them. May be specified multiple times. Default: none.

-s, --source-directory, --source-dir directory

A root directory of your Java sources - that is, one of the directories you would pass to javac, such that the name of a package, used as a directory path, names the directory holding that package's sources. Required, unless -p names them or the default search below finds them. May be specified multiple times. Default: none.

-p, --plugin-directory, --plugin-dir directory

Optional. The root of an Eclipse/Maven plugin, or the parent directory of several of them, to be searched for source and class directories in the usual places (src, src/java, src/main/java, src/test/java and bin, classes, target/classes). This is a shorthand for the -s and -c options which such a directory implies. May be specified multiple times. Default: with none of -s, -c and -p given, the current directory is searched as -p . would search it - see What JaCoCo needs to be told above.

--jar jacococli.jar

Optional if the environment names the jar, required if it does not. Path to the JaCoCo command line jar. Default: the jar named by the JACOCOCLI_JAR environment variable, else the one found under the directory named by JACOCO_HOME.

--java executable

Optional. The java executable used to run the JaCoCo command line jar. Default: $JAVA_HOME/bin/java if that is an executable, else java, found on your PATH.

--xml file

Optional. Write the intermediate JaCoCo XML report to the named file and keep it. Default: a temporary file, removed when jacoco2lcov exits.

--xml2lcov path

Optional. The xml2lcov executable to use. Default: the one installed next to jacoco2lcov. On Windows, a wrapper which Windows can run - an xml2lcov.bat, say - is preferred to the extensionless script beside it.

-v, --verbose

Optional. Print each command before it is run. Default: off - only warnings, errors and notices are printed.

-k, --keep-going

Optional. Ignore errors and continue processing. Default: off - stop at the first error.

-h, --help

Print usage information and exit.

Common options

Every other option jacoco2lcov accepts is one the rest of the suite accepts, and means here what it means there - it is applied to the translated data:

$ jacoco2lcov -o mydata.info -s src -c bin --exclude='*/test/*' \
      --filter branch mytest.exec

See lcov(1) and lcovrc(5) for details of these options and of the configuration settings which also reach them.

EXAMPLES

  # run your tests with the JaCoCo agent attached, to collect coverage
$ java -javaagent:jacocoagent.jar=destfile=test1.exec -cp bin MyTest1
$ java -javaagent:jacocoagent.jar=destfile=test2.exec -cp bin MyTest2

  # translate all of the execution data in one step
$ jacoco2lcov -o mydata.info -s src -c bin test1.exec test2.exec

  # the same, run from the root of a conventionally laid out project:  with
  # no directory named, the ones the layout implies are used
$ jacoco2lcov -o mydata.info test1.exec test2.exec

  # the same, for a directory of Eclipse/Maven plugins, keeping the
  # intermediate XML report and dropping the test sources from the result
$ jacoco2lcov -o mydata.info -p plugins --xml jacoco.xml \
    --exclude '*/src/test/java/*' test1.exec test2.exec

  # a build which wrote one .exec file per test below a results directory,
  # translated from the directory the rest of your coverage data is
  # relative to:  naming that directory is what makes the file names in the
  # result line up with it
$ jacoco2lcov -d /work/myproject -o mydata.info -p plugins results

  # and generate an HTML coverage report.  JaCoCo reports lines as covered
  # whose branches it never saw evaluated, which genhtml considers
  # inconsistent - see 'Consistency' above
$ genhtml -o html_report mydata.info --branch-coverage \
    --ignore-errors inconsistent

ENVIRONMENT

JACOCOCLI_JAR

The JaCoCo command line jar to run, if --jar does not name one.

JACOCO_HOME

The root of a JaCoCo installation, searched for lib/jacococli.jar and then jacococli.jar if neither --jar nor JACOCOCLI_JAR names a jar.

JAVA_HOME

The root of the Java installation whose bin/java is used to run the JaCoCo command line jar, if --java does not name one.

AUTHOR

Henry Cox <henry.cox@mediatek.com>

SEE ALSO

lcov(1), genhtml(1), xml2lcov(1)