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 and Debian. They 14should work correctly on newer versions of Ubuntu, Debian and related Linux 15distros. They have not been tested on Windows and Mac. 16 17Previously, the code coverage scripts required specific versions of `lcov` and 18`llvm-cov` to be present. This is no longer true, so if you have no other need 19for them they can be removed. All of the required tools will be pulled into the 20Clang build tools directory by the script. 21 22## Generating Code Coverage 23 24### Setup 25 26This step assumes that you have already checked out the PDFium source code. If 27you have not, please consult the Prerequisites section above. 28 29Before generating code coverage information, you will need to have a build 30directory with coverage enabled. This can be done by running the `gn args` 31command and adding `use_clang_coverage = true` in the editor that is opened. 32 33If not using the default directory, `out/Coverage`, then replace it with the 34correct location in the following command. 35 36```shell 37gn args out/Coverage 38``` 39 40If you already have a build directory, you can append the coverage flag to the 41existing `args.gn` as follows. If not using the default directory, 42`out/Coverage`, then replace it with the correct location in the following 43command. 44 45```shell 46echo "use_clang_coverage = true" >> out/Coverage/args.gn 47``` 48 49Previous versions of code coverage used **use_coverage = true** in args.gn; this 50needs to be changed to **use_clang_coverage = true** 51 52### Usage 53 54Generating code coverage information is done via the 55`testing/tools/coverage/coverage_report.py` script. This script will download 56the Clang coverage tools if needed, build any binaries that it needs, perform 57test runs, collect coverage data, and generate a HTML coverage report. It is 58based on the Chromium coverage scripts, so will generate the same style of 59report. 60 61Running the script with no arguments, as below, it will assume that you are 62currently at the root of your PDFium checkout, the build directory to use is 63`./out/Coverage/` and that HTML should be outputted to `./coverage_report/`. 64 65```shell 66testing/tools/coverage/coverage_report.py 67``` 68 69If the current working directory is not the root of your PDFium checkout, then 70you will need to pass in `--source-directory` with the appropriate directory. If 71you are using a different build directory, then `--build-directory` will need to 72be passed in. Finally, if you want the HTML report in a different location then 73you will need to pass in `--output-directory`. 74 75An example of all these flags being used: 76 77```shell 78testing/tools/coverage/coverage_report.py \ 79 --source-directory ~/pdfium/pdfium \ 80 --build-directory ~/pdfium/pdfium/out/Debug_with_Coverage \ 81 --output-directory ~/Documents/PDFium_coverage 82``` 83 84To run different tests than the default set, including running just a single 85test, you can specify the test names on the command line. The list of supported 86tests can be found by running the script with `--help`. 87 88For example, running all of the tests that don't use pdfium_test: 89 90```shell 91testing/tools/coverage/coverage_report.py pdfium_unittests pdfium_embeddertests 92``` 93 94NOTE: At the present time, there is no mechanism for combining data from 95different invocations of `coverage_report.py`. Instead, you must specify all of 96the tests to be included in the report in a single invocation. Alternatively, 97you can collect the profiling data that is generated from each run and manually 98invoke `tools/code_coverage/coverage.py` to generate a combined report. 99 100There are additional developer debugging flags available, `--dry-run` and 101`--verbose`. `--dry-run` will output a trace of commands that would have been 102run, but doesn't actually execute them. `--verbose` turns on outputting 103additional logging information. 104 105### Viewing 106 107Once the script has run, the output directory should contain a set of HTML files 108containing the coverage report. 109 110These files are static HTML, so you can point your browser at them directly on 111your local file system and they should render fine. You can also serve them via a 112web server if you want, but how to achieve that is beyond the scope of this 113documentation. 114 115## Issues 116 117For help with using the code coverage tools please contact the PDFium 118maintainers via the PDFium 119mailing [list](https://groups.google.com/forum/#!forum/pdfium). 120 121Please file bugs against the code coverage 122support [here](https://bugs.chromium.org/p/pdfium/issues/list). 123