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