third_party/googletest/README.chromium

   1 Name: Google Test: Google's C++ Testing Framework
   2 Short Name: googletest
   3 URL: https://github.com/google/googletest.git
   4 Version: unknown
   5 License: BSD
   6 License File: src/LICENSE
   7 Shipped: no
   8 Security critical: no
   9
  10 Google Test is imported as-is, to facilitate version bumping. However, the
  11 file/directory layout of Google Test is not yet considered stable. Therefore,
  12 until Google Test's layout stabilizes, Chromium code MUST NOT depend on it
  13 directly. Instead, Chromium code MUST:
  14
  15 * #include the headers in testing/gtest and testing/gmock
  16 * use //testing/gtest(:gtest_main) and //testing/gmock(:gmock_main) in BUILD.gn
  17   deps
  18
  19 This will allow us to adapt to Google Test changes with minimal disruption.
  20
  21
  22 ## Resources for Rolling Googletest in Chrome
  23
  24 ### What is Googletest
  25
  26 Googletest is an open source C++ testing framework developed by Google and used
  27 by Chromium. See the [User Guide](https://google.github.io/googletest/).
  28
  29 ### Where is Googletest
  30
  31 Googletest is developed in google3 and uses
  32 [copybara](https://github.com/google/copybara) to sync with the public GitHub
  33 repository.
  34
  35 * Development (Googler only): [google3/third\_party/googletest](http://google3/third_party/googletest/)
  36 * GitHub: https://github.com/google/googletest
  37 * Chromium mirror: https://chromium.googlesource.com/external/github.com/google/googletest/
  38 * Locally, [third\_party/googletest/src/](https://source.chromium.org/chromium/chromium/src/+/master:third_party/googletest/src/)
  39   is a copy of Googletest which is updated via `gclient sync` according to the
  40   `googletest revision` commit hash in the
  41   [DEPS file](https://source.chromium.org/chromium/chromium/src/+/master:DEPS;l=244?q=DEPS%20googletest)
  42
  43 ### Unblocking Googletest Rolls
  44
  45 1. Roll Googletest to include the breaking change
  46 * Find the hash (on GitHub) of the offending commit
  47   * If the change came from google3, the CL number can be found in the
  48     `PiperOrigin-RevId` footer of Copybara commits
  49 * On a fresh checkout, pull in the relevant change. Either:
  50   * Sync using the DEPS file
  51 ```
  52 roll-dep --roll-to=commitish src/third_party/googletest/src/
  53 gclient sync
  54 ```
  55   * Check out the commit directly
  56 ```
  57 cd third_party/googletest/src
  58 git remote add up https://github.com/google/googletest.git
  59 git checkout commitish
  60 ```
  61
  62 2. Observe errors
  63 * Ideally, this can be done by building locally.
  64   If the build is successful, this means the change does not affect your OS or
  65   your compiler flags differ from the trybots
  66 * Upload a CL with the added trybots from
  67   [Testing Changes to Chromium in Chromium](#testing-changes-to-chromium-in-chromium)
  68
  69 3. Make changes
  70 * To Chromium: create a CL including both the roll and other changes
  71 * To Googletest:
  72   * Make changes to [third\_party/googletest/src/](https://source.chromium.org/chromium/chromium/src/+/master:third_party/googletest/src/)
  73     and try building locally. If the fix is successful and you’re confident
  74     this change will work across all the trybots, create a PR on GitHub or a
  75     CL to google3 (Googler only) of the changes you made locally to
  76     [third\_party/googletest/src/](https://source.chromium.org/chromium/chromium/src/+/master:third_party/googletest/src/).
  77     See [Testing Changes to Googletest in Googletest](#testing-changes-to-googletest-in-googletest)
  78   * What if I need to make a change to Googletest, but I’m not confident it
  79     will work with Chromium? Maybe it has to do with a tricky compiler error
  80     that only affects a specific OS. See
  81     [Testing Changes to Googletest in Chromium](#testing-changes-to-googletest-in-chromium)
  82   * Once your Googletest change lands, create a roll which includes both the
  83     offending commit and your change
  84
  85 ### Testing Changes to Chromium in Chromium
  86
  87 Most changes should only require testing via the trybots,
  88 with the following added:
  89
  90 `Cq-Include-Trybots: luci.chromium.try:android_optional_gpu_tests_rel;luci.chromium.try:mac_optional_gpu_tests_rel;luci.chromium.try:linux_chromium_cfi_rel_ng;luci.chrome.try:win-chrome`
  91
  92 ### Testing Changes to Googletest in Googletest
  93
  94 External: Upload a PR with your proposed changes to GitHub.
  95 This will trigger automated testing.
  96
  97 Googlers: See the [Googletest Developer’s Guide](http://go/gunitdev).
  98
  99 ### Testing Changes to Googletest in Chromium
 100
 101 In most cases, testing locally with changes to
 102 [third\_party/googletest/src/](https://source.chromium.org/chromium/chromium/src/+/master:third_party/googletest/src/)
 103 should be enough. But how can you make sure the changes to Googletest actually
 104 work in Chromium? Sometimes it’s not possible to test these changes locally
 105 (different compiler flags, error that only affects a specific OS, etc).
 106 Insert the pwnall repo:
 107
 108 * Development: https://github.com/pwnall/googletest
 109 * Chromium mirror: https://chromium.googlesource.com/external/github.com/pwnall/googletest/
 110
 111 The pwnall repo allows you to make speculative changes to Googletest and run
 112 them against the Chromium trybots. The flow is as follows:
 113
 114 * Create a local remote to the pwnall repo (alternatively, clone it elsewhere):
 115 ```
 116 cd third_party/googletest/src
 117 git remote
 118 git remote add up https://github.com/google/googletest.git
 119 git remote add pwnall git@github.com:pwnall/googletest.git
 120 ```
 121 * Sync the pwnall repo:
 122 ```
 123 git checkout master
 124 git pull up master
 125 git push pwnall master
 126 ```
 127 * Make changes on a new branch
 128 * `git push pwnall branch-name`
 129 * Update the `googletest revision` in the
 130   [DEPS file](https://source.chromium.org/chromium/chromium/src/+/master:DEPS)
 131   with the commit hash and `/external/github.com/google/googletest.git` to
 132   `/external/github.com/pwnall/googletest.git`
 133 * Upload the CL to run the change against the Chromium trybots
 134
 135 ### Common Problems
 136
 137 * Differences in C++ version and clang compiler flags between Chromium and Googletest
 138   * Chromium is on C++14, though its dependencies,
 139     which may use Googletest, may be further behind
 140   * Look for NACL in build errors. You may need to update your GN args with
 141     `enable_nacl=true` to reproduce these errors locally
 142 * [A Googletest interface is changed](https://github.com/google/googletest/pull/2718/)
 143   * Rolling past the commit will fail, since Chromium still uses the old interface
 144   * Roll past the affecting commit and update uses in Chromium [in one CL](https://crrev.com/c/2709263)
 145 * [A Googletest header is removed](https://github.com/google/googletest/commit/df6b75949b1efab7606ba60c0f0a0125ac95c5af)
 146   * Rolling past the commit will fail, since Chromium still expects the header to exist
 147   * Roll past the affecting commit and updates uses in Chromium [in one CL](https://crrev.com/c/2713029)
 148 * [A new Googletest feature](https://github.com/google/googletest/commit/ec94d9f24c92a5090fda5567156d6dde99cdbf31)
 149   requires [updating tests in Chromium](https://crbug.com/1163396#c8)
 150
 151 ### Other Resources
 152
 153 * [AutoRoller](https://autoroll.skia.org/r/googletest-chromium-autoroll) and
 154   accompanying [configuration file](https://skia.googlesource.com/skia-autoroll-internal-config.git/+/main/skia-public/googletest-chromium.cfg)
 155 * [Bug tracking substantial roll](https://crbug.com/1163396)