# How GoogleTest Handles Stack Traces and the --gtest_stack_trace_depth Flag

> Learn how GoogleTest displays stack traces on assertion failures. Discover the --gtest_stack_trace_depth flag to control output depth and default behavior.

- Repository: [Google/googletest](https://github.com/google/googletest)
- Tags: internals
- Published: 2026-08-29

---

**GoogleTest prints the call stack when assertions fail, using the `--gtest_stack_trace_depth` flag (or `GTEST_STACK_TRACE_DEPTH` environment variable) to limit output to a specific number of frames, defaulting to 1.**

The `google/googletest` framework provides detailed diagnostics through **stack traces** that show the exact execution path leading to a test failure. Developers control the verbosity of this output via the **`--gtest_stack_trace_depth`** command-line flag, which interfaces with the platform-specific `OsStackTraceGetter` implementation to capture and truncate call stack frames according to the specified limit.

## Architecture of GoogleTest Stack Traces

GoogleTest implements stack trace generation through a layered architecture that separates flag management from OS-specific retrieval and depth enforcement.

### Flag Declaration and Parsing

The integer flag `stack_trace_depth` is declared in [`googletest/include/gtest/gtest.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest.h) at lines 151-153. At runtime, the parsing logic in `googletest/src/gtest.cc` (lines 6794-6847) processes the `--gtest_stack_trace_depth=N` argument or reads the `GTEST_STACK_TRACE_DEPTH` environment variable. The parsed value is stored internally and accessed via `GTEST_FLAG_GET(stack_trace_depth)`.

### OS-Specific Stack Retrieval

Raw stack frames are captured by **`OsStackTraceGetter::CurrentStackTrace`**, an abstract interface implemented for each supported platform. This method obtains the full call stack from the operating system before any filtering or truncation occurs.

### Depth Limiting and Frame Filtering

The method **`UnitTestImpl::CurrentOsStackTraceExceptTop(int skip_count)`** in `googletest/src/gtest.cc` (lines 1200-1215) enforces the depth constraint. It passes the flag value to the OS getter and applies the `skip_count` argument (typically `skip_count + 1`) to remove GoogleTest's internal helper frames. The final output contains at most `stack_trace_depth` frames minus the skipped internal entries.

## Configuring Stack Trace Output

GoogleTest supports multiple configuration mechanisms for stack trace depth, allowing flexibility across different development environments.

### Command-Line Usage

Pass the flag directly when executing your test binary to override the default depth of 1:

```bash
./my_test --gtest_stack_trace_depth=5

```

### Environment Variable Alternative

Set the `GTEST_STACK_TRACE_DEPTH` environment variable before running tests:

```bash
export GTEST_STACK_TRACE_DEPTH=5
./my_test

```

### Programmatic Control

Set defaults in C++ code before initializing the framework. This approach requires including the internal flag helpers from [`googletest/src/gtest-internal-inl.h`](https://github.com/google/googletest/blob/main/googletest/src/gtest-internal-inl.h):

```cpp
int main(int argc, char **argv) {
  ::testing::GTEST_FLAG_SET(stack_trace_depth, 10);
  ::testing::GTEST_FLAG_SET(show_internal_stack_frames, true);
  ::testing::InitGoogleTest(&argc, argv);
  return RUN_ALL_TESTS();
}

```

## Filtering Internal Frames

Beyond depth control, GoogleTest provides **`--gtest_show_internal_stack_frames`**, declared in [`googletest/include/gtest/gtest.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest.h) (lines 144-147). This boolean flag determines whether GoogleTest's own helper functions appear in the trace. By default, internal frames are hidden to emphasize user code.

To display only user frames with a specific depth:

```bash
./my_test --gtest_stack_trace_depth=3 --gtest_show_internal_stack_frames=0

```

## Practical Example

Consider a test with nested function calls:

```cpp
void helper() {
  EXPECT_EQ(1, 2);  // Line 3
}

TEST(StackTraceDemo, DeepFailure) {
  helper();  // Line 7
}

```

Running with default settings shows only line 3. With `--gtest_stack_trace_depth=5`, the output includes the call chain from `main()` through `RUN_ALL_TESTS()` to the specific assertion, depending on the `skip_count` calculation.

## Summary

- GoogleTest captures stack traces via **`OsStackTraceGetter`** and limits them using **`--gtest_stack_trace_depth`**, defaulting to **1 frame**.
- The **`CurrentOsStackTraceExceptTop`** method in `googletest/src/gtest.cc` applies depth limits and skips internal frames based on the `skip_count` parameter.
- Configure depth via command line, `GTEST_STACK_TRACE_DEPTH` environment variable, or **`GTEST_FLAG_SET`** macros.
- Use **`--gtest_show_internal_stack_frames`** to toggle visibility of GoogleTest's internal helper functions.
- All flag declarations reside in [`googletest/include/gtest/gtest.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest.h), while implementation logic is in `googletest/src/gtest.cc`.

## Frequently Asked Questions

### What is the default stack trace depth in GoogleTest?

GoogleTest defaults to **1 frame**, meaning only the line containing the failed assertion is displayed. This minimizes output noise for simple test failures while allowing developers to increase verbosity when debugging complex call chains.

### How do I show more frames in my GoogleTest stack trace?

Increase the depth using `--gtest_stack_trace_depth=N` where N is the desired number of frames. For example, `--gtest_stack_trace_depth=10` displays up to ten call stack frames, helping you trace the execution path through multiple function calls.

### Can I hide GoogleTest's internal functions from the stack trace?

Yes. Set `--gtest_show_internal_stack_frames=0` or use `::testing::GTEST_FLAG_SET(show_internal_stack_frames, false)` in your `main()` function. This flag removes framework helper functions from the output, keeping only your test and application code visible.

### Why does my stack trace show fewer frames than specified?

The `skip_count` parameter passed to `CurrentOsStackTraceExceptTop` automatically removes internal GoogleTest frames from the count. If you set depth to 3 and GoogleTest determines it must skip 2 internal frames, only 1 user frame remains visible in the final output.