primer.md 23.4 KB
Newer Older
Gennadiy Civil's avatar
Gennadiy Civil committed
1
2
3
4
5
6
# Googletest Primer

## Introduction: Why googletest?

*googletest* helps you write better C++ tests.

Gennadiy Civil's avatar
 
Gennadiy Civil committed
7
googletest is a testing framework developed by the Testing Technology team with
Abseil Team's avatar
Abseil Team committed
8
9
10
Google's specific requirements and constraints in mind. Whether you work on
Linux, Windows, or a Mac, if you write C++ code, googletest can help you. And it
supports *any* kind of tests, not just unit tests.
Gennadiy Civil's avatar
Gennadiy Civil committed
11
12
13
14
15
16
17

So what makes a good test, and how does googletest fit in? We believe:

1.  Tests should be *independent* and *repeatable*. It's a pain to debug a test
    that succeeds or fails as a result of other tests. googletest isolates the
    tests by running each of them on a different object. When a test fails,
    googletest allows you to run it in isolation for quick debugging.
18
2.  Tests should be well *organized* and reflect the structure of the tested
Gennadiy Civil's avatar
 
Gennadiy Civil committed
19
    code. googletest groups related tests into test suites that can share data
Gennadiy Civil's avatar
Gennadiy Civil committed
20
21
22
    and subroutines. This common pattern is easy to recognize and makes tests
    easy to maintain. Such consistency is especially helpful when people switch
    projects and start to work on a new code base.
23
3.  Tests should be *portable* and *reusable*. Google has a lot of code that is
Abseil Team's avatar
Abseil Team committed
24
    platform-neutral; its tests should also be platform-neutral. googletest
Gennadiy Civil's avatar
 
Gennadiy Civil committed
25
26
    works on different OSes, with different compilers, with or without
    exceptions, so googletest tests can work with a variety of configurations.
27
4.  When tests fail, they should provide as much *information* about the problem
Gennadiy Civil's avatar
Gennadiy Civil committed
28
29
30
31
32
    as possible. googletest doesn't stop at the first test failure. Instead, it
    only stops the current test and continues with the next. You can also set up
    tests that report non-fatal failures after which the current test continues.
    Thus, you can detect and fix multiple bugs in a single run-edit-compile
    cycle.
33
5.  The testing framework should liberate test writers from housekeeping chores
Gennadiy Civil's avatar
Gennadiy Civil committed
34
35
36
    and let them focus on the test *content*. googletest automatically keeps
    track of all tests defined, and doesn't require the user to enumerate them
    in order to run them.
37
6.  Tests should be *fast*. With googletest, you can reuse shared resources
Gennadiy Civil's avatar
Gennadiy Civil committed
38
39
40
41
42
43
    across tests and pay for the set-up/tear-down only once, without making
    tests depend on each other.

Since googletest is based on the popular xUnit architecture, you'll feel right
at home if you've used JUnit or PyUnit before. If not, it will take you about 10
minutes to learn the basics and get started. So let's go!
44

Gennadiy Civil's avatar
Gennadiy Civil committed
45
## Beware of the nomenclature
46

Abseil Team's avatar
Abseil Team committed
47
48
_Note:_ There might be some confusion arising from different definitions of the
terms _Test_, _Test Case_ and _Test Suite_, so beware of misunderstanding these.
49

