py2lcov - Translate Python Coverage.py data to lcov format

Manual section:

1

Manual group:

LCOV Tools

NAME

py2lcov

Translate Python Coverage.py data to lcov format

SYNOPSIS

py2lcov [--output mydata.info] [--test-name name] [options] coverage.dat+

DESCRIPTION

py2lcov traverses Python coverage data in one or more coverage data files (generated by the Coverage.py module) and translates it into LCOV .info format.

Note that the --no-functions argument may result in subtly inconsistent coverage data if a no-functions coverage DB is merged with one which contains derived function data. This is because the def myFunc(...) line will acquire a hit count of 1 (the Python interpreter considers the def to have been executed when the line is interpreted, i.e., when the function is defined). This will generate an inconsistent error if the function is not executed in your tests because the (derived) function will have a zero hit count but the first line of the function has a non-zero count.

Best practice: Either always specify --no-functions or never specify --no-functions.

py2lcov uses Coverage.py to extract coverage data. The name of the Coverage.py executable may differ on your platform. By default, py2lcov uses coverage (expected to be in your PATH). You can use a different executable via the COVERAGE_COMMAND environment variable or the --cmd command line option.

py2lcov does not implement the full suite of LCOV features (e.g., filtering, substitutions, etc.). Generate the translated LCOV format file and then read the data back into lcov to use those features.

Branch Coverage Limitations

Note that the XML coverage data format does not contain enough information to deduce exactly which branch expressions have been taken or not taken. It reports the total number of branch expressions associated with a particular line, and the number of those which have been taken. There is no way to know (except, possibly by inspection of surrounding code and/or some understanding of your implementation) exactly which ones.

This is a problem in at least 2 ways:

  • It is not straightforward to use the result to improve your regression suite because you don’t really know what was exercised/not exercised.

  • Coverage data merge is problematic. For example: you have two testcase XML files, each of which hit 4 of 8 branches on some line. Does that mean you hit 4 of them (both tests exercised the same code), all 8 (tests exercised disjoint subsets), or some number between?

This implementation assumes that the first M branches are the ones which are hit and the remaining N-M were not hit, in each testcase. Thus, the combined result in the above example would claim 4 of 8 branches hit. This definition turns out to be a lower bound.

OPTIONS

-i, --input file

DEPRECATED: Specify the input XML file from coverage.py.

-o, --output file

Specify the output LCOV .info file. Default: py2lcov.info.

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

Specify the test name for the TN: entry in the LCOV .info file.

-e, --exclude patterns

Specify exclude file patterns separated by commas.

-v, --verbose

Print debug messages.

--version-script script

Version extract callback script.

--checksum

Compute line checksum. See lcov(1).

--no-functions

Do not derive function coverpoints.

--tabwidth n

Tab size when computing indent. Default: 8.

-k, --keep-going

Ignore errors and continue processing.

--cmd executable

Executable used to extract Python coverage data (e.g., python3-coverage). Default: coverage (or value from COVERAGE_COMMAND environment variable).

Note that py2lcov is a stand-alone Python executable - and so does not directly support the standard LCOV command line and RC options - e.g., for filtering, file inclusion and exclusion, etc. To use these options, you will have to first use py2lcov to capture your coverage DB, and then apply the options you want to use via lcov -a pycov.info <options> .... See lcov(1) for details.

EXAMPLES

Basic workflow:

$ export PYCOV_DATA=path/to/pydata

# For 'coverage' versions 6.6.1 and higher (support "--data-file"):
$ coverage run --data-file=${PYCOV_DATA} --append --branch \
    /path/to/myPythonScript.py args_to_my_python_script

# For older versions without "--data-file" support:
$ COVERAGE_FILE=${PYCOV_DATA} coverage run --append --branch \
    /path/to/myPythonScript.py args_to_my_python_script

# Translate to LCOV format:
$ py2lcov -o pydata.info ${PYCOV_DATA}

# Apply filtering:
$ lcov -a pydata.info -o filtered.info --filter branch,blank

# Generate HTML report:
$ genhtml -o html_report pydata.info

# Generate filtered report:
$ genhtml -o html_filtered filtered.info

# Use differential coverage to see what filtering did:
$ genhtml -o html_differential --baseline-file mydata.info filtered.info

Deprecated XML input mode:

# First translate from Python coverage data to XML:
$ coverage xml --data-file=${PYCOV_DATA} -o pydata.xml

# Then translate XML to LCOV format:
$ py2lcov -i pydata.xml -o pydata.info --version-script myCovScript

ENVIRONMENT

COVERAGE_COMMAND

Override the default coverage executable used to extract Python coverage data.

COVERAGE_FILE

Default input file if no files are specified on the command line.

AUTHOR

Henry Cox <henry.cox@mediatek.com>

SEE ALSO

lcov(1), genhtml(1), geninfo(1)