| # 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](/README.md) 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. |
| |
| ### lcov |
| |
| 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](http://ltp.sourceforge.net/coverage/lcov.php). |
| |
| 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](http://downloads.sourceforge.net/ltp/lcov-1.13-1.noarch.rpm). |
| |
| 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`. |
| |
| ### llvm-cov |
| |
| 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. |
| |
| ## Generating Code Coverage |
| |
| ### Setup |
| |
| 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. |
| |
| ```shell |
| 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. |
| |
| ```shell |
| echo "use_coverage = true" >> out/Coverage/args.gn |
| ``` |
| |
| |
| ### Usage |
| |
| 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. |
| |
| ```shell |
| 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: |
| |
| ```shell |
| 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. |
| |
| ```shell |
| 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: |
| |
| ```shell |
| 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. |
| |
| ### 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](https://groups.google.com/forum/#!forum/pdfium). |
| |
| Please file bugs against the code coverage |
| support [here](https://bugs.chromium.org/p/pdfium/issues/list). |