This guide explains how to generate code coverage information for the PDFium library on a local computer.
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 14.04. They should work correctly on newer versions of Ubuntu and related Linux distros. They have not been tested on Windows and Mac.
The code coverage scripts depend on having a version of lcov of 1.11 or greater available, which is enforced by the script. Unfortunately the default version of lcov for Ubuntu 14.04 is 1.10, thus you will need to install a newer version.
You can build a newer version of lcov from source, which is available here.
If you don't want to build from source and use an RPM based Linux, not Ubuntu/Debian, then there are pre-built RPMs available here.
For Ubuntu/Debian users these RPMs can be converted to .deb using alien. More information about how to do this can be found in man alien.
The other external dependency for generating code coverage information is having a version of llvm-cov that supports the gcov command. This should be all versions of 3.5.0 or greater.
Again, unfortunately, the default llvm-cov that comes with Ubuntu 14.04, 3.4, is lower then what is needed. The 14.04 repositories do support having multiple versions of the llvm package, and thus llvm-cov. Through your favourite package manager you should be able to install any version of llvm of 3.5 or greater and the coverage scripts should find it.
This step assumes that you have already checked out the PDFium source code and installed the proper versions of the external tools. If you have not, please consult the above Prerequisites section.
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_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_coverage = true" >> out/Coverage/args.gn
Generating code coverage information is done via the testing/tools/coverage/coverage_report.py script. This script will build any binaries that it needs, perform test runs, collect coverage data, and finally generate a nice HTML coverage report.
Running the script with no arguments, as below, 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/. By default, it will also only run pdfium_unittests and pdfium_embeddertests for coverage data. This is because the other tests are known to take a long time to run, so they are not included in the defaults.
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 then the default set, there are two ways to achieve this. If you want to run everything, including tests that are known to take a long time, then you just need to add the --slow flag.
testing/tools/coverage/coverage_report.py --slow
If you want more fine grained control, including running just a single test, you can specify the test names on the command line. The --slow flag is not needed if you are explicitly invoking tests. The list of supported tests can be found by running the script with --help.
An example running the default tests explicitly:
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.
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.
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.
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.