1# Code Coverage Support for PDFium 2 3[TOC] 4 5This guide explains how to generate code coverage information for the PDFium 6library on a local computer. 7 8## Prerequisites 9 10You will need the PDFium source code on your computer. You can see 11the [README](/README.md) for instructions on checking out PDFium's source. 12 13The tools used for code coverage are known to work on Ubuntu 14.04. They should 14work correctly on newer versions of Ubuntu and related Linux distros. They have 15not been tested on Windows and Mac. 16 17### lcov 18 19The code coverage scripts depend on having a version of `lcov` of 1.11 or 20greater available, which is enforced by the script. Unfortunately the default 21version of `lcov` for Ubuntu 14.04 is 1.10, thus you will need to install a 22newer version. 23 24You can build a newer version of `lcov` from source, which is 25available [here](http://ltp.sourceforge.net/coverage/lcov.php). 26 27If you don't want to build from source and use an RPM based Linux, not 28Ubuntu/Debian, then there are pre-built RPMs 29available [here](http://downloads.sourceforge.net/ltp/lcov-1.13-1.noarch.rpm). 30 31For Ubuntu/Debian users these RPMs can be converted to .deb using `alien`. More 32information about how to do this can be found in `man alien`. 33 34### llvm-cov 35 36The other external dependency for generating code coverage information is having 37a version of `llvm-cov` that supports the `gcov` command. This should be all 38versions of 3.5.0 or greater. 39 40Again, unfortunately, the default llvm-cov that comes with Ubuntu 14.04, 3.4, is 41lower then what is needed. The 14.04 repositories do support having multiple 42versions of the `llvm` package, and thus `llvm-cov`. Through your favourite 43package manager you should be able to install any version of `llvm` of 3.5 or 44greater and the coverage scripts should find it. 45 46## Generating Code Coverage 47 48### Setup 49 50This step assumes that you have already checked out the PDFium source code and 51installed the proper versions of the external tools. If you have not, please 52consult the above Prerequisites section. 53 54Before generating code coverage information, you will need to have a build 55directory with coverage enabled. This can be done by running the `gn args` 56command and adding `use_coverage = true` in the editor that is opened. If not 57using the default directory, `out/Coverage`, then replace it with the correct 58location in the following command. 59 60```shell 61gn args out/Coverage 62``` 63 64If you already have a build directory, you can append the coverage flag to the 65existing `args.gn` as follows. If not using the default directory, 66`out/Coverage`, then replace it with the correct location in the following 67command. 68 69```shell 70echo "use_coverage = true" >> out/Coverage/args.gn 71``` 72 73 74### Usage 75 76Generating code coverage information is done via the 77`testing/tools/coverage/coverage_report.py` script. This script will build any binaries 78that it needs, perform test runs, collect coverage data, and finally generate a 79nice HTML coverage report. 80 81Running the script with no arguments, as below, will assume that you are 82currently at the root of your PDFium checkout, the build directory to use is 83`./out/Coverage/` and that HTML should be outputted to `./coverage_report/`. By 84default, it will also only run `pdfium_unittests` and `pdfium_embeddertests` for 85coverage data. This is because the other tests are known to take a long time to 86run, so they are not included in the defaults. 87 88```shell 89testing/tools/coverage/coverage_report.py 90``` 91 92If the current working directory is not the root of your PDFium checkout, then 93you will need to pass in `--source-directory` with the appropriate directory. If 94you are using a different build directory, then `--build-directory` will need to 95be passed in. Finally, if you want the HTML report in a different location then 96you will need to pass in `--output-directory`. 97 98An example of all these flags being used: 99 100```shell 101testing/tools/coverage/coverage_report.py \ 102 --source-directory ~/pdfium/pdfium \ 103 --build-directory ~/pdfium/pdfium/out/Debug_with_Coverage \ 104 --output-directory ~/Documents/PDFium_coverage 105``` 106 107To run different tests then the default set, there are two ways to achieve 108this. If you want to run everything, including tests that are known to take a 109long time, then you just need to add the `--slow` flag. 110 111```shell 112testing/tools/coverage/coverage_report.py --slow 113``` 114 115If you want more fine grained control, including running just a single test, you 116can specify the test names on the command line. The `--slow` flag is not needed 117if you are explicitly invoking tests. The list of supported tests can be found 118by running the script with `--help`. 119 120An example running the default tests explicitly: 121 122```shell 123testing/tools/coverage/coverage_report.py pdfium_unittests pdfium_embeddertests 124``` 125 126NOTE: 127At the present time, there is no mechanism for combining data from different 128invocations of `coverage_report.py`. Instead you must specify all of the tests 129to be included in the report in a single invocation. 130 131There are additional developer debugging flags available, `--dry-run` and 132`--verbose`. `--dry-run` will output a trace of commands that would have been 133run, but doesn't actually execute them. `--verbose` turns on outputting 134additional logging information. 135 136### Viewing 137 138Once the script has run, the output directory should contain a set of HTML files 139containing the coverage report. 140 141These files are static HTML, so you can point your browser at them directly on 142your local file system and they should render fine. You can also serve them via a 143web server if you want, but how to achieve that is beyond the scope of this 144documentation. 145 146## Issues 147 148For help with using the code coverage tools please contact the PDFium 149maintainers via the PDFium 150mailing [list](https://groups.google.com/forum/#!forum/pdfium). 151 152Please file bugs against the code coverage 153support [here](https://bugs.chromium.org/p/pdfium/issues/list). 154