# How to Repeat Tests Multiple Times in GoogleTest: Command-Line Flags and Environment Variables

> Repeat GoogleTest tests multiple times using command-line flags like --gtest_repeat=N or the GTEST_REPEAT environment variable. Learn how to manage test environments during repetition.

- Repository: [Google/googletest](https://github.com/google/googletest)
- Tags: how-to-guide
- Published: 2026-08-31

---

**Use the `--gtest_repeat=N` command-line flag or the `GTEST_REPEAT` environment variable to execute GoogleTest suites multiple times, and control global setup/teardown behavior with `--gtest_recreate_environments_when_repeating`.**

The `google/googletest` framework provides built-in mechanisms to repeat tests multiple times for detecting flaky tests, stress-testing code, or benchmarking performance. This functionality is implemented directly in the core runtime and requires no changes to test code to enable basic repetition.

## Understanding GoogleTest's Test Repetition Flags

GoogleTest implements test repetition through command-line flags defined in `googletest/src/gtest.cc`. The system wraps the standard test execution loop with a repetition controller that manages multiple iterations while preserving all event notifications and listener callbacks.

### The `--gtest_repeat` Flag and `GTEST_REPEAT` Environment Variable

The primary control for repetition is the **`--gtest_repeat`** flag (lines 363-368 in `googletest/src/gtest.cc`). This flag accepts integer values with specific semantics:

- **Positive integer `N`**: Runs the entire test suite exactly `N` times.
- **`-1` (or any negative value)**: Repeats the test suite indefinitely until manually terminated (useful for long-running stress tests).
- **`0`**: Disables test execution entirely.

Alternatively, you can set the **`GTEST_REPEAT`** environment variable to achieve the same effect without modifying command-line arguments.

### TestEventRepeater and Event Forwarding

The internal **`TestEventRepeater`** class (implemented around lines 2897-2952 in `googletest/src/gtest.cc`) wraps the normal test event listener interface. This repeater forwards every event—test start/end, suite start/end, and iteration boundaries—to registered listeners for each repetition cycle. This ensures that output formats and custom listeners behave identically across all iterations, with the current iteration index included in log output.

### Environment Recreation Control

The **`--gtest_recreate_environments_when_repeating`** flag (lines 6042-6070 in `googletest/src/gtest.cc`) determines how global test environments (instances of `::testing::Environment`) behave during repetitions:

- **Default (`false`)**: Environments are set up once before the first iteration and torn down once after the final iteration, minimizing overhead for simple repetition scenarios.
- **When set to `true`**: Environments are recreated on every iteration, providing complete isolation between repetitions at the cost of additional setup time.

Setting this flag to `true` is automatically enforced when using negative repeat counts (infinite loops) to prevent resource exhaustion from accumulating across unlimited iterations.

## How the Repeat Loop Works

The main test execution loop in `gtest.cc` implements repetition through a straightforward iterative structure. The framework retrieves the repeat count via `GTEST_FLAG_GET(repeat)` and enters a loop that continues while `repeat_forever` is true or the iteration counter has not reached the target count.

Inside the loop, the `TestEventRepeater` invokes `OnTestIterationStart()` and `OnTestIterationEnd()` to bracket each cycle. Environment setup occurs on the first iteration or when recreation is enabled, while teardown occurs on the final iteration or when recreation is enabled. The actual test execution happens via `RunAllTests()` within this controlled lifecycle.

## Practical Examples for Repeating Tests

### Running Tests from the Command Line

Execute your test binary with the repeat flag to run specific iterations:

```bash

# Run the entire suite 50 times

./my_test_binary --gtest_repeat=50

# Run indefinitely ( Ctrl+C to stop )

./my_test_binary --gtest_repeat=-1

# Repeat only a specific test suite with environment recreation

./my_test_binary --gtest_repeat=30 --gtest_filter=MySuite.* --gtest_recreate_environments_when_repeating=true

```

### Using Environment Variables

Set `GTEST_REPEAT` before invoking the binary for CI/CD pipelines where command-line modification is difficult:

```bash
export GTEST_REPEAT=100
./my_test_binary

```

This produces identical behavior to passing `--gtest_repeat=100` directly.

### Accessing Iteration Indices in Test Code

While GoogleTest does not automatically inject iteration counts into test functions, you can retrieve the current iteration through the `UnitTest` singleton (available since version 1.13):

```cpp
#include <gtest/gtest.h>
#include <iostream>

TEST(MySuite, FlakyTest) {
  const int iteration = ::testing::UnitTest::GetInstance()
                           ->current_test_info()
                           ->iteration();
  
  std::cout << "Executing iteration " << iteration << std::endl;
  
  // Use iteration index for conditional logic or logging
  EXPECT_EQ(iteration >= 0, true);  // Always true, but shows usage
}

```

The `iteration()` accessor returns the zero-based index of the current repetition cycle.

### Measuring Per-Iteration Performance with Custom Listeners

Create a custom event listener to benchmark each repetition using the `TestEventRepeater` framework:

```cpp
#include <gtest/gtest.h>
#include <chrono>
#include <iostream>

class TimingListener : public ::testing::EmptyTestEventListener {
 public:
  void OnTestIterationStart(const ::testing::UnitTest&, int iteration) override {
    start_ = std::chrono::steady_clock::now();
    std::cout << "=== Starting iteration " << iteration << " ===" << std::endl;
  }

  void OnTestIterationEnd(const ::testing::UnitTest&, int) override {
    auto duration = std::chrono::steady_clock::now() - start_;
    auto ms = std::chrono::duration_cast<std::chrono::milliseconds>(duration).count();
    std::cout << "=== Iteration elapsed: " << ms << " ms ===" << std::endl;
  }

 private:
  std::chrono::steady_clock::time_point start_;
};

int main(int argc, char** argv) {
  ::testing::InitGoogleTest(&argc, argv);
  ::testing::TestEventListeners& listeners =
      ::testing::UnitTest::GetInstance()->listeners();
  listeners.Append(new TimingListener);
  return RUN_ALL_TESTS();
}

```

When run with `--gtest_repeat=5`, this outputs timing data for each of the five iterations, leveraging the same event forwarding mechanism used internally by `TestEventRepeater`.

## Key Source Files in google/googletest

Understanding the implementation requires examining these specific files in the repository:

- **`googletest/src/gtest.cc`**: Contains the core repetition logic, flag definitions (lines 363-368), `TestEventRepeater` implementation (lines 2897-2952), and environment recreation controls (lines 6042-6070).
- **`googletest/src/gtest-port.cc`**: Provides platform-agnostic utilities supporting the flag parsing infrastructure.
- **[`googletest/docs/advanced.md`](https://github.com/google/googletest/blob/main/googletest/docs/advanced.md)**: Official documentation covering repetition flags and best practices.
- **[`googletest/docs/reference/testing.md`](https://github.com/google/googletest/blob/main/googletest/docs/reference/testing.md)**: Complete reference for command-line flags including `--gtest_repeat`.

## Summary

- **Use `--gtest_repeat=N`** to run tests multiple times, or `--gtest_repeat=-1` for infinite repetition.
- **Set `GTEST_REPEAT`** as an environment variable when command-line flags are impractical.
- **Control environment lifecycle** with `--gtest_recreate_environments_when_repeating` to either preserve global state across iterations or isolate each repetition.
- **Access iteration indices** programmatically via `::testing::UnitTest::GetInstance()->current_test_info()->iteration()` for conditional test logic.
- **Implement custom listeners** by extending `EmptyTestEventListener` to capture per-iteration metrics while the `TestEventRepeater` handles event distribution.

## Frequently Asked Questions

### What is the difference between `--gtest_repeat` and `--gtest_recreate_environments_when_repeating`?

The **`--gtest_repeat`** flag controls how many times the test suite executes, while **`--gtest_recreate_environments_when_repeating`** controls whether global `::testing::Environment` objects are torn down and rebuilt between iterations. By default, environments persist across repetitions for efficiency, but setting the recreation flag to `true` provides clean isolation for each iteration.

### How do I run GoogleTest forever for stress testing?

Pass **`-1`** (or any negative number) to the `--gtest_repeat` flag: `./test_binary --gtest_repeat=-1`. The test suite will execute indefinitely until you manually terminate the process, and GoogleTest automatically enables environment recreation to prevent resource exhaustion during long-running stress tests.

### Can I determine which iteration is currently running inside my test code?

Yes, though it requires accessing the `UnitTest` singleton. Call `::testing::UnitTest::GetInstance()->current_test_info()->iteration()` to retrieve the zero-based iteration index. This functionality was introduced in GoogleTest version 1.13 and is useful for logging or conditional logic during flaky test investigation.

### Why would I repeat tests multiple times if they pass on the first run?

Repeating tests is essential for detecting **flaky tests**—tests that pass or fail inconsistently due to race conditions, timing issues, or state pollution. Running a suite thousands of times (`--gtest_repeat=10000`) helps identify intermittent failures that would otherwise go unnoticed in single-run CI/CD pipelines.