docs/reference/testing.md

   1 # Testing Reference
   2
   3 <!--* toc_depth: 3 *-->
   4
   5 This page lists the facilities provided by GoogleTest for writing test programs.
   6 To use them, include the header `gtest/gtest.h`.
   7
   8 ## Macros
   9
  10 GoogleTest defines the following macros for writing tests.
  11
  12 ### TEST {#TEST}
  13
  14 <pre>
  15 TEST(<em>TestSuiteName</em>, <em>TestName</em>) {
  16   ... <em>statements</em> ...
  17 }
  18 </pre>
  19
  20 Defines an individual test named *`TestName`* in the test suite
  21 *`TestSuiteName`*, consisting of the given statements.
  22
  23 Both arguments *`TestSuiteName`* and *`TestName`* must be valid C++ identifiers
  24 and must not contain underscores (`_`). Tests in different test suites can have
  25 the same individual name.
  26
  27 The statements within the test body can be any code under test.
  28 [Assertions](assertions.md) used within the test body determine the outcome of
  29 the test.
  30
  31 ### TEST_F {#TEST_F}
  32
  33 <pre>
  34 TEST_F(<em>TestFixtureName</em>, <em>TestName</em>) {
  35   ... <em>statements</em> ...
  36 }
  37 </pre>
  38
  39 Defines an individual test named *`TestName`* that uses the test fixture class
  40 *`TestFixtureName`*. The test suite name is *`TestFixtureName`*.
  41
  42 Both arguments *`TestFixtureName`* and *`TestName`* must be valid C++
  43 identifiers and must not contain underscores (`_`). *`TestFixtureName`* must be
  44 the name of a test fixture class—see
  45 [Test Fixtures](../primer.md#same-data-multiple-tests).
  46
  47 The statements within the test body can be any code under test.
  48 [Assertions](assertions.md) used within the test body determine the outcome of
  49 the test.
  50
  51 ### TEST_P {#TEST_P}
  52
  53 <pre>
  54 TEST_P(<em>TestFixtureName</em>, <em>TestName</em>) {
  55   ... <em>statements</em> ...
  56 }
  57 </pre>
  58
  59 Defines an individual value-parameterized test named *`TestName`* that uses the
  60 test fixture class *`TestFixtureName`*. The test suite name is
  61 *`TestFixtureName`*.
  62
  63 Both arguments *`TestFixtureName`* and *`TestName`* must be valid C++
  64 identifiers and must not contain underscores (`_`). *`TestFixtureName`* must be
  65 the name of a value-parameterized test fixture class—see
  66 [Value-Parameterized Tests](../advanced.md#value-parameterized-tests).
  67
  68 The statements within the test body can be any code under test. Within the test
  69 body, the test parameter can be accessed with the `GetParam()` function (see
  70 [`WithParamInterface`](#WithParamInterface)). For example:
  71
  72 ```cpp
  73 TEST_P(MyTestSuite, DoesSomething) {
  74   ...
  75   EXPECT_TRUE(DoSomething(GetParam()));
  76   ...
  77 }
  78 ```
  79
  80 [Assertions](assertions.md) used within the test body determine the outcome of
  81 the test.
  82
  83 See also [`INSTANTIATE_TEST_SUITE_P`](#INSTANTIATE_TEST_SUITE_P).
  84
  85 ### INSTANTIATE_TEST_SUITE_P {#INSTANTIATE_TEST_SUITE_P}
  86
  87 `INSTANTIATE_TEST_SUITE_P(`*`InstantiationName`*`,`*`TestSuiteName`*`,`*`param_generator`*`)`
  88 \
  89 `INSTANTIATE_TEST_SUITE_P(`*`InstantiationName`*`,`*`TestSuiteName`*`,`*`param_generator`*`,`*`name_generator`*`)`
  90
  91 Instantiates the value-parameterized test suite *`TestSuiteName`* (defined with
  92 [`TEST_P`](#TEST_P)).
  93
  94 The argument *`InstantiationName`* is a unique name for the instantiation of the
  95 test suite, to distinguish between multiple instantiations. In test output, the
  96 instantiation name is added as a prefix to the test suite name
  97 *`TestSuiteName`*.
  98
  99 The argument *`param_generator`* is one of the following GoogleTest-provided
 100 functions that generate the test parameters, all defined in the `::testing`
 101 namespace:
 102
 103 <span id="param-generators"></span>
 104
 105 | Parameter Generator | Behavior                                             |
 106 | ------------------- | ---------------------------------------------------- |
 107 | `Range(begin, end [, step])` | Yields values `{begin, begin+step, begin+step+step, ...}`. The values do not include `end`. `step` defaults to 1. |
 108 | `Values(v1, v2, ..., vN)`    | Yields values `{v1, v2, ..., vN}`.          |
 109 | `ValuesIn(container)` or `ValuesIn(begin,end)` | Yields values from a C-style array, an STL-style container, or an iterator range `[begin, end)`. |
 110 | `Bool()`                     | Yields sequence `{false, true}`.            |
 111 | `Combine(g1, g2, ..., gN)`   | Yields as `std::tuple` *n*-tuples all combinations (Cartesian product) of the values generated by the given *n* generators `g1`, `g2`, ..., `gN`. |
 112
 113 The optional last argument *`name_generator`* is a function or functor that
 114 generates custom test name suffixes based on the test parameters. The function
 115 must accept an argument of type
 116 [`TestParamInfo<class ParamType>`](#TestParamInfo) and return a `std::string`.
 117 The test name suffix can only contain alphanumeric characters and underscores.
 118 GoogleTest provides [`PrintToStringParamName`](#PrintToStringParamName), or a
 119 custom function can be used for more control:
 120
 121 ```cpp
 122 INSTANTIATE_TEST_SUITE_P(
 123     MyInstantiation, MyTestSuite,
 124     ::testing::Values(...),
 125     [](const ::testing::TestParamInfo<MyTestSuite::ParamType>& info) {
 126       // Can use info.param here to generate the test suffix
 127       std::string name = ...
 128       return name;
 129     });
 130 ```
 131
 132 For more information, see
 133 [Value-Parameterized Tests](../advanced.md#value-parameterized-tests).
 134
 135 See also
 136 [`GTEST_ALLOW_UNINSTANTIATED_PARAMETERIZED_TEST`](#GTEST_ALLOW_UNINSTANTIATED_PARAMETERIZED_TEST).
 137
 138 ### TYPED_TEST_SUITE {#TYPED_TEST_SUITE}
 139
 140 `TYPED_TEST_SUITE(`*`TestFixtureName`*`,`*`Types`*`)`
 141
 142 Defines a typed test suite based on the test fixture *`TestFixtureName`*. The
 143 test suite name is *`TestFixtureName`*.
 144
 145 The argument *`TestFixtureName`* is a fixture class template, parameterized by a
 146 type, for example:
 147
 148 ```cpp
 149 template <typename T>
 150 class MyFixture : public ::testing::Test {
 151  public:
 152   ...
 153   using List = std::list<T>;
 154   static T shared_;
 155   T value_;
 156 };
 157 ```
 158
 159 The argument *`Types`* is a [`Types`](#Types) object representing the list of
 160 types to run the tests on, for example:
 161
 162 ```cpp
 163 using MyTypes = ::testing::Types<char, int, unsigned int>;
 164 TYPED_TEST_SUITE(MyFixture, MyTypes);
 165 ```
 166
 167 The type alias (`using` or `typedef`) is necessary for the `TYPED_TEST_SUITE`
 168 macro to parse correctly.
 169
 170 See also [`TYPED_TEST`](#TYPED_TEST) and
 171 [Typed Tests](../advanced.md#typed-tests) for more information.
 172
 173 ### TYPED_TEST {#TYPED_TEST}
 174
 175 <pre>
 176 TYPED_TEST(<em>TestSuiteName</em>, <em>TestName</em>) {
 177   ... <em>statements</em> ...
 178 }
 179 </pre>
 180
 181 Defines an individual typed test named *`TestName`* in the typed test suite
 182 *`TestSuiteName`*. The test suite must be defined with
 183 [`TYPED_TEST_SUITE`](#TYPED_TEST_SUITE).
 184
 185 Within the test body, the special name `TypeParam` refers to the type parameter,
 186 and `TestFixture` refers to the fixture class. See the following example:
 187
 188 ```cpp
 189 TYPED_TEST(MyFixture, Example) {
 190   // Inside a test, refer to the special name TypeParam to get the type
 191   // parameter.  Since we are inside a derived class template, C++ requires
 192   // us to visit the members of MyFixture via 'this'.
 193   TypeParam n = this->value_;
 194
 195   // To visit static members of the fixture, add the 'TestFixture::'
 196   // prefix.
 197   n += TestFixture::shared_;
 198
 199   // To refer to typedefs in the fixture, add the 'typename TestFixture::'
 200   // prefix. The 'typename' is required to satisfy the compiler.
 201   typename TestFixture::List values;
 202
 203   values.push_back(n);
 204   ...
 205 }
 206 ```
 207
 208 For more information, see [Typed Tests](../advanced.md#typed-tests).
 209
 210 ### TYPED_TEST_SUITE_P {#TYPED_TEST_SUITE_P}
 211
 212 `TYPED_TEST_SUITE_P(`*`TestFixtureName`*`)`
 213
 214 Defines a type-parameterized test suite based on the test fixture
 215 *`TestFixtureName`*. The test suite name is *`TestFixtureName`*.
 216
 217 The argument *`TestFixtureName`* is a fixture class template, parameterized by a
 218 type. See [`TYPED_TEST_SUITE`](#TYPED_TEST_SUITE) for an example.
 219
 220 See also [`TYPED_TEST_P`](#TYPED_TEST_P) and
 221 [Type-Parameterized Tests](../advanced.md#type-parameterized-tests) for more
 222 information.
 223
 224 ### TYPED_TEST_P {#TYPED_TEST_P}
 225
 226 <pre>
 227 TYPED_TEST_P(<em>TestSuiteName</em>, <em>TestName</em>) {
 228   ... <em>statements</em> ...
 229 }
 230 </pre>
 231
 232 Defines an individual type-parameterized test named *`TestName`* in the
 233 type-parameterized test suite *`TestSuiteName`*. The test suite must be defined
 234 with [`TYPED_TEST_SUITE_P`](#TYPED_TEST_SUITE_P).
 235
 236 Within the test body, the special name `TypeParam` refers to the type parameter,
 237 and `TestFixture` refers to the fixture class. See [`TYPED_TEST`](#TYPED_TEST)
 238 for an example.
 239
 240 See also [`REGISTER_TYPED_TEST_SUITE_P`](#REGISTER_TYPED_TEST_SUITE_P) and
 241 [Type-Parameterized Tests](../advanced.md#type-parameterized-tests) for more
 242 information.
 243
 244 ### REGISTER_TYPED_TEST_SUITE_P {#REGISTER_TYPED_TEST_SUITE_P}
 245
 246 `REGISTER_TYPED_TEST_SUITE_P(`*`TestSuiteName`*`,`*`TestNames...`*`)`
 247
 248 Registers the type-parameterized tests *`TestNames...`* of the test suite
 249 *`TestSuiteName`*. The test suite and tests must be defined with
 250 [`TYPED_TEST_SUITE_P`](#TYPED_TEST_SUITE_P) and [`TYPED_TEST_P`](#TYPED_TEST_P).
 251
 252 For example:
 253
 254 ```cpp
 255 // Define the test suite and tests.
 256 TYPED_TEST_SUITE_P(MyFixture);
 257 TYPED_TEST_P(MyFixture, HasPropertyA) { ... }
 258 TYPED_TEST_P(MyFixture, HasPropertyB) { ... }
 259
 260 // Register the tests in the test suite.
 261 REGISTER_TYPED_TEST_SUITE_P(MyFixture, HasPropertyA, HasPropertyB);
 262 ```
 263
 264 See also [`INSTANTIATE_TYPED_TEST_SUITE_P`](#INSTANTIATE_TYPED_TEST_SUITE_P) and
 265 [Type-Parameterized Tests](../advanced.md#type-parameterized-tests) for more
 266 information.
 267
 268 ### INSTANTIATE_TYPED_TEST_SUITE_P {#INSTANTIATE_TYPED_TEST_SUITE_P}
 269
 270 `INSTANTIATE_TYPED_TEST_SUITE_P(`*`InstantiationName`*`,`*`TestSuiteName`*`,`*`Types`*`)`
 271
 272 Instantiates the type-parameterized test suite *`TestSuiteName`*. The test suite
 273 must be registered with
 274 [`REGISTER_TYPED_TEST_SUITE_P`](#REGISTER_TYPED_TEST_SUITE_P).
 275
 276 The argument *`InstantiationName`* is a unique name for the instantiation of the
 277 test suite, to distinguish between multiple instantiations. In test output, the
 278 instantiation name is added as a prefix to the test suite name
 279 *`TestSuiteName`*.
 280
 281 The argument *`Types`* is a [`Types`](#Types) object representing the list of
 282 types to run the tests on, for example:
 283
 284 ```cpp
 285 using MyTypes = ::testing::Types<char, int, unsigned int>;
 286 INSTANTIATE_TYPED_TEST_SUITE_P(MyInstantiation, MyFixture, MyTypes);
 287 ```
 288
 289 The type alias (`using` or `typedef`) is necessary for the
 290 `INSTANTIATE_TYPED_TEST_SUITE_P` macro to parse correctly.
 291
 292 For more information, see
 293 [Type-Parameterized Tests](../advanced.md#type-parameterized-tests).
 294
 295 ### FRIEND_TEST {#FRIEND_TEST}
 296
 297 `FRIEND_TEST(`*`TestSuiteName`*`,`*`TestName`*`)`
 298
 299 Within a class body, declares an individual test as a friend of the class,
 300 enabling the test to access private class members.
 301
 302 If the class is defined in a namespace, then in order to be friends of the
 303 class, test fixtures and tests must be defined in the exact same namespace,
 304 without inline or anonymous namespaces.
 305
 306 For example, if the class definition looks like the following:
 307
 308 ```cpp
 309 namespace my_namespace {
 310
 311 class MyClass {
 312   friend class MyClassTest;
 313   FRIEND_TEST(MyClassTest, HasPropertyA);
 314   FRIEND_TEST(MyClassTest, HasPropertyB);
 315   ... definition of class MyClass ...
 316 };
 317
 318 }  // namespace my_namespace
 319 ```
 320
 321 Then the test code should look like:
 322
 323 ```cpp
 324 namespace my_namespace {
 325
 326 class MyClassTest : public ::testing::Test {
 327   ...
 328 };
 329
 330 TEST_F(MyClassTest, HasPropertyA) { ... }
 331 TEST_F(MyClassTest, HasPropertyB) { ... }
 332
 333 }  // namespace my_namespace
 334 ```
 335
 336 See [Testing Private Code](../advanced.md#testing-private-code) for more
 337 information.
 338
 339 ### SCOPED_TRACE {#SCOPED_TRACE}
 340
 341 `SCOPED_TRACE(`*`message`*`)`
 342
 343 Causes the current file name, line number, and the given message *`message`* to
 344 be added to the failure message for each assertion failure that occurs in the
 345 scope.
 346
 347 For more information, see
 348 [Adding Traces to Assertions](../advanced.md#adding-traces-to-assertions).
 349
 350 See also the [`ScopedTrace` class](#ScopedTrace).
 351
 352 ### GTEST_SKIP {#GTEST_SKIP}
 353
 354 `GTEST_SKIP()`
 355
 356 Prevents further test execution at runtime.
 357
 358 Can be used in individual test cases or in the `SetUp()` methods of test
 359 environments or test fixtures (classes derived from the
 360 [`Environment`](#Environment) or [`Test`](#Test) classes). If used in a global
 361 test environment `SetUp()` method, it skips all tests in the test program. If
 362 used in a test fixture `SetUp()` method, it skips all tests in the corresponding
 363 test suite.
 364
 365 Similar to assertions, `GTEST_SKIP` allows streaming a custom message into it.
 366
 367 See [Skipping Test Execution](../advanced.md#skipping-test-execution) for more
 368 information.
 369
 370 ### GTEST_ALLOW_UNINSTANTIATED_PARAMETERIZED_TEST {#GTEST_ALLOW_UNINSTANTIATED_PARAMETERIZED_TEST}
 371
 372 `GTEST_ALLOW_UNINSTANTIATED_PARAMETERIZED_TEST(`*`TestSuiteName`*`)`
 373
 374 Allows the value-parameterized test suite *`TestSuiteName`* to be
 375 uninstantiated.
 376
 377 By default, every [`TEST_P`](#TEST_P) call without a corresponding
 378 [`INSTANTIATE_TEST_SUITE_P`](#INSTANTIATE_TEST_SUITE_P) call causes a failing
 379 test in the test suite `GoogleTestVerification`.
 380 `GTEST_ALLOW_UNINSTANTIATED_PARAMETERIZED_TEST` suppresses this failure for the
 381 given test suite.
 382
 383 ## Classes and types
 384
 385 GoogleTest defines the following classes and types to help with writing tests.
 386
 387 ### AssertionResult {#AssertionResult}
 388
 389 `::testing::AssertionResult`
 390
 391 A class for indicating whether an assertion was successful.
 392
 393 When the assertion wasn't successful, the `AssertionResult` object stores a
 394 non-empty failure message that can be retrieved with the object's `message()`
 395 method.
 396
 397 To create an instance of this class, use one of the factory functions
 398 [`AssertionSuccess()`](#AssertionSuccess) or
 399 [`AssertionFailure()`](#AssertionFailure).
 400
 401 ### AssertionException {#AssertionException}
 402
 403 `::testing::AssertionException`
 404
 405 Exception which can be thrown from
 406 [`TestEventListener::OnTestPartResult`](#TestEventListener::OnTestPartResult).
 407
 408 ### EmptyTestEventListener {#EmptyTestEventListener}
 409
 410 `::testing::EmptyTestEventListener`
 411
 412 Provides an empty implementation of all methods in the
 413 [`TestEventListener`](#TestEventListener) interface, such that a subclass only
 414 needs to override the methods it cares about.
 415
 416 ### Environment {#Environment}
 417
 418 `::testing::Environment`
 419
 420 Represents a global test environment. See
 421 [Global Set-Up and Tear-Down](../advanced.md#global-set-up-and-tear-down).
 422
 423 #### Protected Methods {#Environment-protected}
 424
 425 ##### SetUp {#Environment::SetUp}
 426
 427 `virtual void Environment::SetUp()`
 428
 429 Override this to define how to set up the environment.
 430
 431 ##### TearDown {#Environment::TearDown}
 432
 433 `virtual void Environment::TearDown()`
 434
 435 Override this to define how to tear down the environment.
 436
 437 ### ScopedTrace {#ScopedTrace}
 438
 439 `::testing::ScopedTrace`
 440
 441 An instance of this class causes a trace to be included in every test failure
 442 message generated by code in the scope of the lifetime of the `ScopedTrace`
 443 instance. The effect is undone with the destruction of the instance.
 444
 445 The `ScopedTrace` constructor has the following form:
 446
 447 ```cpp
 448 template <typename T>
 449 ScopedTrace(const char* file, int line, const T& message)
 450 ```
 451
 452 Example usage:
 453
 454 ```cpp
 455 ::testing::ScopedTrace trace("file.cc", 123, "message");
 456 ```
 457
 458 The resulting trace includes the given source file path and line number, and the
 459 given message. The `message` argument can be anything streamable to
 460 `std::ostream`.
 461
 462 See also [`SCOPED_TRACE`](#SCOPED_TRACE).
 463
 464 ### Test {#Test}
 465
 466 `::testing::Test`
 467
 468 The abstract class that all tests inherit from. `Test` is not copyable.
 469
 470 #### Public Methods {#Test-public}
 471
 472 ##### SetUpTestSuite {#Test::SetUpTestSuite}
 473
 474 `static void Test::SetUpTestSuite()`
 475
 476 Performs shared setup for all tests in the test suite. GoogleTest calls
 477 `SetUpTestSuite()` before running the first test in the test suite.
 478
 479 ##### TearDownTestSuite {#Test::TearDownTestSuite}
 480
 481 `static void Test::TearDownTestSuite()`
 482
 483 Performs shared teardown for all tests in the test suite. GoogleTest calls
 484 `TearDownTestSuite()` after running the last test in the test suite.
 485
 486 ##### HasFatalFailure {#Test::HasFatalFailure}
 487
 488 `static bool Test::HasFatalFailure()`
 489
 490 Returns true if and only if the current test has a fatal failure.
 491
 492 ##### HasNonfatalFailure {#Test::HasNonfatalFailure}
 493
 494 `static bool Test::HasNonfatalFailure()`
 495
 496 Returns true if and only if the current test has a nonfatal failure.
 497
 498 ##### HasFailure {#Test::HasFailure}
 499
 500 `static bool Test::HasFailure()`
 501
 502 Returns true if and only if the current test has any failure, either fatal or
 503 nonfatal.
 504
 505 ##### IsSkipped {#Test::IsSkipped}
 506
 507 `static bool Test::IsSkipped()`
 508
 509 Returns true if and only if the current test was skipped.
 510
 511 ##### RecordProperty {#Test::RecordProperty}
 512
 513 `static void Test::RecordProperty(const std::string& key, const std::string&
 514 value)` \
 515 `static void Test::RecordProperty(const std::string& key, int value)`
 516
 517 Logs a property for the current test, test suite, or entire invocation of the
 518 test program. Only the last value for a given key is logged.
 519
 520 The key must be a valid XML attribute name, and cannot conflict with the ones
 521 already used by GoogleTest (`name`, `file`, `line`, `status`, `time`,
 522 `classname`, `type_param`, and `value_param`).
 523
 524 `RecordProperty` is `public static` so it can be called from utility functions
 525 that are not members of the test fixture.
 526
 527 Calls to `RecordProperty` made during the lifespan of the test (from the moment
 528 its constructor starts to the moment its destructor finishes) are output in XML
 529 as attributes of the `<testcase>` element. Properties recorded from a fixture's
 530 `SetUpTestSuite` or `TearDownTestSuite` methods are logged as attributes of the
 531 corresponding `<testsuite>` element. Calls to `RecordProperty` made in the
 532 global context (before or after invocation of `RUN_ALL_TESTS` or from the
 533 `SetUp`/`TearDown` methods of registered `Environment` objects) are output as
 534 attributes of the `<testsuites>` element.
 535
 536 #### Protected Methods {#Test-protected}
 537
 538 ##### SetUp {#Test::SetUp}
 539
 540 `virtual void Test::SetUp()`
 541
 542 Override this to perform test fixture setup. GoogleTest calls `SetUp()` before
 543 running each individual test.
 544
 545 ##### TearDown {#Test::TearDown}
 546
 547 `virtual void Test::TearDown()`
 548
 549 Override this to perform test fixture teardown. GoogleTest calls `TearDown()`
 550 after running each individual test.
 551
 552 ### TestWithParam {#TestWithParam}
 553
 554 `::testing::TestWithParam<T>`
 555
 556 A convenience class which inherits from both [`Test`](#Test) and
 557 [`WithParamInterface<T>`](#WithParamInterface).
 558
 559 ### TestSuite {#TestSuite}
 560
 561 Represents a test suite. `TestSuite` is not copyable.
 562
 563 #### Public Methods {#TestSuite-public}
 564
 565 ##### name {#TestSuite::name}
 566
 567 `const char* TestSuite::name() const`
 568
 569 Gets the name of the test suite.
 570
 571 ##### type_param {#TestSuite::type_param}
 572
 573 `const char* TestSuite::type_param() const`
 574
 575 Returns the name of the parameter type, or `NULL` if this is not a typed or
 576 type-parameterized test suite. See [Typed Tests](../advanced.md#typed-tests) and
 577 [Type-Parameterized Tests](../advanced.md#type-parameterized-tests).
 578
 579 ##### should_run {#TestSuite::should_run}
 580
 581 `bool TestSuite::should_run() const`
 582
 583 Returns true if any test in this test suite should run.
 584
 585 ##### successful_test_count {#TestSuite::successful_test_count}
 586
 587 `int TestSuite::successful_test_count() const`
 588
 589 Gets the number of successful tests in this test suite.
 590
 591 ##### skipped_test_count {#TestSuite::skipped_test_count}
 592
 593 `int TestSuite::skipped_test_count() const`
 594
 595 Gets the number of skipped tests in this test suite.
 596
 597 ##### failed_test_count {#TestSuite::failed_test_count}
 598
 599 `int TestSuite::failed_test_count() const`
 600
 601 Gets the number of failed tests in this test suite.
 602
 603 ##### reportable_disabled_test_count {#TestSuite::reportable_disabled_test_count}
 604
 605 `int TestSuite::reportable_disabled_test_count() const`
 606
 607 Gets the number of disabled tests that will be reported in the XML report.
 608
 609 ##### disabled_test_count {#TestSuite::disabled_test_count}
 610
 611 `int TestSuite::disabled_test_count() const`
 612
 613 Gets the number of disabled tests in this test suite.
 614
 615 ##### reportable_test_count {#TestSuite::reportable_test_count}
 616
 617 `int TestSuite::reportable_test_count() const`
 618
 619 Gets the number of tests to be printed in the XML report.
 620
 621 ##### test_to_run_count {#TestSuite::test_to_run_count}
 622
 623 `int TestSuite::test_to_run_count() const`
 624
 625 Get the number of tests in this test suite that should run.
 626
 627 ##### total_test_count {#TestSuite::total_test_count}
 628
 629 `int TestSuite::total_test_count() const`
 630
 631 Gets the number of all tests in this test suite.
 632
 633 ##### Passed {#TestSuite::Passed}
 634
 635 `bool TestSuite::Passed() const`
 636
 637 Returns true if and only if the test suite passed.
 638
 639 ##### Failed {#TestSuite::Failed}
 640
 641 `bool TestSuite::Failed() const`
 642
 643 Returns true if and only if the test suite failed.
 644
 645 ##### elapsed_time {#TestSuite::elapsed_time}
 646
 647 `TimeInMillis TestSuite::elapsed_time() const`
 648
 649 Returns the elapsed time, in milliseconds.
 650
 651 ##### start_timestamp {#TestSuite::start_timestamp}
 652
 653 `TimeInMillis TestSuite::start_timestamp() const`
 654
 655 Gets the time of the test suite start, in ms from the start of the UNIX epoch.
 656
 657 ##### GetTestInfo {#TestSuite::GetTestInfo}
 658
 659 `const TestInfo* TestSuite::GetTestInfo(int i) const`
 660
 661 Returns the [`TestInfo`](#TestInfo) for the `i`-th test among all the tests. `i`
 662 can range from 0 to `total_test_count() - 1`. If `i` is not in that range,
 663 returns `NULL`.
 664
 665 ##### ad_hoc_test_result {#TestSuite::ad_hoc_test_result}
 666
 667 `const TestResult& TestSuite::ad_hoc_test_result() const`
 668
 669 Returns the [`TestResult`](#TestResult) that holds test properties recorded
 670 during execution of `SetUpTestSuite` and `TearDownTestSuite`.
 671
 672 ### TestInfo {#TestInfo}
 673
 674 `::testing::TestInfo`
 675
 676 Stores information about a test.
 677
 678 #### Public Methods {#TestInfo-public}
 679
 680 ##### test_suite_name {#TestInfo::test_suite_name}
 681
 682 `const char* TestInfo::test_suite_name() const`
 683
 684 Returns the test suite name.
 685
 686 ##### name {#TestInfo::name}
 687
 688 `const char* TestInfo::name() const`
 689
 690 Returns the test name.
 691
 692 ##### type_param {#TestInfo::type_param}
 693
 694 `const char* TestInfo::type_param() const`
 695
 696 Returns the name of the parameter type, or `NULL` if this is not a typed or
 697 type-parameterized test. See [Typed Tests](../advanced.md#typed-tests) and
 698 [Type-Parameterized Tests](../advanced.md#type-parameterized-tests).
 699
 700 ##### value_param {#TestInfo::value_param}
 701
 702 `const char* TestInfo::value_param() const`
 703
 704 Returns the text representation of the value parameter, or `NULL` if this is not
 705 a value-parameterized test. See
 706 [Value-Parameterized Tests](../advanced.md#value-parameterized-tests).
 707
 708 ##### file {#TestInfo::file}
 709
 710 `const char* TestInfo::file() const`
 711
 712 Returns the file name where this test is defined.
 713
 714 ##### line {#TestInfo::line}
 715
 716 `int TestInfo::line() const`
 717
 718 Returns the line where this test is defined.
 719
 720 ##### is_in_another_shard {#TestInfo::is_in_another_shard}
 721
 722 `bool TestInfo::is_in_another_shard() const`
 723
 724 Returns true if this test should not be run because it's in another shard.
 725
 726 ##### should_run {#TestInfo::should_run}
 727
 728 `bool TestInfo::should_run() const`
 729
 730 Returns true if this test should run, that is if the test is not disabled (or it
 731 is disabled but the `also_run_disabled_tests` flag has been specified) and its
 732 full name matches the user-specified filter.
 733
 734 GoogleTest allows the user to filter the tests by their full names. Only the
 735 tests that match the filter will run. See
 736 [Running a Subset of the Tests](../advanced.md#running-a-subset-of-the-tests)
 737 for more information.
 738
 739 ##### is_reportable {#TestInfo::is_reportable}
 740
 741 `bool TestInfo::is_reportable() const`
 742
 743 Returns true if and only if this test will appear in the XML report.
 744
 745 ##### result {#TestInfo::result}
 746
 747 `const TestResult* TestInfo::result() const`
 748
 749 Returns the result of the test. See [`TestResult`](#TestResult).
 750
 751 ### TestParamInfo {#TestParamInfo}
 752
 753 `::testing::TestParamInfo<T>`
 754
 755 Describes a parameter to a value-parameterized test. The type `T` is the type of
 756 the parameter.
 757
 758 Contains the fields `param` and `index` which hold the value of the parameter
 759 and its integer index respectively.
 760
 761 ### UnitTest {#UnitTest}
 762
 763 `::testing::UnitTest`
 764
 765 This class contains information about the test program.
 766
 767 `UnitTest` is a singleton class. The only instance is created when
 768 `UnitTest::GetInstance()` is first called. This instance is never deleted.
 769
 770 `UnitTest` is not copyable.
 771
 772 #### Public Methods {#UnitTest-public}
 773
 774 ##### GetInstance {#UnitTest::GetInstance}
 775
 776 `static UnitTest* UnitTest::GetInstance()`
 777
 778 Gets the singleton `UnitTest` object. The first time this method is called, a
 779 `UnitTest` object is constructed and returned. Consecutive calls will return the
 780 same object.
 781
 782 ##### original_working_dir {#UnitTest::original_working_dir}
 783
 784 `const char* UnitTest::original_working_dir() const`
 785
 786 Returns the working directory when the first [`TEST()`](#TEST) or
 787 [`TEST_F()`](#TEST_F) was executed. The `UnitTest` object owns the string.
 788
 789 ##### current_test_suite {#UnitTest::current_test_suite}
 790
 791 `const TestSuite* UnitTest::current_test_suite() const`
 792
 793 Returns the [`TestSuite`](#TestSuite) object for the test that's currently
 794 running, or `NULL` if no test is running.
 795
 796 ##### current_test_info {#UnitTest::current_test_info}
 797
 798 `const TestInfo* UnitTest::current_test_info() const`
 799
 800 Returns the [`TestInfo`](#TestInfo) object for the test that's currently
 801 running, or `NULL` if no test is running.
 802
 803 ##### random_seed {#UnitTest::random_seed}
 804
 805 `int UnitTest::random_seed() const`
 806
 807 Returns the random seed used at the start of the current test run.
 808
 809 ##### successful_test_suite_count {#UnitTest::successful_test_suite_count}
 810
 811 `int UnitTest::successful_test_suite_count() const`
 812
 813 Gets the number of successful test suites.
 814
 815 ##### failed_test_suite_count {#UnitTest::failed_test_suite_count}
 816
 817 `int UnitTest::failed_test_suite_count() const`
 818
 819 Gets the number of failed test suites.
 820
 821 ##### total_test_suite_count {#UnitTest::total_test_suite_count}
 822
 823 `int UnitTest::total_test_suite_count() const`
 824
 825 Gets the number of all test suites.
 826
 827 ##### test_suite_to_run_count {#UnitTest::test_suite_to_run_count}
 828
 829 `int UnitTest::test_suite_to_run_count() const`
 830
 831 Gets the number of all test suites that contain at least one test that should
 832 run.
 833
 834 ##### successful_test_count {#UnitTest::successful_test_count}
 835
 836 `int UnitTest::successful_test_count() const`
 837
 838 Gets the number of successful tests.
 839
 840 ##### skipped_test_count {#UnitTest::skipped_test_count}
 841
 842 `int UnitTest::skipped_test_count() const`
 843
 844 Gets the number of skipped tests.
 845
 846 ##### failed_test_count {#UnitTest::failed_test_count}
 847
 848 `int UnitTest::failed_test_count() const`
 849
 850 Gets the number of failed tests.
 851
 852 ##### reportable_disabled_test_count {#UnitTest::reportable_disabled_test_count}
 853
 854 `int UnitTest::reportable_disabled_test_count() const`
 855
 856 Gets the number of disabled tests that will be reported in the XML report.
 857
 858 ##### disabled_test_count {#UnitTest::disabled_test_count}
 859
 860 `int UnitTest::disabled_test_count() const`
 861
 862 Gets the number of disabled tests.
 863
 864 ##### reportable_test_count {#UnitTest::reportable_test_count}
 865
 866 `int UnitTest::reportable_test_count() const`
 867
 868 Gets the number of tests to be printed in the XML report.
 869
 870 ##### total_test_count {#UnitTest::total_test_count}
 871
 872 `int UnitTest::total_test_count() const`
 873
 874 Gets the number of all tests.
 875
 876 ##### test_to_run_count {#UnitTest::test_to_run_count}
 877
 878 `int UnitTest::test_to_run_count() const`
 879
 880 Gets the number of tests that should run.
 881
 882 ##### start_timestamp {#UnitTest::start_timestamp}
 883
 884 `TimeInMillis UnitTest::start_timestamp() const`
 885
 886 Gets the time of the test program start, in ms from the start of the UNIX epoch.
 887
 888 ##### elapsed_time {#UnitTest::elapsed_time}
 889
 890 `TimeInMillis UnitTest::elapsed_time() const`
 891
 892 Gets the elapsed time, in milliseconds.
 893
 894 ##### Passed {#UnitTest::Passed}
 895
 896 `bool UnitTest::Passed() const`
 897
 898 Returns true if and only if the unit test passed (i.e. all test suites passed).
 899
 900 ##### Failed {#UnitTest::Failed}
 901
 902 `bool UnitTest::Failed() const`
 903
 904 Returns true if and only if the unit test failed (i.e. some test suite failed or
 905 something outside of all tests failed).
 906
 907 ##### GetTestSuite {#UnitTest::GetTestSuite}
 908
 909 `const TestSuite* UnitTest::GetTestSuite(int i) const`
 910
 911 Gets the [`TestSuite`](#TestSuite) object for the `i`-th test suite among all
 912 the test suites. `i` can range from 0 to `total_test_suite_count() - 1`. If `i`
 913 is not in that range, returns `NULL`.
 914
 915 ##### ad_hoc_test_result {#UnitTest::ad_hoc_test_result}
 916
 917 `const TestResult& UnitTest::ad_hoc_test_result() const`
 918
 919 Returns the [`TestResult`](#TestResult) containing information on test failures
 920 and properties logged outside of individual test suites.
 921
 922 ##### listeners {#UnitTest::listeners}
 923
 924 `TestEventListeners& UnitTest::listeners()`
 925
 926 Returns the list of event listeners that can be used to track events inside
 927 GoogleTest. See [`TestEventListeners`](#TestEventListeners).
 928
 929 ### TestEventListener {#TestEventListener}
 930
 931 `::testing::TestEventListener`
 932
 933 The interface for tracing execution of tests. The methods below are listed in
 934 the order the corresponding events are fired.
 935
 936 #### Public Methods {#TestEventListener-public}
 937
 938 ##### OnTestProgramStart {#TestEventListener::OnTestProgramStart}
 939
 940 `virtual void TestEventListener::OnTestProgramStart(const UnitTest& unit_test)`
 941
 942 Fired before any test activity starts.
 943
 944 ##### OnTestIterationStart {#TestEventListener::OnTestIterationStart}
 945
 946 `virtual void TestEventListener::OnTestIterationStart(const UnitTest& unit_test,
 947 int iteration)`
 948
 949 Fired before each iteration of tests starts. There may be more than one
 950 iteration if `GTEST_FLAG(repeat)` is set. `iteration` is the iteration index,
 951 starting from 0.
 952
 953 ##### OnEnvironmentsSetUpStart {#TestEventListener::OnEnvironmentsSetUpStart}
 954
 955 `virtual void TestEventListener::OnEnvironmentsSetUpStart(const UnitTest&
 956 unit_test)`
 957
 958 Fired before environment set-up for each iteration of tests starts.
 959
 960 ##### OnEnvironmentsSetUpEnd {#TestEventListener::OnEnvironmentsSetUpEnd}
 961
 962 `virtual void TestEventListener::OnEnvironmentsSetUpEnd(const UnitTest&
 963 unit_test)`
 964
 965 Fired after environment set-up for each iteration of tests ends.
 966
 967 ##### OnTestSuiteStart {#TestEventListener::OnTestSuiteStart}
 968
 969 `virtual void TestEventListener::OnTestSuiteStart(const TestSuite& test_suite)`
 970
 971 Fired before the test suite starts.
 972
 973 ##### OnTestStart {#TestEventListener::OnTestStart}
 974
 975 `virtual void TestEventListener::OnTestStart(const TestInfo& test_info)`
 976
 977 Fired before the test starts.
 978
 979 ##### OnTestPartResult {#TestEventListener::OnTestPartResult}
 980
 981 `virtual void TestEventListener::OnTestPartResult(const TestPartResult&
 982 test_part_result)`
 983
 984 Fired after a failed assertion or a `SUCCEED()` invocation. If you want to throw
 985 an exception from this function to skip to the next test, it must be an
 986 [`AssertionException`](#AssertionException) or inherited from it.
 987
 988 ##### OnTestEnd {#TestEventListener::OnTestEnd}
 989
 990 `virtual void TestEventListener::OnTestEnd(const TestInfo& test_info)`
 991
 992 Fired after the test ends.
 993
 994 ##### OnTestSuiteEnd {#TestEventListener::OnTestSuiteEnd}
 995
 996 `virtual void TestEventListener::OnTestSuiteEnd(const TestSuite& test_suite)`
 997
 998 Fired after the test suite ends.
 999
1000 ##### OnEnvironmentsTearDownStart {#TestEventListener::OnEnvironmentsTearDownStart}
1001
1002 `virtual void TestEventListener::OnEnvironmentsTearDownStart(const UnitTest&
1003 unit_test)`
1004
1005 Fired before environment tear-down for each iteration of tests starts.
1006
1007 ##### OnEnvironmentsTearDownEnd {#TestEventListener::OnEnvironmentsTearDownEnd}
1008
1009 `virtual void TestEventListener::OnEnvironmentsTearDownEnd(const UnitTest&
1010 unit_test)`
1011
1012 Fired after environment tear-down for each iteration of tests ends.
1013
1014 ##### OnTestIterationEnd {#TestEventListener::OnTestIterationEnd}
1015
1016 `virtual void TestEventListener::OnTestIterationEnd(const UnitTest& unit_test,
1017 int iteration)`
1018
1019 Fired after each iteration of tests finishes.
1020
1021 ##### OnTestProgramEnd {#TestEventListener::OnTestProgramEnd}
1022
1023 `virtual void TestEventListener::OnTestProgramEnd(const UnitTest& unit_test)`
1024
1025 Fired after all test activities have ended.
1026
1027 ### TestEventListeners {#TestEventListeners}
1028
1029 `::testing::TestEventListeners`
1030
1031 Lets users add listeners to track events in GoogleTest.
1032
1033 #### Public Methods {#TestEventListeners-public}
1034
1035 ##### Append {#TestEventListeners::Append}
1036
1037 `void TestEventListeners::Append(TestEventListener* listener)`
1038
1039 Appends an event listener to the end of the list. GoogleTest assumes ownership
1040 of the listener (i.e. it will delete the listener when the test program
1041 finishes).
1042
1043 ##### Release {#TestEventListeners::Release}
1044
1045 `TestEventListener* TestEventListeners::Release(TestEventListener* listener)`
1046
1047 Removes the given event listener from the list and returns it. It then becomes
1048 the caller's responsibility to delete the listener. Returns `NULL` if the
1049 listener is not found in the list.
1050
1051 ##### default_result_printer {#TestEventListeners::default_result_printer}
1052
1053 `TestEventListener* TestEventListeners::default_result_printer() const`
1054
1055 Returns the standard listener responsible for the default console output. Can be
1056 removed from the listeners list to shut down default console output. Note that
1057 removing this object from the listener list with
1058 [`Release()`](#TestEventListeners::Release) transfers its ownership to the
1059 caller and makes this function return `NULL` the next time.
1060
1061 ##### default_xml_generator {#TestEventListeners::default_xml_generator}
1062
1063 `TestEventListener* TestEventListeners::default_xml_generator() const`
1064
1065 Returns the standard listener responsible for the default XML output controlled
1066 by the `--gtest_output=xml` flag. Can be removed from the listeners list by
1067 users who want to shut down the default XML output controlled by this flag and
1068 substitute it with custom one. Note that removing this object from the listener
1069 list with [`Release()`](#TestEventListeners::Release) transfers its ownership to
1070 the caller and makes this function return `NULL` the next time.
1071
1072 ### TestPartResult {#TestPartResult}
1073
1074 `::testing::TestPartResult`
1075
1076 A copyable object representing the result of a test part (i.e. an assertion or
1077 an explicit `FAIL()`, `ADD_FAILURE()`, or `SUCCESS()`).
1078
1079 #### Public Methods {#TestPartResult-public}
1080
1081 ##### type {#TestPartResult::type}
1082
1083 `Type TestPartResult::type() const`
1084
1085 Gets the outcome of the test part.
1086
1087 The return type `Type` is an enum defined as follows:
1088
1089 ```cpp
1090 enum Type {
1091   kSuccess,          // Succeeded.
1092   kNonFatalFailure,  // Failed but the test can continue.
1093   kFatalFailure,     // Failed and the test should be terminated.
1094   kSkip              // Skipped.
1095 };
1096 ```
1097
1098 ##### file_name {#TestPartResult::file_name}
1099
1100 `const char* TestPartResult::file_name() const`
1101
1102 Gets the name of the source file where the test part took place, or `NULL` if
1103 it's unknown.
1104
1105 ##### line_number {#TestPartResult::line_number}
1106
1107 `int TestPartResult::line_number() const`
1108
1109 Gets the line in the source file where the test part took place, or `-1` if it's
1110 unknown.
1111
1112 ##### summary {#TestPartResult::summary}
1113
1114 `const char* TestPartResult::summary() const`
1115
1116 Gets the summary of the failure message.
1117
1118 ##### message {#TestPartResult::message}
1119
1120 `const char* TestPartResult::message() const`
1121
1122 Gets the message associated with the test part.
1123
1124 ##### skipped {#TestPartResult::skipped}
1125
1126 `bool TestPartResult::skipped() const`
1127
1128 Returns true if and only if the test part was skipped.
1129
1130 ##### passed {#TestPartResult::passed}
1131
1132 `bool TestPartResult::passed() const`
1133
1134 Returns true if and only if the test part passed.
1135
1136 ##### nonfatally_failed {#TestPartResult::nonfatally_failed}
1137
1138 `bool TestPartResult::nonfatally_failed() const`
1139
1140 Returns true if and only if the test part non-fatally failed.
1141
1142 ##### fatally_failed {#TestPartResult::fatally_failed}
1143
1144 `bool TestPartResult::fatally_failed() const`
1145
1146 Returns true if and only if the test part fatally failed.
1147
1148 ##### failed {#TestPartResult::failed}
1149
1150 `bool TestPartResult::failed() const`
1151
1152 Returns true if and only if the test part failed.
1153
1154 ### TestProperty {#TestProperty}
1155
1156 `::testing::TestProperty`
1157
1158 A copyable object representing a user-specified test property which can be
1159 output as a key/value string pair.
1160
1161 #### Public Methods {#TestProperty-public}
1162
1163 ##### key {#key}
1164
1165 `const char* key() const`
1166
1167 Gets the user-supplied key.
1168
1169 ##### value {#value}
1170
1171 `const char* value() const`
1172
1173 Gets the user-supplied value.
1174
1175 ##### SetValue {#SetValue}
1176
1177 `void SetValue(const std::string& new_value)`
1178
1179 Sets a new value, overriding the previous one.
1180
1181 ### TestResult {#TestResult}
1182
1183 `::testing::TestResult`
1184
1185 Contains information about the result of a single test.
1186
1187 `TestResult` is not copyable.
1188
1189 #### Public Methods {#TestResult-public}
1190
1191 ##### total_part_count {#TestResult::total_part_count}
1192
1193 `int TestResult::total_part_count() const`
1194
1195 Gets the number of all test parts. This is the sum of the number of successful
1196 test parts and the number of failed test parts.
1197
1198 ##### test_property_count {#TestResult::test_property_count}
1199
1200 `int TestResult::test_property_count() const`
1201
1202 Returns the number of test properties.
1203
1204 ##### Passed {#TestResult::Passed}
1205
1206 `bool TestResult::Passed() const`
1207
1208 Returns true if and only if the test passed (i.e. no test part failed).
1209
1210 ##### Skipped {#TestResult::Skipped}
1211
1212 `bool TestResult::Skipped() const`
1213
1214 Returns true if and only if the test was skipped.
1215
1216 ##### Failed {#TestResult::Failed}
1217
1218 `bool TestResult::Failed() const`
1219
1220 Returns true if and only if the test failed.
1221
1222 ##### HasFatalFailure {#TestResult::HasFatalFailure}
1223
1224 `bool TestResult::HasFatalFailure() const`
1225
1226 Returns true if and only if the test fatally failed.
1227
1228 ##### HasNonfatalFailure {#TestResult::HasNonfatalFailure}
1229
1230 `bool TestResult::HasNonfatalFailure() const`
1231
1232 Returns true if and only if the test has a non-fatal failure.
1233
1234 ##### elapsed_time {#TestResult::elapsed_time}
1235
1236 `TimeInMillis TestResult::elapsed_time() const`
1237
1238 Returns the elapsed time, in milliseconds.
1239
1240 ##### start_timestamp {#TestResult::start_timestamp}
1241
1242 `TimeInMillis TestResult::start_timestamp() const`
1243
1244 Gets the time of the test case start, in ms from the start of the UNIX epoch.
1245
1246 ##### GetTestPartResult {#TestResult::GetTestPartResult}
1247
1248 `const TestPartResult& TestResult::GetTestPartResult(int i) const`
1249
1250 Returns the [`TestPartResult`](#TestPartResult) for the `i`-th test part result
1251 among all the results. `i` can range from 0 to `total_part_count() - 1`. If `i`
1252 is not in that range, aborts the program.
1253
1254 ##### GetTestProperty {#TestResult::GetTestProperty}
1255
1256 `const TestProperty& TestResult::GetTestProperty(int i) const`
1257
1258 Returns the [`TestProperty`](#TestProperty) object for the `i`-th test property.
1259 `i` can range from 0 to `test_property_count() - 1`. If `i` is not in that
1260 range, aborts the program.
1261
1262 ### TimeInMillis {#TimeInMillis}
1263
1264 `::testing::TimeInMillis`
1265
1266 An integer type representing time in milliseconds.
1267
1268 ### Types {#Types}
1269
1270 `::testing::Types<T...>`
1271
1272 Represents a list of types for use in typed tests and type-parameterized tests.
1273
1274 The template argument `T...` can be any number of types, for example:
1275
1276 ```
1277 ::testing::Types<char, int, unsigned int>
1278 ```
1279
1280 See [Typed Tests](../advanced.md#typed-tests) and
1281 [Type-Parameterized Tests](../advanced.md#type-parameterized-tests) for more
1282 information.
1283
1284 ### WithParamInterface {#WithParamInterface}
1285
1286 `::testing::WithParamInterface<T>`
1287
1288 The pure interface class that all value-parameterized tests inherit from.
1289
1290 A value-parameterized test fixture class must inherit from both [`Test`](#Test)
1291 and `WithParamInterface`. In most cases that just means inheriting from
1292 [`TestWithParam`](#TestWithParam), but more complicated test hierarchies may
1293 need to inherit from `Test` and `WithParamInterface` at different levels.
1294
1295 This interface defines the type alias `ParamType` for the parameter type `T` and
1296 has support for accessing the test parameter value via the `GetParam()` method:
1297
1298 ```
1299 static const ParamType& GetParam()
1300 ```
1301
1302 For more information, see
1303 [Value-Parameterized Tests](../advanced.md#value-parameterized-tests).
1304
1305 ## Functions
1306
1307 GoogleTest defines the following functions to help with writing and running
1308 tests.
1309
1310 ### InitGoogleTest {#InitGoogleTest}
1311
1312 `void ::testing::InitGoogleTest(int* argc, char** argv)` \
1313 `void ::testing::InitGoogleTest(int* argc, wchar_t** argv)` \
1314 `void ::testing::InitGoogleTest()`
1315
1316 Initializes GoogleTest. This must be called before calling
1317 [`RUN_ALL_TESTS()`](#RUN_ALL_TESTS). In particular, it parses the command line
1318 for the flags that GoogleTest recognizes. Whenever a GoogleTest flag is seen, it
1319 is removed from `argv`, and `*argc` is decremented.
1320
1321 No value is returned. Instead, the GoogleTest flag variables are updated.
1322
1323 The `InitGoogleTest(int* argc, wchar_t** argv)` overload can be used in Windows
1324 programs compiled in `UNICODE` mode.
1325
1326 The argument-less `InitGoogleTest()` overload can be used on Arduino/embedded
1327 platforms where there is no `argc`/`argv`.
1328
1329 ### AddGlobalTestEnvironment {#AddGlobalTestEnvironment}
1330
1331 `Environment* ::testing::AddGlobalTestEnvironment(Environment* env)`
1332
1333 Adds a test environment to the test program. Must be called before
1334 [`RUN_ALL_TESTS()`](#RUN_ALL_TESTS) is called. See
1335 [Global Set-Up and Tear-Down](../advanced.md#global-set-up-and-tear-down) for
1336 more information.
1337
1338 See also [`Environment`](#Environment).
1339
1340 ### RegisterTest {#RegisterTest}
1341
1342 ```cpp
1343 template <typename Factory>
1344 TestInfo* ::testing::RegisterTest(const char* test_suite_name, const char* test_name,
1345                                   const char* type_param, const char* value_param,
1346                                   const char* file, int line, Factory factory)
1347 ```
1348
1349 Dynamically registers a test with the framework.
1350
1351 The `factory` argument is a factory callable (move-constructible) object or
1352 function pointer that creates a new instance of the `Test` object. It handles
1353 ownership to the caller. The signature of the callable is `Fixture*()`, where
1354 `Fixture` is the test fixture class for the test. All tests registered with the
1355 same `test_suite_name` must return the same fixture type. This is checked at
1356 runtime.
1357
1358 The framework will infer the fixture class from the factory and will call the
1359 `SetUpTestSuite` and `TearDownTestSuite` methods for it.
1360
1361 Must be called before [`RUN_ALL_TESTS()`](#RUN_ALL_TESTS) is invoked, otherwise
1362 behavior is undefined.
1363
1364 See
1365 [Registering tests programmatically](../advanced.md#registering-tests-programmatically)
1366 for more information.
1367
1368 ### RUN_ALL_TESTS {#RUN_ALL_TESTS}
1369
1370 `int RUN_ALL_TESTS()`
1371
1372 Use this function in `main()` to run all tests. It returns `0` if all tests are
1373 successful, or `1` otherwise.
1374
1375 `RUN_ALL_TESTS()` should be invoked after the command line has been parsed by
1376 [`InitGoogleTest()`](#InitGoogleTest).
1377
1378 This function was formerly a macro; thus, it is in the global namespace and has
1379 an all-caps name.
1380
1381 ### AssertionSuccess {#AssertionSuccess}
1382
1383 `AssertionResult ::testing::AssertionSuccess()`
1384
1385 Creates a successful assertion result. See
1386 [`AssertionResult`](#AssertionResult).
1387
1388 ### AssertionFailure {#AssertionFailure}
1389
1390 `AssertionResult ::testing::AssertionFailure()`
1391
1392 Creates a failed assertion result. Use the `<<` operator to store a failure
1393 message:
1394
1395 ```cpp
1396 ::testing::AssertionFailure() << "My failure message";
1397 ```
1398
1399 See [`AssertionResult`](#AssertionResult).
1400
1401 ### StaticAssertTypeEq {#StaticAssertTypeEq}
1402
1403 `::testing::StaticAssertTypeEq<T1, T2>()`
1404
1405 Compile-time assertion for type equality. Compiles if and only if `T1` and `T2`
1406 are the same type. The value it returns is irrelevant.
1407
1408 See [Type Assertions](../advanced.md#type-assertions) for more information.
1409
1410 ### PrintToString {#PrintToString}
1411
1412 `std::string ::testing::PrintToString(x)`
1413
1414 Prints any value `x` using GoogleTest's value printer.
1415
1416 See
1417 [Teaching GoogleTest How to Print Your Values](../advanced.md#teaching-googletest-how-to-print-your-values)
1418 for more information.
1419
1420 ### PrintToStringParamName {#PrintToStringParamName}
1421
1422 `std::string ::testing::PrintToStringParamName(TestParamInfo<T>& info)`
1423
1424 A built-in parameterized test name generator which returns the result of
1425 [`PrintToString`](#PrintToString) called on `info.param`. Does not work when the
1426 test parameter is a `std::string` or C string. See
1427 [Specifying Names for Value-Parameterized Test Parameters](../advanced.md#specifying-names-for-value-parameterized-test-parameters)
1428 for more information.
1429
1430 See also [`TestParamInfo`](#TestParamInfo) and
1431 [`INSTANTIATE_TEST_SUITE_P`](#INSTANTIATE_TEST_SUITE_P).