1Name: Google Test: Google's C++ Testing Framework 2Short Name: googletest 3URL: https://github.com/google/googletest.git 4Version: unknown 5License: BSD 6License File: src/LICENSE 7Shipped: no 8Security critical: no 9 10Google Test is imported as-is, to facilitate version bumping. However, the 11file/directory layout of Google Test is not yet considered stable. Therefore, 12until Google Test's layout stabilizes, Chromium code MUST NOT depend on it 13directly. 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 19This 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 26Googletest is an open source C++ testing framework developed by Google and used 27by Chromium. See the [User Guide](https://google.github.io/googletest/). 28 29### Where is Googletest 30 31Googletest is developed in google3 and uses 32[copybara](https://github.com/google/copybara) to sync with the public GitHub 33repository. 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 451. 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``` 52roll-dep --roll-to=commitish src/third_party/googletest/src/ 53gclient sync 54``` 55 * Check out the commit directly 56``` 57cd third_party/googletest/src 58git remote add up https://github.com/google/googletest.git 59git checkout commitish 60``` 61 622. 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 693. 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 87Most changes should only require testing via the trybots, 88with 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 94External: Upload a PR with your proposed changes to GitHub. 95This will trigger automated testing. 96 97Googlers: See the [Googletest Developer’s Guide](http://go/gunitdev). 98 99### Testing Changes to Googletest in Chromium 100 101In most cases, testing locally with changes to 102[third\_party/googletest/src/](https://source.chromium.org/chromium/chromium/src/+/master:third_party/googletest/src/) 103should be enough. But how can you make sure the changes to Googletest actually 104work in Chromium? Sometimes it’s not possible to test these changes locally 105(different compiler flags, error that only affects a specific OS, etc). 106Insert the pwnall repo: 107 108* Development: https://github.com/pwnall/googletest 109* Chromium mirror: https://chromium.googlesource.com/external/github.com/pwnall/googletest/ 110 111The pwnall repo allows you to make speculative changes to Googletest and run 112them against the Chromium trybots. The flow is as follows: 113 114* Create a local remote to the pwnall repo (alternatively, clone it elsewhere): 115``` 116cd third_party/googletest/src 117git remote 118git remote add up https://github.com/google/googletest.git 119git remote add pwnall [email protected]:pwnall/googletest.git 120``` 121* Sync the pwnall repo: 122``` 123git checkout master 124git pull up master 125git 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) 156