Skip to content

GitLab

Commit d9c309fd authored by Abseil Team's avatar Abseil Team Committed by Derek Mauro
Browse files

Googletest export 

Add files for GitHub Pages

PiperOrigin-RevId: 358289110
parent daa0df7b
Show whitespace changes
Inline Side-by-side
Showing with 343 additions and 3 deletions
docs/_config.yml 0 → 100644
View file @ d9c309fd
title: GoogleTest
docs/_data/navigation.yml 0 → 100644
View file @ d9c309fd
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"
docs/_layouts/default.html 0 → 100644
View file @ d9c309fd
<!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>
docs/_sass/main.scss 0 → 100644
View file @ d9c309fd
// 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%;
}
}
docs/advanced.md
View file @ d9c309fd
......@@ -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>`. `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
......
docs/assets/css/style.scss 0 → 100644
View file @ d9c309fd
---
---
@import "jekyll-theme-primer";
@import "main";
docs/faq.md
View file @ d9c309fd
......@@ -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.
......
docs/gmock_cheat_sheet.md
View file @ d9c309fd
......@@ -45,6 +45,7 @@ NaggyMock<MockFoo> naggy_foo; // The type is a subclass of MockFoo.
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 @@ 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.
......
docs/gmock_cook_book.md
View file @ d9c309fd
......@@ -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<bool, int>, 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<bool, int>), 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<bool, int>;
......@@ -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<NotNullMatcher> 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.
......
docs/gmock_for_dummies.md
View file @ d9c309fd
......@@ -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
......
docs/index.md 0 → 100644
View file @ d9c309fd
# 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.
docs/primer.md
View file @ d9c309fd
......@@ -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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment