code-coverage.md

Code Coverage Support for PDFium

[TOC]

This guide explains how to generate code coverage information for the PDFium library on a local computer.

Prerequisites

You will need the PDFium source code on your computer. You can see the README for instructions on checking out PDFium's source.

The tools used for code coverage are known to work on Ubuntu and Debian. They should work correctly on newer versions of Ubuntu, Debian and related Linux distros. They have not been tested on Windows and Mac.

Previously, the code coverage scripts required specific versions of lcov and llvm-cov to be present. This is no longer true, so if you have no other need for them they can be removed. All of the required tools will be pulled into the Clang build tools directory by the script.

Generating Code Coverage

Setup

This step assumes that you have already checked out the PDFium source code. If you have not, please consult the Prerequisites section above.

Before generating code coverage information, you will need to have a build directory with coverage enabled. This can be done by running the gn args command and adding use_clang_coverage = true in the editor that is opened.

If not using the default directory, out/Coverage, then replace it with the correct location in the following command.

gn args out/Coverage

If you already have a build directory, you can append the coverage flag to the existing args.gn as follows. If not using the default directory, out/Coverage, then replace it with the correct location in the following command.

echo "use_clang_coverage = true" >> out/Coverage/args.gn

Previous versions of code coverage used use_coverage = true in args.gn; this needs to be changed to use_clang_coverage = true

Usage

Generating code coverage information is done via the testing/tools/coverage/coverage_report.py script. This script will download the Clang coverage tools if needed, build any binaries that it needs, perform test runs, collect coverage data, and generate a HTML coverage report. It is based on the Chromium coverage scripts, so will generate the same style of report.

Running the script with no arguments, as below, it will assume that you are currently at the root of your PDFium checkout, the build directory to use is ./out/Coverage/ and that HTML should be outputted to ./coverage_report/.

testing/tools/coverage/coverage_report.py

If the current working directory is not the root of your PDFium checkout, then you will need to pass in --source-directory with the appropriate directory. If you are using a different build directory, then --build-directory will need to be passed in. Finally, if you want the HTML report in a different location then you will need to pass in --output-directory.

An example of all these flags being used:

testing/tools/coverage/coverage_report.py \
    --source-directory ~/pdfium/pdfium \
    --build-directory ~/pdfium/pdfium/out/Debug_with_Coverage \
    --output-directory ~/Documents/PDFium_coverage

To run different tests than the default set, including running just a single test, you can specify the test names on the command line. The list of supported tests can be found by running the script with --help.

For example, running all of the tests that don't use pdfium_test:

testing/tools/coverage/coverage_report.py pdfium_unittests pdfium_embeddertests

NOTE: At the present time, there is no mechanism for combining data from different invocations of coverage_report.py. Instead, you must specify all of the tests to be included in the report in a single invocation. Alternatively, you can collect the profiling data that is generated from each run and manually invoke tools/code_coverage/coverage.py to generate a combined report.

There are additional developer debugging flags available, --dry-run and --verbose. --dry-run will output a trace of commands that would have been run, but doesn't actually execute them. --verbose turns on outputting additional logging information.

Viewing

Once the script has run, the output directory should contain a set of HTML files containing the coverage report.

These files are static HTML, so you can point your browser at them directly on your local file system and they should render fine. You can also serve them via a web server if you want, but how to achieve that is beyond the scope of this documentation.

Issues

For help with using the code coverage tools please contact the PDFium maintainers via the PDFium mailing list.

Please file bugs against the code coverage support here.