# How to Break into the Debugger on a Test Failure in GoogleTest: Complete Configuration Guide

> Learn how to break into the debugger on a GoogleTest failure. Configure GoogleTest to pause execution at the exact moment an assertion fails for efficient debugging.

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

---

**Use the `--gtest_break_on_failure` command-line flag or programmatically set `::testing::GTEST_FLAG_SET(break_on_failure, true)` to force GoogleTest to trigger a platform-specific breakpoint immediately when any test assertion fails.**

When debugging test failures in the `google/googletest` framework, manually setting breakpoints before every assertion is impractical. GoogleTest provides a built-in mechanism to **break into the debugger on a test failure** automatically, controlled by the `break_on_failure` flag declared in [`include/gtest/gtest.h`](https://github.com/google/googletest/blob/main/include/gtest/gtest.h). This feature integrates with platform-specific debugging APIs to halt execution exactly where an expectation fails.

## How the `break_on_failure` Flag Works

### Flag Declaration and Default Behavior

The `break_on_failure` flag is declared in [`include/gtest/gtest.h`](https://github.com/google/googletest/blob/main/include/gtest/gtest.h) (around lines 85-86) and defaults to `false`. When enabled, it instructs the test framework to invoke a breakpoint trap instead of simply reporting the failure and continuing. You can access the flag at runtime using `GTEST_FLAG_GET(break_on_failure)` or modify it with `GTEST_FLAG_SET(break_on_failure, true)`.

### Core Failure Handling Logic

When a test reports a failure, the `TestPartResult` class processes the result in `src/gtest.cc`. The framework checks this flag at runtime before deciding how to handle the error:

```cpp
if (GTEST_FLAG_GET(break_on_failure)) {
    // platform-specific break-into-debugger code
} else if (GTEST_FLAG_GET(throw_on_failure)) {
    // Alternative error handling
}

```

This logic appears in `src/gtest.cc` around lines 5496-5505. Notably, if both `break_on_failure` and `throw_on_failure` are enabled, the break flag takes precedence, ensuring the debugger intercepts the failure before any exception handling occurs.

## Platform-Specific Breakpoint Implementation

The actual breakpoint mechanism varies by operating system and compiler, as implemented in `src/gtest.cc` (lines 5501-5522):

- **Windows**: Calls the `DebugBreak()` Win32 API
- **x86 Linux/macOS with GCC/Clang**: Executes inline assembly `asm("int3")`
- **Compilers supporting `__builtin_trap`**: Invokes the compiler intrinsic
- **POSIX systems**: Raises the `SIGTRAP` signal
- **Fallback mechanism**: Dereferences a volatile `nullptr` to generate a catchable crash if no other method is available

## Enabling Debugger Breaks in Practice

### Command-Line Usage

Launch your test binary under a debugger with the flag:

```bash
gdb --args ./my_test_binary --gtest_break_on_failure

# Inside gdb:

run

# Execution stops automatically at the failing assertion

```

For LLDB on macOS:

```bash
lldb ./my_test_binary -- --gtest_break_on_failure

```

### Programmatic Configuration

For test suites spawning child processes or requiring conditional debugging, set the flag in your `main()` function before calling `RUN_ALL_TESTS()`:

```cpp
#include "gtest/gtest.h"

int main(int argc, char **argv) {
  ::testing::InitGoogleTest(&argc, argv);
  // Force break-into-debugger on failures for the entire run
  ::testing::GTEST_FLAG_SET(break_on_failure, true);
  return RUN_ALL_TESTS();
}

```

### Combining with Exception Handling

To ensure breakpoints trigger even when GoogleTest catches exceptions:

```bash
gdb --args ./my_test_binary --gtest_catch_exceptions --gtest_break_on_failure

```

## Example Test Demonstrating the Breakpoint

This test automatically triggers a debugger stop when run with the flag:

```cpp
TEST(MySuite, FailsAndBreaks) {
  EXPECT_EQ(1, 2);  // With --gtest_break_on_failure, debugger stops here
  // When running under gdb or Visual Studio, inspect variables here
}

```

When executed under a debugger with `--gtest_break_on_failure`, execution halts at the `EXPECT_EQ` line, allowing immediate inspection of local variables and the call stack.

## Summary

- The `--gtest_break_on_failure` flag triggers automatic debugger breaks on assertion failures in `google/googletest`
- Set programmatically using `::testing::GTEST_FLAG_SET(break_on_failure, true)` when command-line access is limited
- Implementation uses `DebugBreak()` on Windows, `int3` assembly on x86, `__builtin_trap`, or `SIGTRAP` depending on the platform and compiler capabilities
- Takes precedence over `throw_on_failure` if both flags are set, as checked in `src/gtest.cc`
- Ideal for interactive debugging sessions under GDB, LLDB, Visual Studio, or other debuggers that handle platform exception signals

## Frequently Asked Questions

### Does `--gtest_break_on_failure` work with Visual Studio on Windows?

Yes. When running tests under the Visual Studio debugger, launch the test binary with `--gtest_break_on_failure` as a command argument or set the flag programmatically. According to the source code in `src/gtest.cc`, the framework calls `DebugBreak()` on Windows, which triggers the Visual Studio Just-In-Time debugger to stop execution at the exact line of the failed assertion in [`include/gtest/gtest.h`](https://github.com/google/googletest/blob/main/include/gtest/gtest.h) or your test file.

### What happens if I enable both `break_on_failure` and `throw_on_failure`?

When both flags are enabled, `break_on_failure` takes precedence. The framework checks for the break flag first in the failure handling logic within `src/gtest.cc` (around line 5496) and triggers the platform-specific breakpoint before evaluating the throw option. This precedence allows you to maintain `throw_on_failure` for automated CI builds while still getting interactive breakpoints during local debugging sessions.

### Can I enable this flag for specific test cases only?

There is no per-test switch for this global flag. However, you can programmatically toggle `::testing::GTEST_FLAG_SET(break_on_failure, true)` at runtime based on test names or environment variables. For selective debugging, run only specific tests using `--gtest_filter=TestSuite.TestName` combined with the break flag to limit which failures trigger debugger interruptions.

### Why does my test crash instead of breaking cleanly into the debugger?

If you see a segmentation fault or access violation instead of a clean breakpoint, your debugger may not be attached, or the platform-specific breakpoint method is unavailable. On POSIX systems without proper `SIGTRAP` handling, GoogleTest falls back to dereferencing a volatile null pointer (as seen in the fallback implementation in `src/gtest.cc`), which appears as a crash. Ensure you are running under an active debugger like GDB, LLDB, or Visual Studio that can catch these platform-specific trap signals.