+
+
+ {% if site.google_analytics %}
+
+ {% endif %}
+
+
diff --git a/docs/_sass/main.scss b/docs/_sass/main.scss
new file mode 100644
index 00000000..91e633bb
--- /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 49f7f541..17ba194d 100644
--- a/docs/advanced.md
+++ b/docs/advanced.md
@@ -26,6 +26,7 @@ SUCCEED();
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 @@ switch(expression) {
}
```
+{: .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 @@ b is 4
c is 10
```
+{: .callout .note}
> NOTE:
>
> 1. If you see a compiler error "no matching function to call" when using
@@ -508,6 +511,7 @@ any assertion inside of it.
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 @@ call `abort` and crash the entire test executable, or put the fatal assertion in
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 @@ to be an expression.
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 @@ necessary.
### 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 @@ handlers registered with `pthread_atfork(3)`.
## 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 @@ will output XML like this:
...
```
+{: .callout .note}
> NOTE:
>
> * `RecordProperty()` is a static member of the `Test` class. Therefore it
@@ -1215,6 +1224,7 @@ TEST_F(FooTest, Test2) {
}
```
+{: .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 @@ and `testing::WithParamInterface`. `T` can be any copyable type. If it's a
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 @@ INSTANTIATE_TEST_SUITE_P(InstantiationName,
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 @@ the test parameters. The function should accept one argument of type
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 @@ well, use one of the following macros instead:
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 @@ class DISABLED_BarTest : public testing::Test { ... };
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 @@ could generate this report:
}
```
+{: .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 00000000..bb30f418
--- /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 79ca4004..da443e33 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 @@ can much more easily decide which one to use the next time.
## 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 c82d9cc0..723cb7e1 100644
--- a/docs/gmock_cheat_sheet.md
+++ b/docs/gmock_cheat_sheet.md
@@ -45,6 +45,7 @@ NaggyMock naggy_foo; // The type is a subclass of MockFoo.
StrictMock 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 @@ A **matcher** matches a *single* argument. You can use it inside `ON_CALL()` or
| `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 @@ value, and `foo` by reference.
| :------------ | :----------------------------------------------------- |
| `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 432d3084..8ba5c989 100644
--- a/docs/gmock_cook_book.md
+++ b/docs/gmock_cook_book.md
@@ -4,6 +4,7 @@ You can find recipes for using gMock here. If you haven't yet, please read
[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 @@ generated method:
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, GetPair, ()); // Won't compile!
@@ -53,7 +55,8 @@ class MockFoo {
Solution 1 - wrap with parentheses:
-```cpp {.good}
+{: .good}
+```cpp
class MockFoo {
public:
MOCK_METHOD((std::pair), GetPair, ());
@@ -66,7 +69,8 @@ invalid C++. `MOCK_METHOD` removes the parentheses.
Solution 2 - define an alias:
-```cpp {.good}
+{: .good}
+```cpp
class MockFoo {
public:
using BoolAndInt = std::pair;
@@ -140,6 +144,7 @@ class MockFoo : public Foo {
};
```
+{: .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 @@ TEST(...) {
}
```
+{: .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 @@ using ::testing::Matcher;
### 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 @@ using ::testing::_;
// 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 @@ additional action to notify the `Notification` object. Now we can just call
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 @@ TEST(MyServerTest, ProcessesRequest) {
} // 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 @@ after typing `M-m`), or `M-up`/`M-down` to move back and forth between errors.
### 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 @@ match succeeds in case of a success (unless it's obvious) - this is useful when
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 @@ Expected: is divisible by 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 @@ PolymorphicMatcher NotNull() {
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 6dca904e..4f7daf55 100644
--- a/docs/gmock_for_dummies.md
+++ b/docs/gmock_for_dummies.md
@@ -334,6 +334,7 @@ says that the `turtle` object's `GetX()` method will be called five times, it
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 @@ error, as the last matching expectation (#2) has been saturated. If, however,
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 @@ body. So, if you have two expectations on the same method, you want to put the
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 00000000..9f18e3e8
--- /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 0e24f3ec..44a1cb55 100644
--- a/docs/primer.md
+++ b/docs/primer.md
@@ -44,6 +44,7 @@ minutes to learn the basics and get started. So let's go!
## 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 @@ When invoked, the `RUN_ALL_TESTS()` macro:
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 @@ agree with you completely, and that's why Google Test provides a basic
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