Gennadiy Civil's avatar
Gennadiy Civil committed
50
Historically, googletest started to use the term _Test Case_ for grouping
Abseil Team's avatar
Abseil Team committed
51
52
53
54
related tests, whereas current publications, including International Software
Testing Qualifications Board ([ISTQB](http://www.istqb.org/)) materials and
various textbooks on software quality, use the term
_[Test Suite][istqb test suite]_ for this.
55

Abseil Team's avatar
Abseil Team committed
56
57
The related term _Test_, as it is used in googletest, corresponds to the term
_[Test Case][istqb test case]_ of ISTQB and others.
58

59
60
61
The term _Test_ is commonly of broad enough sense, including ISTQB's definition
of _Test Case_, so it's not much of a problem here. But the term _Test Case_ as
was used in Google Test is of contradictory sense and thus confusing.
62

Abseil Team's avatar
Abseil Team committed
63
64
65
googletest recently started replacing the term _Test Case_ with _Test Suite_.
The preferred API is *TestSuite*. The older TestCase API is being slowly
deprecated and refactored away.
66

67
So please be aware of the different definitions of the terms:
68

69

70
71
72
Meaning                                                                              | googletest Term         | [ISTQB](http://www.istqb.org/) Term
:----------------------------------------------------------------------------------- | :---------------------- | :----------------------------------
Exercise a particular program path with specific input values and verify the results | [TEST()](#simple-tests) | [Test Case][istqb test case]
Abseil Team's avatar
Abseil Team committed
73
74
75
76


[istqb test case]: http://glossary.istqb.org/en/search/test%20case
[istqb test suite]: http://glossary.istqb.org/en/search/test%20suite
Gennadiy Civil's avatar
Gennadiy Civil committed
77
78
79
80
81
82
83
84
85
86
87

## Basic Concepts

When using googletest, you start by writing *assertions*, which are statements
that check whether a condition is true. An assertion's result can be *success*,
*nonfatal failure*, or *fatal failure*. If a fatal failure occurs, it aborts the
current function; otherwise the program continues normally.

*Tests* use assertions to verify the tested code's behavior. If a test crashes
or has a failed assertion, then it *fails*; otherwise it *succeeds*.

Gennadiy Civil's avatar
 
Gennadiy Civil committed
88
89
90
A *test suite* contains one or many tests. You should group your tests into test
suites that reflect the structure of the tested code. When multiple tests in a
test suite need to share common objects and subroutines, you can put them into a
Gennadiy Civil's avatar
Gennadiy Civil committed
91
*test fixture* class.
92

Gennadiy Civil's avatar
 
Gennadiy Civil committed
93
A *test program* can contain multiple test suites.
94
95

We'll now explain how to write a test program, starting at the individual
Gennadiy Civil's avatar
 
Gennadiy Civil committed
96
assertion level and building up to tests and test suites.
97

Gennadiy Civil's avatar
Gennadiy Civil committed
98
## Assertions
99

Gennadiy Civil's avatar
Gennadiy Civil committed
100
101
102
103
104
googletest assertions are macros that resemble function calls. You test a class
or function by making assertions about its behavior. When an assertion fails,
googletest prints the assertion's source file and line number location, along
with a failure message. You may also supply a custom failure message which will
be appended to googletest's message.
105

Gennadiy Civil's avatar
Gennadiy Civil committed
106
107
108
109
110
111
112
The assertions come in pairs that test the same thing but have different effects
on the current function. `ASSERT_*` versions generate fatal failures when they
fail, and **abort the current function**. `EXPECT_*` versions generate nonfatal
failures, which don't abort the current function. Usually `EXPECT_*` are
preferred, as they allow more than one failure to be reported in a test.
However, you should use `ASSERT_*` if it doesn't make sense to continue when the
assertion in question fails.
113
114
115

Since a failed `ASSERT_*` returns from the current function immediately,
possibly skipping clean-up code that comes after it, it may cause a space leak.
Gennadiy Civil's avatar
Gennadiy Civil committed
116
117
Depending on the nature of the leak, it may or may not be worth fixing - so keep
this in mind if you get a heap checker error in addition to assertion errors.
118
119

To provide a custom failure message, simply stream it into the macro using the
Abseil Team's avatar
Abseil Team committed
120
`<<` operator or a sequence of such operators. An example:
Gennadiy Civil's avatar
Gennadiy Civil committed
121
122

```c++
123
124
125
126
127
128
129
130
131
132
133
134
ASSERT_EQ(x.size(), y.size()) << "Vectors x and y are of unequal length";

for (int i = 0; i < x.size(); ++i) {
  EXPECT_EQ(x[i], y[i]) << "Vectors x and y differ at index " << i;
}
```

Anything that can be streamed to an `ostream` can be streamed to an assertion
macro--in particular, C strings and `string` objects. If a wide string
(`wchar_t*`, `TCHAR*` in `UNICODE` mode on Windows, or `std::wstring`) is
streamed to an assertion, it will be translated to UTF-8 when printed.

Gennadiy Civil's avatar
Gennadiy Civil committed
135
### Basic Assertions
136
137

These assertions do basic true/false condition testing.
138

Gennadiy Civil's avatar
Gennadiy Civil committed
139
140
141
142
Fatal assertion            | Nonfatal assertion         | Verifies
-------------------------- | -------------------------- | --------------------
`ASSERT_TRUE(condition);`  | `EXPECT_TRUE(condition);`  | `condition` is true
`ASSERT_FALSE(condition);` | `EXPECT_FALSE(condition);` | `condition` is false
143

Gennadiy Civil's avatar
Gennadiy Civil committed
144
145
146
147
Remember, when they fail, `ASSERT_*` yields a fatal failure and returns from the
current function, while `EXPECT_*` yields a nonfatal failure, allowing the
function to continue running. In either case, an assertion failure means its
containing test fails.
148

Gennadiy Civil's avatar
Gennadiy Civil committed
149
**Availability**: Linux, Windows, Mac.
150

Gennadiy Civil's avatar
Gennadiy Civil committed
151
### Binary Comparison
152
153
154

This section describes assertions that compare two values.

Gennadiy Civil's avatar
Gennadiy Civil committed
155
156
157
158
159
160
161
162
163
164
165
Fatal assertion          | Nonfatal assertion       | Verifies
------------------------ | ------------------------ | --------------
`ASSERT_EQ(val1, val2);` | `EXPECT_EQ(val1, val2);` | `val1 == val2`
`ASSERT_NE(val1, val2);` | `EXPECT_NE(val1, val2);` | `val1 != val2`
`ASSERT_LT(val1, val2);` | `EXPECT_LT(val1, val2);` | `val1 < val2`
`ASSERT_LE(val1, val2);` | `EXPECT_LE(val1, val2);` | `val1 <= val2`
`ASSERT_GT(val1, val2);` | `EXPECT_GT(val1, val2);` | `val1 > val2`
`ASSERT_GE(val1, val2);` | `EXPECT_GE(val1, val2);` | `val1 >= val2`

Value arguments must be comparable by the assertion's comparison operator or
you'll get a compiler error. We used to require the arguments to support the
Abseil Team's avatar
Abseil Team committed
166
`<<` operator for streaming to an `ostream`, but this is no longer necessary. If
Gennadiy Civil's avatar
Gennadiy Civil committed
167
168
`<<` is supported, it will be called to print the arguments when the assertion
fails; otherwise googletest will attempt to print them in the best way it can.
Abseil Team's avatar
Abseil Team committed
169
For more details and how to customize the printing of the arguments, see the
aribibek's avatar
aribibek committed
170
[documentation](./advanced.md#teaching-googletest-how-to-print-your-values).
171
172

These assertions can work with a user-defined type, but only if you define the
Abseil Team's avatar
Abseil Team committed
173
174
175
corresponding comparison operator (e.g., `==` or `<`). Since this is discouraged
by the Google
[C++ Style Guide](https://google.github.io/styleguide/cppguide.html#Operator_Overloading),
Gennadiy Civil's avatar
Gennadiy Civil committed
176
177
178
179
180
181
you may need to use `ASSERT_TRUE()` or `EXPECT_TRUE()` to assert the equality of
two objects of a user-defined type.

However, when possible, `ASSERT_EQ(actual, expected)` is preferred to
`ASSERT_TRUE(actual == expected)`, since it tells you `actual` and `expected`'s
values on failure.
182
183
184

Arguments are always evaluated exactly once. Therefore, it's OK for the
arguments to have side effects. However, as with any ordinary C/C++ function,
Abseil Team's avatar
Abseil Team committed
185
186
the arguments' evaluation order is undefined (i.e., the compiler is free to
choose any order), and your code should not depend on any particular argument
187
188
189
190
191
evaluation order.

`ASSERT_EQ()` does pointer equality on pointers. If used on two C strings, it
tests if they are in the same memory location, not if they have the same value.
Therefore, if you want to compare C strings (e.g. `const char*`) by value, use
Gennadiy Civil's avatar
Gennadiy Civil committed
192
`ASSERT_STREQ()`, which will be described later on. In particular, to assert
193
that a C string is `NULL`, use `ASSERT_STREQ(c_string, NULL)`. Consider using
Gennadiy Civil's avatar
Gennadiy Civil committed
194
195
196
197
198
`ASSERT_EQ(c_string, nullptr)` if c++11 is supported. To compare two `string`
objects, you should use `ASSERT_EQ`.

When doing pointer comparisons use `*_EQ(ptr, nullptr)` and `*_NE(ptr, nullptr)`
instead of `*_EQ(ptr, NULL)` and `*_NE(ptr, NULL)`. This is because `nullptr` is
Abseil Team's avatar
Abseil Team committed
199
typed, while `NULL` is not. See the [FAQ](faq.md) for more details.
Gennadiy Civil's avatar
Gennadiy Civil committed
200
201
202

If you're working with floating point numbers, you may want to use the floating
point variations of some of these macros in order to avoid problems caused by
Stian Valle's avatar
Stian Valle committed
203
rounding. See [Advanced googletest Topics](advanced.md) for details.
204
205
206
207

Macros in this section work with both narrow and wide string objects (`string`
and `wstring`).

Gennadiy Civil's avatar
Gennadiy Civil committed
208
**Availability**: Linux, Windows, Mac.
209

Gennadiy Civil's avatar
Gennadiy Civil committed
210
211
212
**Historical note**: Before February 2016 `*_EQ` had a convention of calling it
as `ASSERT_EQ(expected, actual)`, so lots of existing code uses this order. Now
`*_EQ` treats both parameters in the same way.
213

Gennadiy Civil's avatar
Gennadiy Civil committed
214
### String Comparison
215
216
217
218

The assertions in this group compare two **C strings**. If you want to compare
two `string` objects, use `EXPECT_EQ`, `EXPECT_NE`, and etc instead.

219

220
221
222
223
224
225
| Fatal assertion                | Nonfatal assertion             | Verifies                                                 |
| --------------------------     | ------------------------------ | -------------------------------------------------------- |
| `ASSERT_STREQ(str1,str2);`     | `EXPECT_STREQ(str1,str2);`     | the two C strings have the same content   		     |
| `ASSERT_STRNE(str1,str2);`     | `EXPECT_STRNE(str1,str2);`     | the two C strings have different contents 		     |
| `ASSERT_STRCASEEQ(str1,str2);` | `EXPECT_STRCASEEQ(str1,str2);` | the two C strings have the same content, ignoring case   |
| `ASSERT_STRCASENE(str1,str2);` | `EXPECT_STRCASENE(str1,str2);` | the two C strings have different contents, ignoring case |
226
227


Gennadiy Civil's avatar
Gennadiy Civil committed
228
229
Note that "CASE" in an assertion name means that case is ignored. A `NULL`
pointer and an empty string are considered *different*.
230

Gennadiy Civil's avatar
Gennadiy Civil committed
231
232
`*STREQ*` and `*STRNE*` also accept wide C strings (`wchar_t*`). If a comparison
of two wide strings fails, their values will be printed as UTF-8 narrow strings.
233

Gennadiy Civil's avatar
Gennadiy Civil committed
234
**Availability**: Linux, Windows, Mac.
235

Gennadiy Civil's avatar
Gennadiy Civil committed
236
**See also**: For more string comparison tricks (substring, prefix, suffix, and
Abseil Team's avatar
Abseil Team committed
237
238
regular expression matching, for example), see [this](advanced.md) in the
Advanced googletest Guide.
239

Gennadiy Civil's avatar
Gennadiy Civil committed
240
## Simple Tests
241
242
243

To create a test:

Abseil Team's avatar
Abseil Team committed
244
1.  Use the `TEST()` macro to define and name a test function. These are
Gennadiy Civil's avatar
Gennadiy Civil committed
245
    ordinary C++ functions that don't return a value.
246
2.  In this function, along with any valid C++ statements you want to include,
Gennadiy Civil's avatar
Gennadiy Civil committed
247
    use the various googletest assertions to check values.
248
3.  The test's result is determined by the assertions; if any assertion in the
Gennadiy Civil's avatar
Gennadiy Civil committed
249
250
251
252
    test fails (either fatally or non-fatally), or if the test crashes, the
    entire test fails. Otherwise, it succeeds.

```c++
253
TEST(TestSuiteName, TestName) {
Gennadiy Civil's avatar
Gennadiy Civil committed
254
  ... test body ...
255
256
257
}
```

Gennadiy Civil's avatar
Gennadiy Civil committed
258
`TEST()` arguments go from general to specific. The *first* argument is the name
259
of the test suite, and the *second* argument is the test's name within the test
260
suite. Both names must be valid C++ identifiers, and they should not contain
Abseil Team's avatar
Abseil Team committed
261
any underscores (`_`). A test's *full name* consists of its containing test suite and
262
its individual name. Tests from different test suites can have the same
Gennadiy Civil's avatar
Gennadiy Civil committed
263
individual name.
264
265

For example, let's take a simple integer function:
Gennadiy Civil's avatar
Gennadiy Civil committed
266
267
268

```c++
int Factorial(int n);  // Returns the factorial of n
269
270
```

271
A test suite for this function might look like:
Gennadiy Civil's avatar
Gennadiy Civil committed
272
273

```c++
274
275
// Tests factorial of 0.
TEST(FactorialTest, HandlesZeroInput) {
Gennadiy Civil's avatar
Gennadiy Civil committed
276
  EXPECT_EQ(Factorial(0), 1);
277
278
279
280
}

// Tests factorial of positive numbers.
TEST(FactorialTest, HandlesPositiveInput) {
Gennadiy Civil's avatar
Gennadiy Civil committed
281
282
283
284
  EXPECT_EQ(Factorial(1), 1);
  EXPECT_EQ(Factorial(2), 2);
  EXPECT_EQ(Factorial(3), 6);
  EXPECT_EQ(Factorial(8), 40320);
285
286
287
}
```

Abseil Team's avatar
Abseil Team committed
288
googletest groups the test results by test suites, so logically related tests
289
should be in the same test suite; in other words, the first argument to their
290
`TEST()` should be the same. In the above example, we have two tests,
291
292
`HandlesZeroInput` and `HandlesPositiveInput`, that belong to the same test
suite `FactorialTest`.
293

294
When naming your test suites and tests, you should follow the same convention as
295
296
for
[naming functions and classes](https://google.github.io/styleguide/cppguide.html#Function_Names).
297

Gennadiy Civil's avatar
Gennadiy Civil committed
298
**Availability**: Linux, Windows, Mac.
299

Abseil Team's avatar
Abseil Team committed
300
## Test Fixtures: Using the Same Data Configuration for Multiple Tests {#same-data-multiple-tests}
Gennadiy Civil's avatar
Gennadiy Civil committed
301
302

If you find yourself writing two or more tests that operate on similar data, you
Abseil Team's avatar
Abseil Team committed
303
can use a *test fixture*. This allows you to reuse the same configuration of
304
305
objects for several different tests.

Gennadiy Civil's avatar
Gennadiy Civil committed
306
307
To create a fixture:

Abseil Team's avatar
Abseil Team committed
308
1.  Derive a class from `::testing::Test` . Start its body with `protected:`, as
Gennadiy Civil's avatar
Gennadiy Civil committed
309
    we'll want to access fixture members from sub-classes.
310
311
2.  Inside the class, declare any objects you plan to use.
3.  If necessary, write a default constructor or `SetUp()` function to prepare
Gennadiy Civil's avatar
Gennadiy Civil committed
312
313
    the objects for each test. A common mistake is to spell `SetUp()` as
    **`Setup()`** with a small `u` - Use `override` in C++11 to make sure you
Abseil Team's avatar
Abseil Team committed
314
    spelled it correctly.
315
4.  If necessary, write a destructor or `TearDown()` function to release any
Gennadiy Civil's avatar
Gennadiy Civil committed
316
317
    resources you allocated in `SetUp()` . To learn when you should use the
    constructor/destructor and when you should use `SetUp()/TearDown()`, read
Abseil Team's avatar
Abseil Team committed
318
    the [FAQ](faq.md#CtorVsSetUp).
319
5.  If needed, define subroutines for your tests to share.
320
321
322

When using a fixture, use `TEST_F()` instead of `TEST()` as it allows you to
access objects and subroutines in the test fixture:
Gennadiy Civil's avatar
Gennadiy Civil committed
323
324

```c++
325
TEST_F(TestFixtureName, TestName) {
Gennadiy Civil's avatar
Gennadiy Civil committed
326
  ... test body ...
327
328
329
}
```

330
331
332
Like `TEST()`, the first argument is the test suite name, but for `TEST_F()`
this must be the name of the test fixture class. You've probably guessed: `_F`
is for fixture.
333
334
335
336
337
338
339
340
341

Unfortunately, the C++ macro system does not allow us to create a single macro
that can handle both types of tests. Using the wrong macro causes a compiler
error.

Also, you must first define a test fixture class before using it in a
`TEST_F()`, or you'll get the compiler error "`virtual outside class
declaration`".

Abseil Team's avatar
Abseil Team committed
342
343
344
For each test defined with `TEST_F()`, googletest will create a *fresh* test
fixture at runtime, immediately initialize it via `SetUp()`, run the test,
clean up by calling `TearDown()`, and then delete the test fixture. Note that
345
different tests in the same test suite have different test fixture objects, and
Gennadiy Civil's avatar
Gennadiy Civil committed
346
347
348
googletest always deletes a test fixture before it creates the next one.
googletest does **not** reuse the same test fixture for multiple tests. Any
changes one test makes to the fixture do not affect other tests.
349

Gennadiy Civil's avatar
Gennadiy Civil committed
350
351
352
353
354
As an example, let's write tests for a FIFO queue class named `Queue`, which has
the following interface:

```c++
template <typename E>  // E is the element type.
355
356
357
358
class Queue {
 public:
  Queue();
  void Enqueue(const E& element);
Gennadiy Civil's avatar
Gennadiy Civil committed
359
  E* Dequeue();  // Returns NULL if the queue is empty.
360
361
362
363
364
365
366
  size_t size() const;
  ...
};
```

First, define a fixture class. By convention, you should give it the name
`FooTest` where `Foo` is the class being tested.
Gennadiy Civil's avatar
Gennadiy Civil committed
367
368

```c++
369
370
class QueueTest : public ::testing::Test {
 protected:
Gennadiy Civil's avatar
Gennadiy Civil committed
371
372
373
374
  void SetUp() override {
     q1_.Enqueue(1);
     q2_.Enqueue(2);
     q2_.Enqueue(3);
375
376
  }

Gennadiy Civil's avatar
Gennadiy Civil committed
377
  // void TearDown() override {}
378
379
380
381
382
383
384
385
386
387
388

  Queue<int> q0_;
  Queue<int> q1_;
  Queue<int> q2_;
};
```

In this case, `TearDown()` is not needed since we don't have to clean up after
each test, other than what's already done by the destructor.

Now we'll write tests using `TEST_F()` and this fixture.
Gennadiy Civil's avatar
Gennadiy Civil committed
389
390

```c++
391
TEST_F(QueueTest, IsEmptyInitially) {
Gennadiy Civil's avatar
Gennadiy Civil committed
392
  EXPECT_EQ(q0_.size(), 0);
393
394
395
396
}

TEST_F(QueueTest, DequeueWorks) {
  int* n = q0_.Dequeue();
Gennadiy Civil's avatar
Gennadiy Civil committed
397
  EXPECT_EQ(n, nullptr);
398
399

  n = q1_.Dequeue();
Gennadiy Civil's avatar
Gennadiy Civil committed
400
401
402
  ASSERT_NE(n, nullptr);
  EXPECT_EQ(*n, 1);
  EXPECT_EQ(q1_.size(), 0);
403
404
405
  delete n;

  n = q2_.Dequeue();
Gennadiy Civil's avatar
Gennadiy Civil committed
406
407
408
  ASSERT_NE(n, nullptr);
  EXPECT_EQ(*n, 2);
  EXPECT_EQ(q2_.size(), 1);
409
410
411
412
413
  delete n;
}
```

The above uses both `ASSERT_*` and `EXPECT_*` assertions. The rule of thumb is
Gennadiy Civil's avatar
Gennadiy Civil committed
414
415
416
to use `EXPECT_*` when you want the test to continue to reveal more errors after
the assertion failure, and use `ASSERT_*` when continuing after failure doesn't
make sense. For example, the second assertion in the `Dequeue` test is
417
`ASSERT_NE(nullptr, n)`, as we need to dereference the pointer `n` later, which
Gennadiy Civil's avatar
Gennadiy Civil committed
418
would lead to a segfault when `n` is `NULL`.
419
420
421

When these tests run, the following happens:

Abseil Team's avatar
Abseil Team committed
422
423
424
1.  googletest constructs a `QueueTest` object (let's call it `t1`).
2.  `t1.SetUp()` initializes `t1`.
3.  The first test (`IsEmptyInitially`) runs on `t1`.
425
426
427
4.  `t1.TearDown()` cleans up after the test finishes.
5.  `t1` is destructed.
6.  The above steps are repeated on another `QueueTest` object, this time
Gennadiy Civil's avatar
Gennadiy Civil committed
428
    running the `DequeueWorks` test.
429

Gennadiy Civil's avatar
Gennadiy Civil committed
430
**Availability**: Linux, Windows, Mac.
431

Gennadiy Civil's avatar
Gennadiy Civil committed
432
## Invoking the Tests
433

Gennadiy Civil's avatar
Gennadiy Civil committed
434
435
436
`TEST()` and `TEST_F()` implicitly register their tests with googletest. So,
unlike with many other C++ testing frameworks, you don't have to re-list all
your defined tests in order to run them.
437

Abseil Team's avatar
Abseil Team committed
438
After defining your tests, you can run them with `RUN_ALL_TESTS()`, which
Gennadiy Civil's avatar
Gennadiy Civil committed
439
returns `0` if all the tests are successful, or `1` otherwise. Note that
Abseil Team's avatar
Abseil Team committed
440
`RUN_ALL_TESTS()` runs *all tests* in your link unit--they can be from
441
different test suites, or even different source files.
442
443
444

When invoked, the `RUN_ALL_TESTS()` macro:

Abseil Team's avatar
Abseil Team committed
445
*   Saves the state of all googletest flags.
Gennadiy Civil's avatar
Gennadiy Civil committed
446
447
448
449
450
451

*   Creates a test fixture object for the first test.

*   Initializes it via `SetUp()`.

*   Runs the test on the fixture object.
452

Gennadiy Civil's avatar
Gennadiy Civil committed
453
*   Cleans up the fixture via `TearDown()`.
454

Gennadiy Civil's avatar
Gennadiy Civil committed
455
*   Deletes the fixture.
456

Abseil Team's avatar
Abseil Team committed
457
*   Restores the state of all googletest flags.
458

Gennadiy Civil's avatar
Gennadiy Civil committed
459
*   Repeats the above steps for the next test, until all tests have run.
460

Gennadiy Civil's avatar
Gennadiy Civil committed
461
462
463
464
465
466
467
468
469
If a fatal failure happens the subsequent steps will be skipped.

> 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
> exit code, not on its stdout/stderr output; thus your `main()` function must
> return the value of `RUN_ALL_TESTS()`.
>
> Also, you should call `RUN_ALL_TESTS()` only **once**. Calling it more than
Abseil Team's avatar
Abseil Team committed
470
> once conflicts with some advanced googletest features (e.g., thread-safe
471
> [death tests](advanced.md#death-tests)) and thus is not supported.
Gennadiy Civil's avatar
Gennadiy Civil committed
472
473
474
475
476

**Availability**: Linux, Windows, Mac.

## Writing the main() Function

Abseil Team's avatar
Abseil Team committed
477
478
479
480
481
482
483
Most users should _not_ need to write their own `main` function and instead link
with `gtest_main` (as opposed to with `gtest`), which defines a suitable entry
point. See the end of this section for details. The remainder of this section
should only apply when you need to do something custom before the tests run that
cannot be expressed within the framework of fixtures and test suites.

If you write your own `main` function, it should return the value of
Abseil Team's avatar
Abseil Team committed
484
`RUN_ALL_TESTS()`.
485
486

You can start from this boilerplate:
Gennadiy Civil's avatar
Gennadiy Civil committed
487
488

```c++
489
#include "this/package/foo.h"
Abseil Team's avatar
Abseil Team committed
490

491
492
#include "gtest/gtest.h"

Abseil Team's avatar
Abseil Team committed
493
494
namespace my {
namespace project {
495
496
497
498
499
namespace {

// The fixture for testing class Foo.
class FooTest : public ::testing::Test {
 protected:
Abseil Team's avatar
Abseil Team committed
500
501
  // You can remove any or all of the following functions if their bodies would
  // be empty.
502
503

  FooTest() {
Gennadiy Civil's avatar
Gennadiy Civil committed
504
     // You can do set-up work for each test here.
505
506
  }

Gennadiy Civil's avatar
Gennadiy Civil committed
507
508
  ~FooTest() override {
     // You can do clean-up work that doesn't throw exceptions here.
509
510
511
512
513
  }

  // If the constructor and destructor are not enough for setting up
  // and cleaning up each test, you can define the following methods:

Gennadiy Civil's avatar
Gennadiy Civil committed
514
515
516
  void SetUp() override {
     // Code here will be called immediately after the constructor (right
     // before each test).
517
518
  }

Gennadiy Civil's avatar
Gennadiy Civil committed
519
520
521
  void TearDown() override {
     // Code here will be called immediately after each test (right
     // before the destructor).
522
523
  }

Abseil Team's avatar
Abseil Team committed
524
525
  // Class members declared here can be used by all tests in the test suite
  // for Foo.
526
527
528
529
};

// Tests that the Foo::Bar() method does Abc.
TEST_F(FooTest, MethodBarDoesAbc) {
Gennadiy Civil's avatar
Gennadiy Civil committed
530
531
  const std::string input_filepath = "this/package/testdata/myinputfile.dat";
  const std::string output_filepath = "this/package/testdata/myoutputfile.dat";
532
  Foo f;
Gennadiy Civil's avatar
Gennadiy Civil committed
533
  EXPECT_EQ(f.Bar(input_filepath, output_filepath), 0);
534
535
536
537
538
539
540
541
}

// Tests that Foo does Xyz.
TEST_F(FooTest, DoesXyz) {
  // Exercises the Xyz feature of Foo.
}

}  // namespace
Abseil Team's avatar
Abseil Team committed
542
543
}  // namespace project
}  // namespace my
544
545
546
547
548
549
550

int main(int argc, char **argv) {
  ::testing::InitGoogleTest(&argc, argv);
  return RUN_ALL_TESTS();
}
```

Gennadiy Civil's avatar
Gennadiy Civil committed
551
552
553
The `::testing::InitGoogleTest()` function parses the command line for
googletest flags, and removes all recognized flags. This allows the user to
control a test program's behavior via various flags, which we'll cover in
Abseil Team's avatar
Abseil Team committed
554
the [AdvancedGuide](advanced.md). You **must** call this function before calling
Gennadiy Civil's avatar
Gennadiy Civil committed
555
`RUN_ALL_TESTS()`, or the flags won't be properly initialized.
556
557
558
559

On Windows, `InitGoogleTest()` also works with wide strings, so it can be used
in programs compiled in `UNICODE` mode as well.

Abseil Team's avatar
Abseil Team committed
560
But maybe you think that writing all those `main` functions is too much work? We
Abseil Team's avatar
Abseil Team committed
561
agree with you completely, and that's why Google Test provides a basic
Gennadiy Civil's avatar
Gennadiy Civil committed
562
implementation of main(). If it fits your needs, then just link your test with
Abseil Team's avatar
Abseil Team committed
563
the `gtest_main` library and you are good to go.
564

Gennadiy Civil's avatar
Gennadiy Civil committed
565
566
567
NOTE: `ParseGUnitFlags()` is deprecated in favor of `InitGoogleTest()`.

## Known Limitations
568

Gennadiy Civil's avatar
Gennadiy Civil committed
569
570
571
572
573
574
575
*   Google Test is designed to be thread-safe. The implementation is thread-safe
    on systems where the `pthreads` library is available. It is currently
    _unsafe_ to use Google Test assertions from two threads concurrently on
    other systems (e.g. Windows). In most tests this is not an issue as usually
    the assertions are done in the main thread. If you want to help, you can
    volunteer to implement the necessary synchronization primitives in
    `gtest-port.h` for your platform.