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