155 lines
6.9 KiB
Plaintext
155 lines
6.9 KiB
Plaintext
Name: Google Test: Google's C++ Testing Framework
|
||
Short Name: googletest
|
||
URL: https://github.com/google/googletest.git
|
||
Version: unknown
|
||
License: BSD
|
||
License File: NOT_SHIPPED
|
||
Security critical: no
|
||
|
||
Google Test is imported as-is, to facilitate version bumping. However, the
|
||
file/directory layout of Google Test is not yet considered stable. Therefore,
|
||
until Google Test's layout stabilizes, Chromium code MUST NOT depend on it
|
||
directly. Instead, Chromium code MUST:
|
||
|
||
* #include the headers in testing/gtest and testing/gmock
|
||
* use //testing/gtest(:gtest_main) and //testing/gmock(:gmock_main) in BUILD.gn
|
||
deps
|
||
|
||
This will allow us to adapt to Google Test changes with minimal disruption.
|
||
|
||
|
||
## Resources for Rolling Googletest in Chrome
|
||
|
||
### What is Googletest
|
||
|
||
Googletest is an open source C++ testing framework developed by Google and used
|
||
by Chromium. See the [User Guide](https://google.github.io/googletest/).
|
||
|
||
### Where is Googletest
|
||
|
||
Googletest is developed in google3 and uses
|
||
[copybara](https://github.com/google/copybara) to sync with the public GitHub
|
||
repository.
|
||
|
||
* Development (Googler only): [google3/third\_party/googletest](http://google3/third_party/googletest/)
|
||
* GitHub: https://github.com/google/googletest
|
||
* Chromium mirror: https://chromium.googlesource.com/external/github.com/google/googletest/
|
||
* Locally, [third\_party/googletest/src/](https://source.chromium.org/chromium/chromium/src/+/master:third_party/googletest/src/)
|
||
is a copy of Googletest which is updated via `gclient sync` according to the
|
||
`googletest revision` commit hash in the
|
||
[DEPS file](https://source.chromium.org/chromium/chromium/src/+/master:DEPS;l=244?q=DEPS%20googletest)
|
||
|
||
### Unblocking Googletest Rolls
|
||
|
||
1. Roll Googletest to include the breaking change
|
||
* Find the hash (on GitHub) of the offending commit
|
||
* If the change came from google3, the CL number can be found in the
|
||
`PiperOrigin-RevId` footer of Copybara commits
|
||
* On a fresh checkout, pull in the relevant change. Either:
|
||
* Sync using the DEPS file
|
||
```
|
||
roll-dep --roll-to=commitish src/third_party/googletest/src/
|
||
gclient sync
|
||
```
|
||
* Check out the commit directly
|
||
```
|
||
cd third_party/googletest/src
|
||
git remote add up https://github.com/google/googletest.git
|
||
git checkout commitish
|
||
```
|
||
|
||
2. Observe errors
|
||
* Ideally, this can be done by building locally.
|
||
If the build is successful, this means the change does not affect your OS or
|
||
your compiler flags differ from the trybots
|
||
* Upload a CL with the added trybots from
|
||
[Testing Changes to Chromium in Chromium](#testing-changes-to-chromium-in-chromium)
|
||
|
||
3. Make changes
|
||
* To Chromium: create a CL including both the roll and other changes
|
||
* To Googletest:
|
||
* Make changes to [third\_party/googletest/src/](https://source.chromium.org/chromium/chromium/src/+/master:third_party/googletest/src/)
|
||
and try building locally. If the fix is successful and you’re confident
|
||
this change will work across all the trybots, create a PR on GitHub or a
|
||
CL to google3 (Googler only) of the changes you made locally to
|
||
[third\_party/googletest/src/](https://source.chromium.org/chromium/chromium/src/+/master:third_party/googletest/src/).
|
||
See [Testing Changes to Googletest in Googletest](#testing-changes-to-googletest-in-googletest)
|
||
* What if I need to make a change to Googletest, but I’m not confident it
|
||
will work with Chromium? Maybe it has to do with a tricky compiler error
|
||
that only affects a specific OS. See
|
||
[Testing Changes to Googletest in Chromium](#testing-changes-to-googletest-in-chromium)
|
||
* Once your Googletest change lands, create a roll which includes both the
|
||
offending commit and your change
|
||
|
||
### Testing Changes to Chromium in Chromium
|
||
|
||
Most changes should only require testing via the trybots,
|
||
with the following added:
|
||
|
||
`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`
|
||
|
||
### Testing Changes to Googletest in Googletest
|
||
|
||
External: Upload a PR with your proposed changes to GitHub.
|
||
This will trigger automated testing.
|
||
|
||
Googlers: See the [Googletest Developer’s Guide](http://go/gunitdev).
|
||
|
||
### Testing Changes to Googletest in Chromium
|
||
|
||
In most cases, testing locally with changes to
|
||
[third\_party/googletest/src/](https://source.chromium.org/chromium/chromium/src/+/master:third_party/googletest/src/)
|
||
should be enough. But how can you make sure the changes to Googletest actually
|
||
work in Chromium? Sometimes it’s not possible to test these changes locally
|
||
(different compiler flags, error that only affects a specific OS, etc).
|
||
Insert the pwnall repo:
|
||
|
||
* Development: https://github.com/pwnall/googletest
|
||
* Chromium mirror: https://chromium.googlesource.com/external/github.com/pwnall/googletest/
|
||
|
||
The pwnall repo allows you to make speculative changes to Googletest and run
|
||
them against the Chromium trybots. The flow is as follows:
|
||
|
||
* Create a local remote to the pwnall repo (alternatively, clone it elsewhere):
|
||
```
|
||
cd third_party/googletest/src
|
||
git remote
|
||
git remote add up https://github.com/google/googletest.git
|
||
git remote add pwnall git@github.com:pwnall/googletest.git
|
||
```
|
||
* Sync the pwnall repo:
|
||
```
|
||
git checkout master
|
||
git pull up master
|
||
git push pwnall master
|
||
```
|
||
* Make changes on a new branch
|
||
* `git push pwnall branch-name`
|
||
* Update the `googletest revision` in the
|
||
[DEPS file](https://source.chromium.org/chromium/chromium/src/+/master:DEPS)
|
||
with the commit hash and `/external/github.com/google/googletest.git` to
|
||
`/external/github.com/pwnall/googletest.git`
|
||
* Upload the CL to run the change against the Chromium trybots
|
||
|
||
### Common Problems
|
||
|
||
* Differences in C++ version and clang compiler flags between Chromium and Googletest
|
||
* Chromium is on C++14, though its dependencies,
|
||
which may use Googletest, may be further behind
|
||
* Look for NACL in build errors. You may need to update your GN args with
|
||
`enable_nacl=true` to reproduce these errors locally
|
||
* [A Googletest interface is changed](https://github.com/google/googletest/pull/2718/)
|
||
* Rolling past the commit will fail, since Chromium still uses the old interface
|
||
* Roll past the affecting commit and update uses in Chromium [in one CL](https://crrev.com/c/2709263)
|
||
* [A Googletest header is removed](https://github.com/google/googletest/commit/df6b75949b1efab7606ba60c0f0a0125ac95c5af)
|
||
* Rolling past the commit will fail, since Chromium still expects the header to exist
|
||
* Roll past the affecting commit and updates uses in Chromium [in one CL](https://crrev.com/c/2713029)
|
||
* [A new Googletest feature](https://github.com/google/googletest/commit/ec94d9f24c92a5090fda5567156d6dde99cdbf31)
|
||
requires [updating tests in Chromium](https://crbug.com/1163396#c8)
|
||
|
||
### Other Resources
|
||
|
||
* [AutoRoller](https://autoroll.skia.org/r/googletest-chromium-autoroll) and
|
||
accompanying [configuration file](https://skia.googlesource.com/skia-autoroll-internal-config.git/+/main/skia-public/googletest-chromium.cfg)
|
||
* [Bug tracking substantial roll](https://crbug.com/1163396)
|