128f6c2f2SEnji Cooper# GoogleTest Primer 228f6c2f2SEnji Cooper 328f6c2f2SEnji Cooper## Introduction: Why GoogleTest? 428f6c2f2SEnji Cooper 528f6c2f2SEnji Cooper*GoogleTest* helps you write better C++ tests. 628f6c2f2SEnji Cooper 728f6c2f2SEnji CooperGoogleTest is a testing framework developed by the Testing Technology team with 828f6c2f2SEnji CooperGoogle's specific requirements and constraints in mind. Whether you work on 928f6c2f2SEnji CooperLinux, Windows, or a Mac, if you write C++ code, GoogleTest can help you. And it 1028f6c2f2SEnji Coopersupports *any* kind of tests, not just unit tests. 1128f6c2f2SEnji Cooper 1228f6c2f2SEnji CooperSo what makes a good test, and how does GoogleTest fit in? We believe: 1328f6c2f2SEnji Cooper 1428f6c2f2SEnji Cooper1. Tests should be *independent* and *repeatable*. It's a pain to debug a test 1528f6c2f2SEnji Cooper that succeeds or fails as a result of other tests. GoogleTest isolates the 1628f6c2f2SEnji Cooper tests by running each of them on a different object. When a test fails, 1728f6c2f2SEnji Cooper GoogleTest allows you to run it in isolation for quick debugging. 1828f6c2f2SEnji Cooper2. Tests should be well *organized* and reflect the structure of the tested 1928f6c2f2SEnji Cooper code. GoogleTest groups related tests into test suites that can share data 2028f6c2f2SEnji Cooper and subroutines. This common pattern is easy to recognize and makes tests 2128f6c2f2SEnji Cooper easy to maintain. Such consistency is especially helpful when people switch 2228f6c2f2SEnji Cooper projects and start to work on a new code base. 2328f6c2f2SEnji Cooper3. Tests should be *portable* and *reusable*. Google has a lot of code that is 2428f6c2f2SEnji Cooper platform-neutral; its tests should also be platform-neutral. GoogleTest 2528f6c2f2SEnji Cooper works on different OSes, with different compilers, with or without 2628f6c2f2SEnji Cooper exceptions, so GoogleTest tests can work with a variety of configurations. 2728f6c2f2SEnji Cooper4. When tests fail, they should provide as much *information* about the problem 2828f6c2f2SEnji Cooper as possible. GoogleTest doesn't stop at the first test failure. Instead, it 2928f6c2f2SEnji Cooper only stops the current test and continues with the next. You can also set up 3028f6c2f2SEnji Cooper tests that report non-fatal failures after which the current test continues. 3128f6c2f2SEnji Cooper Thus, you can detect and fix multiple bugs in a single run-edit-compile 3228f6c2f2SEnji Cooper cycle. 3328f6c2f2SEnji Cooper5. The testing framework should liberate test writers from housekeeping chores 3428f6c2f2SEnji Cooper and let them focus on the test *content*. GoogleTest automatically keeps 3528f6c2f2SEnji Cooper track of all tests defined, and doesn't require the user to enumerate them 3628f6c2f2SEnji Cooper in order to run them. 3728f6c2f2SEnji Cooper6. Tests should be *fast*. With GoogleTest, you can reuse shared resources 3828f6c2f2SEnji Cooper across tests and pay for the set-up/tear-down only once, without making 3928f6c2f2SEnji Cooper tests depend on each other. 4028f6c2f2SEnji Cooper 4128f6c2f2SEnji CooperSince GoogleTest is based on the popular xUnit architecture, you'll feel right 4228f6c2f2SEnji Cooperat home if you've used JUnit or PyUnit before. If not, it will take you about 10 4328f6c2f2SEnji Cooperminutes to learn the basics and get started. So let's go! 4428f6c2f2SEnji Cooper 4528f6c2f2SEnji Cooper## Beware of the Nomenclature 4628f6c2f2SEnji Cooper 4728f6c2f2SEnji Cooper{: .callout .note} 4828f6c2f2SEnji Cooper*Note:* There might be some confusion arising from different definitions of the 4928f6c2f2SEnji Cooperterms *Test*, *Test Case* and *Test Suite*, so beware of misunderstanding these. 5028f6c2f2SEnji Cooper 5128f6c2f2SEnji CooperHistorically, GoogleTest started to use the term *Test Case* for grouping 5228f6c2f2SEnji Cooperrelated tests, whereas current publications, including International Software 5328f6c2f2SEnji CooperTesting Qualifications Board ([ISTQB](http://www.istqb.org/)) materials and 5428f6c2f2SEnji Coopervarious textbooks on software quality, use the term 5528f6c2f2SEnji Cooper*[Test Suite][istqb test suite]* for this. 5628f6c2f2SEnji Cooper 5728f6c2f2SEnji CooperThe related term *Test*, as it is used in GoogleTest, corresponds to the term 5828f6c2f2SEnji Cooper*[Test Case][istqb test case]* of ISTQB and others. 5928f6c2f2SEnji Cooper 6028f6c2f2SEnji CooperThe term *Test* is commonly of broad enough sense, including ISTQB's definition 6128f6c2f2SEnji Cooperof *Test Case*, so it's not much of a problem here. But the term *Test Case* as 6228f6c2f2SEnji Cooperwas used in Google Test is of contradictory sense and thus confusing. 6328f6c2f2SEnji Cooper 6428f6c2f2SEnji CooperGoogleTest recently started replacing the term *Test Case* with *Test Suite*. 6528f6c2f2SEnji CooperThe preferred API is *TestSuite*. The older TestCase API is being slowly 6628f6c2f2SEnji Cooperdeprecated and refactored away. 6728f6c2f2SEnji Cooper 6828f6c2f2SEnji CooperSo please be aware of the different definitions of the terms: 6928f6c2f2SEnji Cooper 7028f6c2f2SEnji Cooper 7128f6c2f2SEnji CooperMeaning | GoogleTest Term | [ISTQB](http://www.istqb.org/) Term 7228f6c2f2SEnji Cooper:----------------------------------------------------------------------------------- | :---------------------- | :---------------------------------- 7328f6c2f2SEnji CooperExercise a particular program path with specific input values and verify the results | [TEST()](#simple-tests) | [Test Case][istqb test case] 7428f6c2f2SEnji Cooper 7528f6c2f2SEnji Cooper 7628f6c2f2SEnji Cooper[istqb test case]: http://glossary.istqb.org/en/search/test%20case 7728f6c2f2SEnji Cooper[istqb test suite]: http://glossary.istqb.org/en/search/test%20suite 7828f6c2f2SEnji Cooper 7928f6c2f2SEnji Cooper## Basic Concepts 8028f6c2f2SEnji Cooper 8128f6c2f2SEnji CooperWhen using GoogleTest, you start by writing *assertions*, which are statements 8228f6c2f2SEnji Cooperthat check whether a condition is true. An assertion's result can be *success*, 8328f6c2f2SEnji Cooper*nonfatal failure*, or *fatal failure*. If a fatal failure occurs, it aborts the 8428f6c2f2SEnji Coopercurrent function; otherwise the program continues normally. 8528f6c2f2SEnji Cooper 8628f6c2f2SEnji Cooper*Tests* use assertions to verify the tested code's behavior. If a test crashes 8728f6c2f2SEnji Cooperor has a failed assertion, then it *fails*; otherwise it *succeeds*. 8828f6c2f2SEnji Cooper 8928f6c2f2SEnji CooperA *test suite* contains one or many tests. You should group your tests into test 9028f6c2f2SEnji Coopersuites that reflect the structure of the tested code. When multiple tests in a 9128f6c2f2SEnji Coopertest suite need to share common objects and subroutines, you can put them into a 9228f6c2f2SEnji Cooper*test fixture* class. 9328f6c2f2SEnji Cooper 9428f6c2f2SEnji CooperA *test program* can contain multiple test suites. 9528f6c2f2SEnji Cooper 9628f6c2f2SEnji CooperWe'll now explain how to write a test program, starting at the individual 9728f6c2f2SEnji Cooperassertion level and building up to tests and test suites. 9828f6c2f2SEnji Cooper 9928f6c2f2SEnji Cooper## Assertions 10028f6c2f2SEnji Cooper 10128f6c2f2SEnji CooperGoogleTest assertions are macros that resemble function calls. You test a class 10228f6c2f2SEnji Cooperor function by making assertions about its behavior. When an assertion fails, 10328f6c2f2SEnji CooperGoogleTest prints the assertion's source file and line number location, along 10428f6c2f2SEnji Cooperwith a failure message. You may also supply a custom failure message which will 10528f6c2f2SEnji Cooperbe appended to GoogleTest's message. 10628f6c2f2SEnji Cooper 10728f6c2f2SEnji CooperThe assertions come in pairs that test the same thing but have different effects 10828f6c2f2SEnji Cooperon the current function. `ASSERT_*` versions generate fatal failures when they 10928f6c2f2SEnji Cooperfail, and **abort the current function**. `EXPECT_*` versions generate nonfatal 11028f6c2f2SEnji Cooperfailures, which don't abort the current function. Usually `EXPECT_*` are 11128f6c2f2SEnji Cooperpreferred, as they allow more than one failure to be reported in a test. 11228f6c2f2SEnji CooperHowever, you should use `ASSERT_*` if it doesn't make sense to continue when the 11328f6c2f2SEnji Cooperassertion in question fails. 11428f6c2f2SEnji Cooper 11528f6c2f2SEnji CooperSince a failed `ASSERT_*` returns from the current function immediately, 11628f6c2f2SEnji Cooperpossibly skipping clean-up code that comes after it, it may cause a space leak. 11728f6c2f2SEnji CooperDepending on the nature of the leak, it may or may not be worth fixing - so keep 11828f6c2f2SEnji Cooperthis in mind if you get a heap checker error in addition to assertion errors. 11928f6c2f2SEnji Cooper 12028f6c2f2SEnji CooperTo provide a custom failure message, simply stream it into the macro using the 12128f6c2f2SEnji Cooper`<<` operator or a sequence of such operators. See the following example, using 12228f6c2f2SEnji Cooperthe [`ASSERT_EQ` and `EXPECT_EQ`](reference/assertions.md#EXPECT_EQ) macros to 12328f6c2f2SEnji Cooperverify value equality: 12428f6c2f2SEnji Cooper 12528f6c2f2SEnji Cooper```c++ 12628f6c2f2SEnji CooperASSERT_EQ(x.size(), y.size()) << "Vectors x and y are of unequal length"; 12728f6c2f2SEnji Cooper 12828f6c2f2SEnji Cooperfor (int i = 0; i < x.size(); ++i) { 12928f6c2f2SEnji Cooper EXPECT_EQ(x[i], y[i]) << "Vectors x and y differ at index " << i; 13028f6c2f2SEnji Cooper} 13128f6c2f2SEnji Cooper``` 13228f6c2f2SEnji Cooper 13328f6c2f2SEnji CooperAnything that can be streamed to an `ostream` can be streamed to an assertion 13428f6c2f2SEnji Coopermacro--in particular, C strings and `string` objects. If a wide string 13528f6c2f2SEnji Cooper(`wchar_t*`, `TCHAR*` in `UNICODE` mode on Windows, or `std::wstring`) is 13628f6c2f2SEnji Cooperstreamed to an assertion, it will be translated to UTF-8 when printed. 13728f6c2f2SEnji Cooper 13828f6c2f2SEnji CooperGoogleTest provides a collection of assertions for verifying the behavior of 13928f6c2f2SEnji Cooperyour code in various ways. You can check Boolean conditions, compare values 14028f6c2f2SEnji Cooperbased on relational operators, verify string values, floating-point values, and 14128f6c2f2SEnji Coopermuch more. There are even assertions that enable you to verify more complex 14228f6c2f2SEnji Cooperstates by providing custom predicates. For the complete list of assertions 14328f6c2f2SEnji Cooperprovided by GoogleTest, see the [Assertions Reference](reference/assertions.md). 14428f6c2f2SEnji Cooper 14528f6c2f2SEnji Cooper## Simple Tests 14628f6c2f2SEnji Cooper 14728f6c2f2SEnji CooperTo create a test: 14828f6c2f2SEnji Cooper 14928f6c2f2SEnji Cooper1. Use the `TEST()` macro to define and name a test function. These are 15028f6c2f2SEnji Cooper ordinary C++ functions that don't return a value. 15128f6c2f2SEnji Cooper2. In this function, along with any valid C++ statements you want to include, 15228f6c2f2SEnji Cooper use the various GoogleTest assertions to check values. 15328f6c2f2SEnji Cooper3. The test's result is determined by the assertions; if any assertion in the 15428f6c2f2SEnji Cooper test fails (either fatally or non-fatally), or if the test crashes, the 15528f6c2f2SEnji Cooper entire test fails. Otherwise, it succeeds. 15628f6c2f2SEnji Cooper 15728f6c2f2SEnji Cooper```c++ 15828f6c2f2SEnji CooperTEST(TestSuiteName, TestName) { 15928f6c2f2SEnji Cooper ... test body ... 16028f6c2f2SEnji Cooper} 16128f6c2f2SEnji Cooper``` 16228f6c2f2SEnji Cooper 16328f6c2f2SEnji Cooper`TEST()` arguments go from general to specific. The *first* argument is the name 16428f6c2f2SEnji Cooperof the test suite, and the *second* argument is the test's name within the test 16528f6c2f2SEnji Coopersuite. Both names must be valid C++ identifiers, and they should not contain any 16628f6c2f2SEnji Cooperunderscores (`_`). A test's *full name* consists of its containing test suite 16728f6c2f2SEnji Cooperand its individual name. Tests from different test suites can have the same 16828f6c2f2SEnji Cooperindividual name. 16928f6c2f2SEnji Cooper 17028f6c2f2SEnji CooperFor example, let's take a simple integer function: 17128f6c2f2SEnji Cooper 17228f6c2f2SEnji Cooper```c++ 17328f6c2f2SEnji Cooperint Factorial(int n); // Returns the factorial of n 17428f6c2f2SEnji Cooper``` 17528f6c2f2SEnji Cooper 17628f6c2f2SEnji CooperA test suite for this function might look like: 17728f6c2f2SEnji Cooper 17828f6c2f2SEnji Cooper```c++ 17928f6c2f2SEnji Cooper// Tests factorial of 0. 18028f6c2f2SEnji CooperTEST(FactorialTest, HandlesZeroInput) { 18128f6c2f2SEnji Cooper EXPECT_EQ(Factorial(0), 1); 18228f6c2f2SEnji Cooper} 18328f6c2f2SEnji Cooper 18428f6c2f2SEnji Cooper// Tests factorial of positive numbers. 18528f6c2f2SEnji CooperTEST(FactorialTest, HandlesPositiveInput) { 18628f6c2f2SEnji Cooper EXPECT_EQ(Factorial(1), 1); 18728f6c2f2SEnji Cooper EXPECT_EQ(Factorial(2), 2); 18828f6c2f2SEnji Cooper EXPECT_EQ(Factorial(3), 6); 18928f6c2f2SEnji Cooper EXPECT_EQ(Factorial(8), 40320); 19028f6c2f2SEnji Cooper} 19128f6c2f2SEnji Cooper``` 19228f6c2f2SEnji Cooper 19328f6c2f2SEnji CooperGoogleTest groups the test results by test suites, so logically related tests 19428f6c2f2SEnji Coopershould be in the same test suite; in other words, the first argument to their 19528f6c2f2SEnji Cooper`TEST()` should be the same. In the above example, we have two tests, 19628f6c2f2SEnji Cooper`HandlesZeroInput` and `HandlesPositiveInput`, that belong to the same test 19728f6c2f2SEnji Coopersuite `FactorialTest`. 19828f6c2f2SEnji Cooper 19928f6c2f2SEnji CooperWhen naming your test suites and tests, you should follow the same convention as 20028f6c2f2SEnji Cooperfor 20128f6c2f2SEnji Cooper[naming functions and classes](https://google.github.io/styleguide/cppguide.html#Function_Names). 20228f6c2f2SEnji Cooper 20328f6c2f2SEnji Cooper**Availability**: Linux, Windows, Mac. 20428f6c2f2SEnji Cooper 20528f6c2f2SEnji Cooper## Test Fixtures: Using the Same Data Configuration for Multiple Tests {#same-data-multiple-tests} 20628f6c2f2SEnji Cooper 20728f6c2f2SEnji CooperIf you find yourself writing two or more tests that operate on similar data, you 20828f6c2f2SEnji Coopercan use a *test fixture*. This allows you to reuse the same configuration of 20928f6c2f2SEnji Cooperobjects for several different tests. 21028f6c2f2SEnji Cooper 21128f6c2f2SEnji CooperTo create a fixture: 21228f6c2f2SEnji Cooper 21328f6c2f2SEnji Cooper1. Derive a class from `::testing::Test` . Start its body with `protected:`, as 21428f6c2f2SEnji Cooper we'll want to access fixture members from sub-classes. 21528f6c2f2SEnji Cooper2. Inside the class, declare any objects you plan to use. 21628f6c2f2SEnji Cooper3. If necessary, write a default constructor or `SetUp()` function to prepare 21728f6c2f2SEnji Cooper the objects for each test. A common mistake is to spell `SetUp()` as 21828f6c2f2SEnji Cooper **`Setup()`** with a small `u` - Use `override` in C++11 to make sure you 21928f6c2f2SEnji Cooper spelled it correctly. 22028f6c2f2SEnji Cooper4. If necessary, write a destructor or `TearDown()` function to release any 22128f6c2f2SEnji Cooper resources you allocated in `SetUp()` . To learn when you should use the 22228f6c2f2SEnji Cooper constructor/destructor and when you should use `SetUp()/TearDown()`, read 22328f6c2f2SEnji Cooper the [FAQ](faq.md#CtorVsSetUp). 22428f6c2f2SEnji Cooper5. If needed, define subroutines for your tests to share. 22528f6c2f2SEnji Cooper 22628f6c2f2SEnji CooperWhen using a fixture, use `TEST_F()` instead of `TEST()` as it allows you to 22728f6c2f2SEnji Cooperaccess objects and subroutines in the test fixture: 22828f6c2f2SEnji Cooper 22928f6c2f2SEnji Cooper```c++ 23028f6c2f2SEnji CooperTEST_F(TestFixtureClassName, TestName) { 23128f6c2f2SEnji Cooper ... test body ... 23228f6c2f2SEnji Cooper} 23328f6c2f2SEnji Cooper``` 23428f6c2f2SEnji Cooper 23528f6c2f2SEnji CooperUnlike `TEST()`, in `TEST_F()` the first argument must be the name of the test 23628f6c2f2SEnji Cooperfixture class. (`_F` stands for "Fixture"). No test suite name is specified for 23728f6c2f2SEnji Cooperthis macro. 23828f6c2f2SEnji Cooper 23928f6c2f2SEnji CooperUnfortunately, the C++ macro system does not allow us to create a single macro 24028f6c2f2SEnji Cooperthat can handle both types of tests. Using the wrong macro causes a compiler 24128f6c2f2SEnji Coopererror. 24228f6c2f2SEnji Cooper 24328f6c2f2SEnji CooperAlso, you must first define a test fixture class before using it in a 24428f6c2f2SEnji Cooper`TEST_F()`, or you'll get the compiler error "`virtual outside class 24528f6c2f2SEnji Cooperdeclaration`". 24628f6c2f2SEnji Cooper 24728f6c2f2SEnji CooperFor each test defined with `TEST_F()`, GoogleTest will create a *fresh* test 24828f6c2f2SEnji Cooperfixture at runtime, immediately initialize it via `SetUp()`, run the test, clean 24928f6c2f2SEnji Cooperup by calling `TearDown()`, and then delete the test fixture. Note that 25028f6c2f2SEnji Cooperdifferent tests in the same test suite have different test fixture objects, and 25128f6c2f2SEnji CooperGoogleTest always deletes a test fixture before it creates the next one. 25228f6c2f2SEnji CooperGoogleTest does **not** reuse the same test fixture for multiple tests. Any 25328f6c2f2SEnji Cooperchanges one test makes to the fixture do not affect other tests. 25428f6c2f2SEnji Cooper 25528f6c2f2SEnji CooperAs an example, let's write tests for a FIFO queue class named `Queue`, which has 25628f6c2f2SEnji Cooperthe following interface: 25728f6c2f2SEnji Cooper 25828f6c2f2SEnji Cooper```c++ 25928f6c2f2SEnji Coopertemplate <typename E> // E is the element type. 26028f6c2f2SEnji Cooperclass Queue { 26128f6c2f2SEnji Cooper public: 26228f6c2f2SEnji Cooper Queue(); 26328f6c2f2SEnji Cooper void Enqueue(const E& element); 26428f6c2f2SEnji Cooper E* Dequeue(); // Returns NULL if the queue is empty. 26528f6c2f2SEnji Cooper size_t size() const; 26628f6c2f2SEnji Cooper ... 26728f6c2f2SEnji Cooper}; 26828f6c2f2SEnji Cooper``` 26928f6c2f2SEnji Cooper 27028f6c2f2SEnji CooperFirst, define a fixture class. By convention, you should give it the name 27128f6c2f2SEnji Cooper`FooTest` where `Foo` is the class being tested. 27228f6c2f2SEnji Cooper 27328f6c2f2SEnji Cooper```c++ 27428f6c2f2SEnji Cooperclass QueueTest : public ::testing::Test { 27528f6c2f2SEnji Cooper protected: 27628f6c2f2SEnji Cooper void SetUp() override { 27728f6c2f2SEnji Cooper // q0_ remains empty 27828f6c2f2SEnji Cooper q1_.Enqueue(1); 27928f6c2f2SEnji Cooper q2_.Enqueue(2); 28028f6c2f2SEnji Cooper q2_.Enqueue(3); 28128f6c2f2SEnji Cooper } 28228f6c2f2SEnji Cooper 28328f6c2f2SEnji Cooper // void TearDown() override {} 28428f6c2f2SEnji Cooper 28528f6c2f2SEnji Cooper Queue<int> q0_; 28628f6c2f2SEnji Cooper Queue<int> q1_; 28728f6c2f2SEnji Cooper Queue<int> q2_; 28828f6c2f2SEnji Cooper}; 28928f6c2f2SEnji Cooper``` 29028f6c2f2SEnji Cooper 29128f6c2f2SEnji CooperIn this case, `TearDown()` is not needed since we don't have to clean up after 29228f6c2f2SEnji Coopereach test, other than what's already done by the destructor. 29328f6c2f2SEnji Cooper 29428f6c2f2SEnji CooperNow we'll write tests using `TEST_F()` and this fixture. 29528f6c2f2SEnji Cooper 29628f6c2f2SEnji Cooper```c++ 29728f6c2f2SEnji CooperTEST_F(QueueTest, IsEmptyInitially) { 29828f6c2f2SEnji Cooper EXPECT_EQ(q0_.size(), 0); 29928f6c2f2SEnji Cooper} 30028f6c2f2SEnji Cooper 30128f6c2f2SEnji CooperTEST_F(QueueTest, DequeueWorks) { 30228f6c2f2SEnji Cooper int* n = q0_.Dequeue(); 30328f6c2f2SEnji Cooper EXPECT_EQ(n, nullptr); 30428f6c2f2SEnji Cooper 30528f6c2f2SEnji Cooper n = q1_.Dequeue(); 30628f6c2f2SEnji Cooper ASSERT_NE(n, nullptr); 30728f6c2f2SEnji Cooper EXPECT_EQ(*n, 1); 30828f6c2f2SEnji Cooper EXPECT_EQ(q1_.size(), 0); 30928f6c2f2SEnji Cooper delete n; 31028f6c2f2SEnji Cooper 31128f6c2f2SEnji Cooper n = q2_.Dequeue(); 31228f6c2f2SEnji Cooper ASSERT_NE(n, nullptr); 31328f6c2f2SEnji Cooper EXPECT_EQ(*n, 2); 31428f6c2f2SEnji Cooper EXPECT_EQ(q2_.size(), 1); 31528f6c2f2SEnji Cooper delete n; 31628f6c2f2SEnji Cooper} 31728f6c2f2SEnji Cooper``` 31828f6c2f2SEnji Cooper 31928f6c2f2SEnji CooperThe above uses both `ASSERT_*` and `EXPECT_*` assertions. The rule of thumb is 32028f6c2f2SEnji Cooperto use `EXPECT_*` when you want the test to continue to reveal more errors after 32128f6c2f2SEnji Cooperthe assertion failure, and use `ASSERT_*` when continuing after failure doesn't 32228f6c2f2SEnji Coopermake sense. For example, the second assertion in the `Dequeue` test is 32328f6c2f2SEnji Cooper`ASSERT_NE(n, nullptr)`, as we need to dereference the pointer `n` later, which 32428f6c2f2SEnji Cooperwould lead to a segfault when `n` is `NULL`. 32528f6c2f2SEnji Cooper 32628f6c2f2SEnji CooperWhen these tests run, the following happens: 32728f6c2f2SEnji Cooper 32828f6c2f2SEnji Cooper1. GoogleTest constructs a `QueueTest` object (let's call it `t1`). 32928f6c2f2SEnji Cooper2. `t1.SetUp()` initializes `t1`. 33028f6c2f2SEnji Cooper3. The first test (`IsEmptyInitially`) runs on `t1`. 33128f6c2f2SEnji Cooper4. `t1.TearDown()` cleans up after the test finishes. 33228f6c2f2SEnji Cooper5. `t1` is destructed. 33328f6c2f2SEnji Cooper6. The above steps are repeated on another `QueueTest` object, this time 33428f6c2f2SEnji Cooper running the `DequeueWorks` test. 33528f6c2f2SEnji Cooper 33628f6c2f2SEnji Cooper**Availability**: Linux, Windows, Mac. 33728f6c2f2SEnji Cooper 33828f6c2f2SEnji Cooper## Invoking the Tests 33928f6c2f2SEnji Cooper 34028f6c2f2SEnji Cooper`TEST()` and `TEST_F()` implicitly register their tests with GoogleTest. So, 34128f6c2f2SEnji Cooperunlike with many other C++ testing frameworks, you don't have to re-list all 34228f6c2f2SEnji Cooperyour defined tests in order to run them. 34328f6c2f2SEnji Cooper 34428f6c2f2SEnji CooperAfter defining your tests, you can run them with `RUN_ALL_TESTS()`, which 34528f6c2f2SEnji Cooperreturns `0` if all the tests are successful, or `1` otherwise. Note that 34628f6c2f2SEnji Cooper`RUN_ALL_TESTS()` runs *all tests* in your link unit--they can be from different 34728f6c2f2SEnji Coopertest suites, or even different source files. 34828f6c2f2SEnji Cooper 34928f6c2f2SEnji CooperWhen invoked, the `RUN_ALL_TESTS()` macro: 35028f6c2f2SEnji Cooper 35128f6c2f2SEnji Cooper* Saves the state of all GoogleTest flags. 35228f6c2f2SEnji Cooper 35328f6c2f2SEnji Cooper* Creates a test fixture object for the first test. 35428f6c2f2SEnji Cooper 35528f6c2f2SEnji Cooper* Initializes it via `SetUp()`. 35628f6c2f2SEnji Cooper 35728f6c2f2SEnji Cooper* Runs the test on the fixture object. 35828f6c2f2SEnji Cooper 35928f6c2f2SEnji Cooper* Cleans up the fixture via `TearDown()`. 36028f6c2f2SEnji Cooper 36128f6c2f2SEnji Cooper* Deletes the fixture. 36228f6c2f2SEnji Cooper 36328f6c2f2SEnji Cooper* Restores the state of all GoogleTest flags. 36428f6c2f2SEnji Cooper 36528f6c2f2SEnji Cooper* Repeats the above steps for the next test, until all tests have run. 36628f6c2f2SEnji Cooper 36728f6c2f2SEnji CooperIf a fatal failure happens the subsequent steps will be skipped. 36828f6c2f2SEnji Cooper 36928f6c2f2SEnji Cooper{: .callout .important} 37028f6c2f2SEnji Cooper> IMPORTANT: You must **not** ignore the return value of `RUN_ALL_TESTS()`, or 37128f6c2f2SEnji Cooper> you will get a compiler error. The rationale for this design is that the 37228f6c2f2SEnji Cooper> automated testing service determines whether a test has passed based on its 37328f6c2f2SEnji Cooper> exit code, not on its stdout/stderr output; thus your `main()` function must 37428f6c2f2SEnji Cooper> return the value of `RUN_ALL_TESTS()`. 37528f6c2f2SEnji Cooper> 37628f6c2f2SEnji Cooper> Also, you should call `RUN_ALL_TESTS()` only **once**. Calling it more than 37728f6c2f2SEnji Cooper> once conflicts with some advanced GoogleTest features (e.g., thread-safe 37828f6c2f2SEnji Cooper> [death tests](advanced.md#death-tests)) and thus is not supported. 37928f6c2f2SEnji Cooper 38028f6c2f2SEnji Cooper**Availability**: Linux, Windows, Mac. 38128f6c2f2SEnji Cooper 38228f6c2f2SEnji Cooper## Writing the main() Function 38328f6c2f2SEnji Cooper 38428f6c2f2SEnji CooperMost users should *not* need to write their own `main` function and instead link 38528f6c2f2SEnji Cooperwith `gtest_main` (as opposed to with `gtest`), which defines a suitable entry 38628f6c2f2SEnji Cooperpoint. See the end of this section for details. The remainder of this section 38728f6c2f2SEnji Coopershould only apply when you need to do something custom before the tests run that 38828f6c2f2SEnji Coopercannot be expressed within the framework of fixtures and test suites. 38928f6c2f2SEnji Cooper 39028f6c2f2SEnji CooperIf you write your own `main` function, it should return the value of 39128f6c2f2SEnji Cooper`RUN_ALL_TESTS()`. 39228f6c2f2SEnji Cooper 39328f6c2f2SEnji CooperYou can start from this boilerplate: 39428f6c2f2SEnji Cooper 39528f6c2f2SEnji Cooper```c++ 39628f6c2f2SEnji Cooper#include "this/package/foo.h" 39728f6c2f2SEnji Cooper 39828f6c2f2SEnji Cooper#include <gtest/gtest.h> 39928f6c2f2SEnji Cooper 40028f6c2f2SEnji Coopernamespace my { 40128f6c2f2SEnji Coopernamespace project { 40228f6c2f2SEnji Coopernamespace { 40328f6c2f2SEnji Cooper 40428f6c2f2SEnji Cooper// The fixture for testing class Foo. 40528f6c2f2SEnji Cooperclass FooTest : public ::testing::Test { 40628f6c2f2SEnji Cooper protected: 40728f6c2f2SEnji Cooper // You can remove any or all of the following functions if their bodies would 40828f6c2f2SEnji Cooper // be empty. 40928f6c2f2SEnji Cooper 41028f6c2f2SEnji Cooper FooTest() { 41128f6c2f2SEnji Cooper // You can do set-up work for each test here. 41228f6c2f2SEnji Cooper } 41328f6c2f2SEnji Cooper 41428f6c2f2SEnji Cooper ~FooTest() override { 41528f6c2f2SEnji Cooper // You can do clean-up work that doesn't throw exceptions here. 41628f6c2f2SEnji Cooper } 41728f6c2f2SEnji Cooper 41828f6c2f2SEnji Cooper // If the constructor and destructor are not enough for setting up 41928f6c2f2SEnji Cooper // and cleaning up each test, you can define the following methods: 42028f6c2f2SEnji Cooper 42128f6c2f2SEnji Cooper void SetUp() override { 42228f6c2f2SEnji Cooper // Code here will be called immediately after the constructor (right 42328f6c2f2SEnji Cooper // before each test). 42428f6c2f2SEnji Cooper } 42528f6c2f2SEnji Cooper 42628f6c2f2SEnji Cooper void TearDown() override { 42728f6c2f2SEnji Cooper // Code here will be called immediately after each test (right 42828f6c2f2SEnji Cooper // before the destructor). 42928f6c2f2SEnji Cooper } 43028f6c2f2SEnji Cooper 43128f6c2f2SEnji Cooper // Class members declared here can be used by all tests in the test suite 43228f6c2f2SEnji Cooper // for Foo. 43328f6c2f2SEnji Cooper}; 43428f6c2f2SEnji Cooper 43528f6c2f2SEnji Cooper// Tests that the Foo::Bar() method does Abc. 43628f6c2f2SEnji CooperTEST_F(FooTest, MethodBarDoesAbc) { 43728f6c2f2SEnji Cooper const std::string input_filepath = "this/package/testdata/myinputfile.dat"; 43828f6c2f2SEnji Cooper const std::string output_filepath = "this/package/testdata/myoutputfile.dat"; 43928f6c2f2SEnji Cooper Foo f; 44028f6c2f2SEnji Cooper EXPECT_EQ(f.Bar(input_filepath, output_filepath), 0); 44128f6c2f2SEnji Cooper} 44228f6c2f2SEnji Cooper 44328f6c2f2SEnji Cooper// Tests that Foo does Xyz. 44428f6c2f2SEnji CooperTEST_F(FooTest, DoesXyz) { 44528f6c2f2SEnji Cooper // Exercises the Xyz feature of Foo. 44628f6c2f2SEnji Cooper} 44728f6c2f2SEnji Cooper 44828f6c2f2SEnji Cooper} // namespace 44928f6c2f2SEnji Cooper} // namespace project 45028f6c2f2SEnji Cooper} // namespace my 45128f6c2f2SEnji Cooper 45228f6c2f2SEnji Cooperint main(int argc, char **argv) { 45328f6c2f2SEnji Cooper ::testing::InitGoogleTest(&argc, argv); 45428f6c2f2SEnji Cooper return RUN_ALL_TESTS(); 45528f6c2f2SEnji Cooper} 45628f6c2f2SEnji Cooper``` 45728f6c2f2SEnji Cooper 45828f6c2f2SEnji CooperThe `::testing::InitGoogleTest()` function parses the command line for 45928f6c2f2SEnji CooperGoogleTest flags, and removes all recognized flags. This allows the user to 46028f6c2f2SEnji Coopercontrol a test program's behavior via various flags, which we'll cover in the 46128f6c2f2SEnji Cooper[AdvancedGuide](advanced.md). You **must** call this function before calling 46228f6c2f2SEnji Cooper`RUN_ALL_TESTS()`, or the flags won't be properly initialized. 46328f6c2f2SEnji Cooper 46428f6c2f2SEnji CooperOn Windows, `InitGoogleTest()` also works with wide strings, so it can be used 46528f6c2f2SEnji Cooperin programs compiled in `UNICODE` mode as well. 46628f6c2f2SEnji Cooper 46728f6c2f2SEnji CooperBut maybe you think that writing all those `main` functions is too much work? We 46828f6c2f2SEnji Cooperagree with you completely, and that's why Google Test provides a basic 46928f6c2f2SEnji Cooperimplementation of main(). If it fits your needs, then just link your test with 47028f6c2f2SEnji Cooperthe `gtest_main` library and you are good to go. 47128f6c2f2SEnji Cooper 47228f6c2f2SEnji Cooper{: .callout .note} 47328f6c2f2SEnji CooperNOTE: `ParseGUnitFlags()` is deprecated in favor of `InitGoogleTest()`. 47428f6c2f2SEnji Cooper 47528f6c2f2SEnji Cooper## Known Limitations 47628f6c2f2SEnji Cooper 47728f6c2f2SEnji Cooper* Google Test is designed to be thread-safe. The implementation is thread-safe 47828f6c2f2SEnji Cooper on systems where the `pthreads` library is available. It is currently 47928f6c2f2SEnji Cooper *unsafe* to use Google Test assertions from two threads concurrently on 48028f6c2f2SEnji Cooper other systems (e.g. Windows). In most tests this is not an issue as usually 48128f6c2f2SEnji Cooper the assertions are done in the main thread. If you want to help, you can 48228f6c2f2SEnji Cooper volunteer to implement the necessary synchronization primitives in 48328f6c2f2SEnji Cooper `gtest-port.h` for your platform. 484