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