# GoogleTest Test Repeating and Environment Recreation (--gtest_repeat): Complete Guide > Master GoogleTest's --gtest_repeat and --gtest_recreate_environments_when_repeating flags. Learn how to repeat tests and manage environments efficiently for robust testing. - Repository: [Google/googletest](https://github.com/google/googletest) - Tags: how-to-guide - Published: 2026-08-29 --- **GoogleTest's `--gtest_repeat` flag runs tests for multiple iterations while `--gtest_recreate_environments_when_repeating` controls whether global test environments are destroyed and rebuilt between repeats, defaulting to `false` for performance but automatically enabling when repeating forever.** The `--gtest_repeat` functionality in GoogleTest allows developers to execute test suites multiple times to detect flaky behavior, but understanding how it interacts with global test environments is critical for resource management and test isolation. According to the GoogleTest source code in `googletest/src/gtest.cc`, the framework provides granular control over whether expensive global environments are recreated between iterations or maintained across the entire run. This article examines the implementation details, execution flow, and practical configuration options for test repeating and environment lifecycle management. ## How `--gtest_repeat` Works in the Source Code GoogleTest implements test repeating through two command-line flags defined in the core runtime. These flags control iteration count and environment lifecycle independently, allowing flexible configurations for different testing scenarios. ### Flag Definitions in `googletest/src/gtest.cc` The flags are registered in [`googletest/src/gtest.cc`](https://github.com/google/googletest/blob/main/googletest/src/gtest.cc#L363-L373) using GoogleTest's internal flag macros: ```cpp GTEST_DEFINE_int32_( repeat, testing::internal::Int32FromGTestEnv("repeat", 1), "How many times to repeat each test. Specify a negative number " "for repeating forever. Useful for shaking out flaky tests."); GTEST_DEFINE_bool_( recreate_environments_when_repeating, testing::internal::BoolFromGTestEnv("recreate_environments_when_repeating", false), "Controls whether global test environments are recreated for each repeat " "of the tests. If set to false the global test environments are only set " "up once, for the first iteration, and only torn down once, for the last. " "Useful for shaking out flaky tests with stable, expensive test environments."); ``` The `repeat` flag accepts any integer, where negative values trigger infinite repetition. The `recreate_environments_when_repeating` boolean determines whether the framework invokes `SetUp()` and `TearDown()` on global environments for every iteration or only at the boundaries of the entire run. ### The Main Execution Loop in `UnitTest::Run()` The repetition logic resides in `::testing::UnitTest::Run()`, implemented around line 6020 in `googletest/src/gtest.cc`. The method calculates repetition parameters and manages the iteration lifecycle: ```cpp const int repeat = GTEST_FLAG_GET(repeat); const bool gtest_repeat_forever = repeat < 0; const bool recreate_environments_when_repeating = GTEST_FLAG_GET(recreate_environments_when_repeating) || gtest_repeat_forever; ``` The framework then executes a `for` loop that continues until the specified count is reached or indefinitely if `gtest_repeat_forever` is true. Within this loop, the **TestEventRepeater** (`repeater`) forwards events to all registered listeners for each iteration: ```cpp for (int i = 0; gtest_repeat_forever || i != repeat; i++) { repeater->OnTestIterationStart(*parent_, i); if (i == 0 || recreate_environments_when_repeating) { repeater->OnEnvironmentsSetUpStart(*parent_); repeater->OnEnvironmentsSetUpEnd(*parent_); } // ... test execution occurs here ... if (i == repeat - 1 || recreate_environments_when_repeating) { repeater->OnEnvironmentsTearDownStart(*parent_); repeater->OnEnvironmentsTearDownEnd(*parent_); } repeater->OnTestIterationEnd(*parent_, i); } ``` When `recreate_environments_when_repeating` is `false`, environments are set up only during the first iteration (`i == 0`) and torn down only during the final iteration (`i == repeat - 1`). When `true`, these callbacks execute every iteration, ensuring complete isolation between repeats. ## Environment Recreation Behavior Global test environments (`::testing::Environment`) typically manage costly resources such as database connections, network services, or hardware interfaces. The recreation flag directly impacts both test isolation and execution performance. ### Iteration-Based Environment Lifecycle The default behavior optimizes for speed by maintaining global environments across repeats. In `googletest/src/gtest.cc`, the logic checks boundary conditions to determine when to trigger setup and teardown: - **First iteration only**: `SetUp()` runs when `i == 0` if not recreating environments - **Last iteration only**: `TearDown()` runs when `i == repeat - 1` if not recreating environments - **Every iteration**: Both methods run every time when `recreate_environments_when_repeating` is `true` This design prevents expensive allocation and deallocation operations from dominating test runtime during stability checks while still allowing full isolation when detecting state-dependent failures. ### Automatic Recreation for Infinite Loops When `--gtest_repeat` is set to a negative value (infinite repetition), the framework automatically forces environment recreation regardless of the explicit flag setting. This prevents resource leaks and memory exhaustion during long-running stability tests: ```cpp const bool recreate_environments_when_repeating = GTEST_FLAG_GET(recreate_environments_when_repeating) || gtest_repeat_forever; // Forces true when repeating forever ``` This safety mechanism ensures that each iteration starts with fresh global state, eliminating cumulative side effects that could mask or mimic flaky behavior during extended test runs. ## Practical Usage Examples Configuring test repetition requires understanding both command-line invocation and programmatic flag manipulation within custom test runners. ### Command Line Configuration Execute tests from the shell using standard GoogleTest flag syntax: ```bash # Run each test 10 times without recreating environments (fast) ./my_test_binary --gtest_repeat=10 # Run each test 10 times with fresh environments every iteration (isolated) ./my_test_binary --gtest_repeat=10 --gtest_recreate_environments_when_repeating=true # Repeat forever until manually stopped, with environments recreated each time ./my_test_binary --gtest_repeat=-1 ``` Alternatively, use environment variables which GoogleTest reads during initialization: ```bash export GTEST_REPEAT=4 export GTEST_RECREATE_ENVIRONMENTS_WHEN_REPEATING=1 ./my_test_binary ``` ### Programmatic Flag Setting For custom test harnesses, modify flags after initialization but before running tests: ```cpp #include int main(int argc, char **argv) { ::testing::InitGoogleTest(&argc, argv); // Override flags programmatically GTEST_FLAG_SET(repeat, 5); GTEST_FLAG_SET(recreate_environments_when_repeating, true); return RUN_ALL_TESTS(); } ``` This approach is useful when building specialized test runners that need to enforce specific repetition policies without requiring users to remember command-line arguments. ### Global Environment Implementation When using `--gtest_repeat`, the behavior of custom environment classes depends on the recreation flag: ```cpp class DatabaseEnvironment : public ::testing::Environment { public: void SetUp() override { // Expensive operation: connect to test database db_connection_ = CreateConnection(); } void TearDown() override { // Clean up connection db_connection_->Disconnect(); } private: DBConnection* db_connection_; }; int main(int argc, char **argv) { ::testing::InitGoogleTest(&argc, argv); ::testing::AddGlobalTestEnvironment(new DatabaseEnvironment); return RUN_ALL_TESTS(); } ``` With `--gtest_repeat=3` and default settings, `SetUp()` executes once and `TearDown()` executes once after the third iteration. With `--gtest_recreate_environments_when_repeating=true`, the database connection is destroyed and recreated three times, ensuring no state persists between iterations. ## Summary GoogleTest's repetition mechanism provides flexible control over test execution and resource management: - **`--gtest_repeat=`** runs the entire test suite `n` times, with negative values indicating infinite repetition - **`--gtest_recreate_environments_when_repeating`** defaults to `false` to minimize overhead, but forces environment recreation every iteration when set to `true` - Infinite repetition automatically enables environment recreation to prevent resource exhaustion - Global environments follow boundary-only setup/teardown by default, running only at the start of the first iteration and end of the final iteration - The `TestEventRepeater` notifies all listeners of iteration boundaries, ensuring reporters correctly handle multiple passes ## Frequently Asked Questions ### Does `--gtest_repeat` recreate global environments by default? No, the default value for `--gtest_recreate_environments_when_repeating` is `false` according to the flag definition in `googletest/src/gtest.cc`. This means global test environments are set up once before the first iteration and torn down once after the final iteration, minimizing overhead for expensive resources like database connections or network services. ### How does infinite test repeating affect environment lifecycle? When `--gtest_repeat` is set to a negative value, GoogleTest automatically forces environment recreation regardless of the explicit flag setting. As implemented in the `UnitTest::Run()` method, the boolean `recreate_environments_when_repeating` is OR'd with `gtest_repeat_forever`, ensuring that `SetUp()` and `TearDown()` execute every iteration during infinite loops to prevent resource leaks. ### What's the performance impact of recreating environments between repeats? Recreating environments significantly increases test execution time because `SetUp()` and `TearDown()` run every iteration rather than just at the boundaries. This trade-off sacrifices speed for isolation, making it suitable for debugging flaky tests but inefficient for routine CI pipelines. The default `false` setting maintains environments across repeats specifically to avoid this overhead during stability testing. ### Can I set the repeat count via environment variables instead of command line? Yes, GoogleTest supports environment variable configuration using the names `GTEST_REPEAT` and `GTEST_RECREATE_ENVIRONMENTS_WHEN_REPEATING`. These are read during flag initialization in `googletest/src/gtest.cc` via `Int32FromGTestEnv` and `BoolFromGTestEnv`, allowing configuration in containerized environments or CI systems where modifying command-line arguments is difficult.