Googletest export
Add files for GitHub Pages
PiperOrigin-RevId: 358289110
diff --git a/docs/_config.yml b/docs/_config.yml
new file mode 100644
index 0000000..d12867e
--- /dev/null
+++ b/docs/_config.yml
@@ -0,0 +1 @@
+title: GoogleTest
diff --git a/docs/_data/navigation.yml b/docs/_data/navigation.yml
new file mode 100644
index 0000000..671ed90
--- /dev/null
+++ b/docs/_data/navigation.yml
@@ -0,0 +1,25 @@
+nav:
+- section: "Guides"
+ items:
+ - title: "GoogleTest Primer"
+ url: "/primer.html"
+ - title: "Advanced Topics"
+ url: "/advanced.html"
+ - title: "Mocking for Dummies"
+ url: "/gmock_for_dummies.html"
+ - title: "Mocking Cookbook"
+ url: "/gmock_cook_book.html"
+ - title: "Mocking Cheat Sheet"
+ url: "/gmock_cheat_sheet.html"
+- section: "References"
+ items:
+ - title: "Testing FAQ"
+ url: "/faq.html"
+ - title: "Mocking FAQ"
+ url: "/gmock_faq.html"
+ - title: "Code Samples"
+ url: "/samples.html"
+ - title: "Using pkg-config"
+ url: "/pkgconfig.html"
+ - title: "Community Documentation"
+ url: "/community_created_documentation.html"
diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
new file mode 100644
index 0000000..731042f
--- /dev/null
+++ b/docs/_layouts/default.html
@@ -0,0 +1,53 @@
+<!DOCTYPE html>
+<html lang="{{ site.lang | default: "en-US" }}">
+ <head>
+ <meta charset="UTF-8">
+ <meta http-equiv="X-UA-Compatible" content="IE=edge">
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+
+{% seo %}
+ <link rel="stylesheet" href="{{ "/assets/css/style.css?v=" | append: site.github.build_revision | relative_url }}">
+ </head>
+ <body>
+ <div class="sidebar">
+ <div class="header">
+ <h1><a href="{{ "/" | relative_url }}">{{ site.title | default: "Documentation" }}</a></h1>
+ </div>
+ <input type="checkbox" id="nav-toggle" class="nav-toggle">
+ <label for="nav-toggle" class="expander">
+ <span class="arrow"></span>
+ </label>
+ <nav>
+ {% for item in site.data.navigation.nav %}
+ <h2>{{ item.section }}</h2>
+ <ul>
+ {% for subitem in item.items %}
+ <a href="{{subitem.url | relative_url }}">
+ <li class="{% if subitem.url == page.url %}active{% endif %}">
+ {{ subitem.title }}
+ </li>
+ </a>
+ {% endfor %}
+ </ul>
+ {% endfor %}
+ </nav>
+ </div>
+ <div class="main markdown-body">
+ <div class="main-inner">
+ {{ content }}
+ </div>
+ </div>
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/anchor-js/4.1.0/anchor.min.js" integrity="sha256-lZaRhKri35AyJSypXXs4o6OPFTbTmUoltBbDCbdzegg=" crossorigin="anonymous"></script>
+ <script>anchors.add('.main h2, .main h3, .main h4, .main h5, .main h6');</script>
+ {% if site.google_analytics %}
+ <script>
+ (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+ m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+ })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
+ ga('create', '{{ site.google_analytics }}', 'auto');
+ ga('send', 'pageview');
+ </script>
+ {% endif %}
+ </body>
+</html>
diff --git a/docs/_sass/main.scss b/docs/_sass/main.scss
new file mode 100644
index 0000000..91e633b
--- /dev/null
+++ b/docs/_sass/main.scss
@@ -0,0 +1,193 @@
+// Styles for GoogleTest docs website on GitHub Pages.
+// Color variables are defined in
+// https://github.com/pages-themes/primer/tree/master/_sass/primer-support/lib/variables
+
+$sidebar-width: 260px;
+
+body {
+ display: flex;
+ margin: 0;
+}
+
+.sidebar {
+ background: $black;
+ color: $text-white;
+ flex-shrink: 0;
+ height: 100vh;
+ overflow: auto;
+ position: sticky;
+ top: 0;
+ width: $sidebar-width;
+}
+
+.sidebar h1 {
+ font-size: 1.5em;
+}
+
+.sidebar h2 {
+ color: $gray-light;
+ font-size: 0.8em;
+ font-weight: normal;
+ margin-bottom: 0.8em;
+ padding-left: 2.5em;
+ text-transform: uppercase;
+}
+
+.sidebar .header {
+ background: $black;
+ padding: 2em;
+ position: sticky;
+ top: 0;
+ width: 100%;
+}
+
+.sidebar .header a {
+ color: $text-white;
+ text-decoration: none;
+}
+
+.sidebar .nav-toggle {
+ display: none;
+}
+
+.sidebar .expander {
+ cursor: pointer;
+ display: none;
+ height: 3em;
+ position: absolute;
+ right: 1em;
+ top: 1.5em;
+ width: 3em;
+}
+
+.sidebar .expander .arrow {
+ border: solid white;
+ border-width: 0 3px 3px 0;
+ display: block;
+ height: 0.7em;
+ margin: 1em auto;
+ transform: rotate(45deg);
+ transition: transform 0.5s;
+ width: 0.7em;
+}
+
+.sidebar nav {
+ width: 100%;
+}
+
+.sidebar nav ul {
+ list-style-type: none;
+ margin-bottom: 1em;
+ padding: 0;
+
+ &:last-child {
+ margin-bottom: 2em;
+ }
+
+ a {
+ text-decoration: none;
+ }
+
+ li {
+ color: $text-white;
+ padding-left: 2em;
+ text-decoration: none;
+ }
+
+ li.active {
+ background: $border-gray-darker;
+ font-weight: bold;
+ }
+
+ li:hover {
+ background: $border-gray-darker;
+ }
+}
+
+.main {
+ width: calc(100% - #{$sidebar-width});
+}
+
+.main .main-inner {
+ margin: 2em;
+}
+
+.main table th {
+ text-align: left;
+}
+
+.main .callout {
+ border-left: 0.25em solid white;
+ padding: 1em;
+
+ a {
+ text-decoration: underline;
+ }
+
+ &.important {
+ background-color: $bg-yellow-light;
+ border-color: $bg-yellow;
+ color: $black;
+ }
+
+ &.note {
+ background-color: $bg-blue-light;
+ border-color: $text-blue;
+ color: $text-blue;
+ }
+
+ &.tip {
+ background-color: $green-000;
+ border-color: $green-700;
+ color: $green-700;
+ }
+
+ &.warning {
+ background-color: $red-000;
+ border-color: $text-red;
+ color: $text-red;
+ }
+}
+
+.main .good pre {
+ background-color: $bg-green-light;
+}
+
+.main .bad pre {
+ background-color: $red-000;
+}
+
+@media all and (max-width: 768px) {
+ body {
+ flex-direction: column;
+ }
+
+ .sidebar {
+ height: auto;
+ position: relative;
+ width: 100%;
+ }
+
+ .sidebar .expander {
+ display: block;
+ }
+
+ .sidebar nav {
+ height: 0;
+ overflow: hidden;
+ }
+
+ .sidebar .nav-toggle:checked {
+ & ~ nav {
+ height: auto;
+ }
+
+ & + .expander .arrow {
+ transform: rotate(-135deg);
+ }
+ }
+
+ .main {
+ width: 100%;
+ }
+}
diff --git a/docs/advanced.md b/docs/advanced.md
index 49f7f54..17ba194 100644
--- a/docs/advanced.md
+++ b/docs/advanced.md
@@ -26,6 +26,7 @@
Generates a success. This does **NOT** make the overall test succeed. A test is
considered successful only if none of its assertions fail during its execution.
+{: .callout .note}
NOTE: `SUCCEED()` is purely documentary and currently doesn't generate any
user-visible output. However, we may add `SUCCEED()` messages to googletest's
output in the future.
@@ -52,6 +53,7 @@
}
```
+{: .callout .note}
NOTE: you can only use `FAIL()` in functions that return `void`. See the
[Assertion Placement section](#assertion-placement) for more information.
@@ -143,6 +145,7 @@
c is 10
```
+{: .callout .note}
> NOTE:
>
> 1. If you see a compiler error "no matching function to call" when using
@@ -508,6 +511,7 @@
If changing the function's type is not an option, you should just use assertions
that generate non-fatal failures, such as `ADD_FAILURE*` and `EXPECT_*`.
+{: .callout .note}
NOTE: Constructors and destructors are not considered void-returning functions,
according to the C++ language specification, and so you may not use fatal
assertions in them; you'll get a compilation error if you try. Instead, either
@@ -515,6 +519,7 @@
a `SetUp`/`TearDown` function; see
[constructor/destructor vs. `SetUp`/`TearDown`](faq.md#CtorVsSetUp)
+{: .callout .warning}
WARNING: A fatal assertion in a helper function (private void-returning method)
called from a constructor or destructor does not terminate the current test, as
your intuition might suggest: it merely returns from the constructor or
@@ -645,6 +650,7 @@
As usual, the `ASSERT` variants abort the current test function, while the
`EXPECT` variants do not.
+{: .callout .note}
> NOTE: We use the word "crash" here to mean that the process terminates with a
> *non-zero* exit status code. There are two possibilities: either the process
> has called `exit()` or `_exit()` with a non-zero value, or it may be killed by
@@ -720,6 +726,7 @@
### Death Test Naming
+{: .callout .important}
IMPORTANT: We strongly recommend you to follow the convention of naming your
**test suite** (not test) `*DeathTest` when it contains a death test, as
demonstrated in the above example. The
@@ -901,6 +908,7 @@
## Using Assertions in Sub-routines
+{: .callout .note}
Note: If you want to put a series of test assertions in a subroutine to check
for a complex condition, consider using
[a custom GMock matcher](gmock_cook_book.md#NewMatchers)
@@ -1128,6 +1136,7 @@
...
```
+{: .callout .note}
> NOTE:
>
> * `RecordProperty()` is a static member of the `Test` class. Therefore it
@@ -1215,6 +1224,7 @@
}
```
+{: .callout .note}
NOTE: Though the above code declares `SetUpTestSuite()` protected, it may
sometimes be necessary to declare it public, such as when using it with
`TEST_P`.
@@ -1302,6 +1312,7 @@
raw pointer, you are responsible for managing the lifespan of the pointed
values.
+{: .callout .note}
NOTE: If your test fixture defines `SetUpTestSuite()` or `TearDownTestSuite()`
they must be declared **public** rather than **protected** in order to use
`TEST_P`.
@@ -1368,6 +1379,7 @@
testing::Values("meeny", "miny", "moe"));
```
+{: .callout .note}
NOTE: The code above must be placed at global or namespace scope, not at
function scope.
@@ -1456,6 +1468,7 @@
returns the value of `testing::PrintToString(GetParam())`. It does not work for
`std::string` or C strings.
+{: .callout .note}
NOTE: test names must be non-empty, unique, and may only contain ASCII
alphanumeric characters. In particular, they
[should not contain underscores](faq.md#why-should-test-suite-names-and-test-names-not-contain-underscore)
@@ -1794,6 +1807,7 @@
EXPECT_NONFATAL_FAILURE_ON_ALL_THREADS(statement, substring);
```
+{: .callout .note}
NOTE: Assertions from multiple threads are currently not supported on Windows.
For technical reasons, there are some caveats:
@@ -2141,10 +2155,12 @@
TEST_F(DISABLED_BarTest, DoesXyz) { ... }
```
+{: .callout .note}
NOTE: This feature should only be used for temporary pain-relief. You still have
to fix the disabled tests at a later date. As a reminder, googletest will print
a banner warning you if a test program contains any disabled tests.
+{: .callout .tip}
TIP: You can easily count the number of disabled tests you have using
`grep`. This number can be used as a metric for
improving your test quality.
@@ -2542,6 +2558,7 @@
}
```
+{: .callout .important}
IMPORTANT: The exact format of the JSON document is subject to change.
### Controlling How Failures Are Reported
diff --git a/docs/assets/css/style.scss b/docs/assets/css/style.scss
new file mode 100644
index 0000000..bb30f41
--- /dev/null
+++ b/docs/assets/css/style.scss
@@ -0,0 +1,5 @@
+---
+---
+
+@import "jekyll-theme-primer";
+@import "main";
diff --git a/docs/faq.md b/docs/faq.md
index 79ca400..da443e3 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -2,6 +2,7 @@
## Why should test suite names and test names not contain underscore?
+{: .callout .note}
Note: Googletest reserves underscore (`_`) for special purpose keywords, such as
[the `DISABLED_` prefix](advanced.md#temporarily-disabling-tests), in addition
to the following rationale.
@@ -129,6 +130,7 @@
## I got some run-time errors about invalid proto descriptors when using `ProtocolMessageEquals`. Help!
+{: .callout .note}
**Note:** `ProtocolMessageEquals` and `ProtocolMessageEquiv` are *deprecated*
now. Please use `EqualsProto`, etc instead.
diff --git a/docs/gmock_cheat_sheet.md b/docs/gmock_cheat_sheet.md
index c82d9cc..723cb7e 100644
--- a/docs/gmock_cheat_sheet.md
+++ b/docs/gmock_cheat_sheet.md
@@ -45,6 +45,7 @@
StrictMock<MockFoo> strict_foo; // The type is a subclass of MockFoo.
```
+{: .callout .note}
**Note:** A mock object is currently naggy by default. We may make it nice by
default in the future.
@@ -231,6 +232,7 @@
| `EXPECT_THAT(actual_value, matcher)` | Asserts that `actual_value` matches `matcher`. |
| `ASSERT_THAT(actual_value, matcher)` | The same as `EXPECT_THAT(actual_value, matcher)`, except that it generates a **fatal** failure. |
+{: .callout .note}
**Note:** Although equality matching via `EXPECT_THAT(actual_value,
expected_value)` is supported, prefer to make the comparison explicit via
`EXPECT_THAT(actual_value, Eq(expected_value))` or `EXPECT_EQ(actual_value,
@@ -576,6 +578,7 @@
| :------------ | :----------------------------------------------------- |
| `DoDefault()` | Do the default action (specified by `ON_CALL()` or the built-in one). |
+{: .callout .note}
**Note:** due to technical reasons, `DoDefault()` cannot be used inside a
composite action - trying to do so will result in a run-time error.
diff --git a/docs/gmock_cook_book.md b/docs/gmock_cook_book.md
index 432d308..8ba5c98 100644
--- a/docs/gmock_cook_book.md
+++ b/docs/gmock_cook_book.md
@@ -4,6 +4,7 @@
[the dummy guide](gmock_for_dummies.md) first to make sure you understand the
basics.
+{: .callout .note}
**Note:** gMock lives in the `testing` name space. For readability, it is
recommended to write `using ::testing::Foo;` once in your file before using the
name `Foo` defined by gMock. We omit such `using` statements in this section for
@@ -43,7 +44,8 @@
Unprotected commas, i.e. commas which are not surrounded by parentheses, prevent
`MOCK_METHOD` from parsing its arguments correctly:
-```cpp {.bad}
+{: .bad}
+```cpp
class MockFoo {
public:
MOCK_METHOD(std::pair<bool, int>, GetPair, ()); // Won't compile!
@@ -53,7 +55,8 @@
Solution 1 - wrap with parentheses:
-```cpp {.good}
+{: .good}
+```cpp
class MockFoo {
public:
MOCK_METHOD((std::pair<bool, int>), GetPair, ());
@@ -66,7 +69,8 @@
Solution 2 - define an alias:
-```cpp {.good}
+{: .good}
+```cpp
class MockFoo {
public:
using BoolAndInt = std::pair<bool, int>;
@@ -140,6 +144,7 @@
};
```
+{: .callout .note}
**Note:** if you don't mock all versions of the overloaded method, the compiler
will give you a warning about some methods in the base class being hidden. To
fix that, use `using` to bring them in scope:
@@ -450,6 +455,7 @@
}
```
+{: .callout .note}
NOTE: `NiceMock` and `StrictMock` only affects *uninteresting* calls (calls of
*methods* with no expectations); they do not affect *unexpected* calls (calls of
methods with expectations, but they don't match). See
@@ -1502,6 +1508,7 @@
### Matchers must have no side-effects {#PureMatchers}
+{: .callout .warning}
WARNING: gMock does not guarantee when or how many times a matcher will be
invoked. Therefore, all matchers must be *purely functional*: they cannot have
any side effects, and the match result must not depend on anything other than
@@ -2377,6 +2384,7 @@
// second argument DoThis() receives.
```
+{: .callout .note}
NOTE: The section below is legacy documentation from before C++ had lambdas:
Arghh, you need to refer to a mock function argument but C++ has no lambda
@@ -2729,6 +2737,7 @@
asynchronous call to finish. After that, our test suite is complete and we can
safely exit.
+{: .callout .note}
Note: this example has a downside: namely, if the expectation is not satisfied,
our test will run forever. It will eventually time-out and fail, but it will
take longer and be slightly harder to debug. To alleviate this problem, you can
@@ -3008,6 +3017,7 @@
} // server is destroyed when it goes out of scope here.
```
+{: .callout .tip}
**Tip:** The `Mock::VerifyAndClearExpectations()` function returns a `bool` to
indicate whether the verification was successful (`true` for yes), so you can
wrap that function call inside a `ASSERT_TRUE()` if there is no point going
@@ -3324,6 +3334,7 @@
### Writing New Matchers Quickly {#NewMatchers}
+{: .callout .warning}
WARNING: gMock does not guarantee when or how many times a matcher will be
invoked. Therefore, all matchers must be functionally pure. See
[this section](#PureMatchers) for more details.
@@ -3427,6 +3438,7 @@
the matcher is used inside `Not()`. There is no need to print the argument value
itself, as gMock already prints it for you.
+{: .callout .note}
NOTE: The type of the value being matched (`arg_type`) is determined by the
context in which you use the matcher and is supplied to you by the compiler, so
you don't need to worry about declaring it (nor can you). This allows the
@@ -3664,6 +3676,7 @@
Actual: 23 (the remainder is 2)
```
+{: .callout .tip}
Tip: for convenience, `MatchAndExplain()` can take a `MatchResultListener*`
instead of `std::ostream*`.
@@ -3788,6 +3801,7 @@
EXPECT_CALL(foo, Bar(NotNull())); // The argument must be a non-NULL pointer.
```
+{: .callout .note}
**Note:** Your polymorphic matcher class does **not** need to inherit from
`MatcherInterface` or any other class, and its methods do **not** need to be
virtual.
diff --git a/docs/gmock_for_dummies.md b/docs/gmock_for_dummies.md
index 6dca904..4f7daf5 100644
--- a/docs/gmock_for_dummies.md
+++ b/docs/gmock_for_dummies.md
@@ -334,6 +334,7 @@
will return 100 the first time, 150 the second time, and then 200 every time.
Some people like to call this style of syntax a Domain-Specific Language (DSL).
+{: .callout .note}
**Note:** Why do we use a macro to do this? Well it serves two purposes: first
it makes expectations easily identifiable (either by `grep` or by a human
reader), and second it allows gMock to include the source file location of a
@@ -543,6 +544,7 @@
the third `Forward(10)` call is replaced by `Forward(20)`, then it would be OK,
as now #1 will be the matching expectation.
+{: .callout .note}
**Note:** Why does gMock search for a match in the *reverse* order of the
expectations? The reason is that this allows a user to set up the default
expectations in a mock object's constructor or the test fixture's set-up phase
@@ -551,6 +553,7 @@
one with more specific matchers **after** the other, or the more specific rule
would be shadowed by the more general one that comes after it.
+{: .callout .tip}
**Tip:** It is very common to start with a catch-all expectation for a method
and `Times(AnyNumber())` (omitting arguments, or with `_` for all arguments, if
overloaded). This makes any calls to the method expected. This is not necessary
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..9f18e3e
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,21 @@
+# GoogleTest User's Guide
+
+## Welcome to GoogleTest!
+
+GoogleTest is Google's C++ testing and mocking framework. This user's guide has
+the following contents:
+
+* [GoogleTest Primer](primer) - Teaches you how to write simple tests using
+ GoogleTest. Read this first if you are new to GoogleTest.
+* [GoogleTest Advanced](advanced) - Read this when you've finished the Primer
+ and want to utilize GoogleTest to its full potential.
+* [GoogleTest Samples](samples) - Describes some GoogleTest samples.
+* [GoogleTest FAQ](faq) - Have a question? Want some tips? Check here first.
+* [Mocking for Dummies](gmock_for_dummies) - Teaches you how to create mock
+ objects and use them in tests.
+* [Mocking Cookbook](gmock_cook_book) - Includes tips and approaches to common
+ mocking use cases.
+* [Mocking Cheat Sheet](gmock_cheat_sheet) - A handy reference for matchers,
+ actions, invariants, and more.
+* [Mocking FAQ](gmock_faq) - Contains answers to some mocking-specific
+ questions.
diff --git a/docs/primer.md b/docs/primer.md
index 0e24f3e..44a1cb5 100644
--- a/docs/primer.md
+++ b/docs/primer.md
@@ -44,6 +44,7 @@
## Beware of the nomenclature
+{: .callout .note}
_Note:_ There might be some confusion arising from different definitions of the
terms _Test_, _Test Case_ and _Test Suite_, so beware of misunderstanding these.
@@ -460,6 +461,7 @@
If a fatal failure happens the subsequent steps will be skipped.
+{: .callout .important}
> IMPORTANT: You must **not** ignore the return value of `RUN_ALL_TESTS()`, or
> you will get a compiler error. The rationale for this design is that the
> automated testing service determines whether a test has passed based on its
@@ -562,6 +564,7 @@
implementation of main(). If it fits your needs, then just link your test with
the `gtest_main` library and you are good to go.
+{: .callout .note}
NOTE: `ParseGUnitFlags()` is deprecated in favor of `InitGoogleTest()`.
## Known Limitations
