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