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