# How to Configure Debug Break on Failure and Abort Settings in Catch2

> Learn to configure debug break on failure and abort settings in Catch2. Halt test execution on assertion errors for efficient debugging with the -b, -a, and -x flags.

- Repository: [Catch Org/Catch2](https://github.com/catchorg/Catch2)
- Tags: how-to-guide
- Published: 2026-07-29

---

**Catch2 provides orthogonal mechanisms to automatically break into a debugger on assertion failures using the `-b/--break` flag and to terminate test runs after a configurable number of failures using `-a/--abort` or `-x/--abortx`.**

When debugging test failures in the Catch2 framework, developers often need precise control over execution flow. Learning how to configure debug break on failure and abort settings in Catch2 allows you to automatically pause execution in attached debuggers and limit the scope of failing test runs. These settings can be controlled via command-line flags, compile-time macros, or programmatic configuration through the `Catch::Session` API.

## Enabling Debug Break on Failure

The **debug break on failure** feature interrupts test execution and transfers control to an attached debugger whenever an assertion fails.

### Platform-Specific Implementation

In [`src/catch2/internal/catch_debugger.hpp`](https://github.com/catchorg/Catch2/blob/main/src/catch2/internal/catch_debugger.hpp), the `CATCH_BREAK_INTO_DEBUGGER()` macro expands to a lambda that checks `Catch::isDebuggerActive()` and, if true, invokes the platform-specific `CATCH_TRAP()` implementation. On MSVC this translates to `__debugbreak()`, while on Linux it uses `raise(SIGTRAP)`. This macro is injected at every failure handling path within the assertion machinery.

### Command-Line Activation

To enable automatic debugger breaks without modifying source code, pass the `-b` or `--break` flag when running your test executable:

```bash
./tests -b

```

This activates the default `CATCH_BREAK_INTO_DEBUGGER()` behavior, causing the process to trap into the debugger only if one is currently attached.

### Compile-Time Customization

You can override the default break behavior by defining your own `CATCH_BREAK_INTO_DEBUGGER()` macro before including any Catch2 headers. This is useful for adding logging or custom breakpoint logic:

```cpp
// Define custom break behavior before including Catch2
#define CATCH_BREAK_INTO_DEBUGGER() []{ \
    if (Catch::isDebuggerActive()) { \
        std::cerr << "Breaking into debugger..." << std::endl; \
        CATCH_TRAP(); \
    } \
}()

#include <catch2/catch_test_macros.hpp>

```

This customization is documented in the configuration section covering compile-time overrides for debug break behavior.

## Configuring Abort After Failures

The **abort after failures** mechanism stops the entire test run once a specified failure threshold is reached, which is distinct from the per-test-case abort behavior of `REQUIRE` versus `CHECK`.

### Immediate Abort on First Failure

Use the `-a` or `--abort` flag to terminate the test run immediately after the first failed assertion of any kind:

```bash
./tests --abort

```

### Threshold-Based Abort

To abort after a specific number of failures rather than immediately, use the `-x` or `--abortx` flag followed by the number:

```bash

# Abort after 5 assertion failures (including both CHECK and REQUIRE)

./tests --abortx 5

```

These flags hook into the test runner's failure counting logic in [`src/catch2/catch_session.hpp`](https://github.com/catchorg/Catch2/blob/main/src/catch2/catch_session.hpp), causing an early exit once the threshold is reached.

### Programmatic Configuration

When embedding Catch2 and constructing a custom main function, configure abort thresholds via `Catch::Session`:

```cpp
#include <catch2/catch_session.hpp>

int main(int argc, char* argv[]) {
    Catch::Session session;
    // Abort after 3 failures (equivalent to `-x 3`)
    session.configData().abortAfter = 3;
    return session.run(argc, argv);
}

```

The `abortAfter` field is part of `Catch::ConfigData` and controls when the test runner terminates based on accumulated assertion failures.

## Key Implementation Files

Understanding where these features reside helps with advanced customization:

- **[`src/catch2/internal/catch_debugger.hpp`](https://github.com/catchorg/Catch2/blob/main/src/catch2/internal/catch_debugger.hpp)** – Contains the platform-specific trap definitions (`CATCH_TRAP`) and the `CATCH_BREAK_INTO_DEBUGGER` macro used at every assertion failure point.
- **[`src/catch2/catch_session.hpp`](https://github.com/catchorg/Catch2/blob/main/src/catch2/catch_session.hpp)** – Parses command-line options (`-b`, `-a`, `-x`) and stores configuration in `Catch::ConfigData`.
- **[`docs/command-line.md`](https://github.com/catchorg/Catch2/blob/main/docs/command-line.md)** – Documents the `-b/--break`, `-a/--abort`, and `-x/--abortx` command-line options.
- **[`docs/configuration.md`](https://github.com/catchorg/Catch2/blob/main/docs/configuration.md)** – Describes compile-time overrides for the debug break macro.

## Summary

- **Debug break on failure** is controlled by the `CATCH_BREAK_INTO_DEBUGGER()` macro in [`catch_debugger.hpp`](https://github.com/catchorg/Catch2/blob/main/catch_debugger.hpp), activated via `-b/--break` or customized at compile time.
- **Abort settings** terminate the test run after specified failure counts, configured via `-a/--abort` (immediate) or `-x/--abortx N` (threshold).
- **Programmatic control** is available through `Catch::Session.configData().abortAfter` for embedded framework usage.
- These mechanisms operate independently—break actions pause for debugging while abort actions terminate execution based on failure counts.

## Frequently Asked Questions

### How do I disable the debug break feature entirely?

Define `CATCH_BREAK_INTO_DEBUGGER()` as an empty macro before including Catch2 headers. This prevents the automatic debugger break logic from compiling into your binary, effectively disabling the feature regardless of command-line flags.

### What is the difference between CHECK and REQUIRE failures regarding abort settings?

`CHECK` failures increment the failure counter and continue test execution, while `REQUIRE` failures throw an exception that aborts the current test case immediately. However, the `-a/--abort` and `-x/--abortx` flags apply to the cumulative failure count across the entire test run, affecting both assertion types when calculating whether to stop execution.

### Can I combine debug break and abort settings in the same test run?

Yes, these settings are orthogonal. You can use `./tests -b -x 5` to break into the debugger on each failure while also ensuring the test run terminates after 5 total failures. The debugger break occurs before the abort check, allowing you to inspect the failure before the process exits.

### Why does the debugger break not work when running tests in CI environments?

The `CATCH_BREAK_INTO_DEBUGGER()` macro checks `Catch::isDebuggerActive()` before invoking the platform trap. In CI environments without an attached debugger, this check returns false, allowing tests to continue normally. Ensure you have an actual debugger attached (not just running in debug build configuration) for the break to trigger.