# How to Configure Catch2 to Abort Tests on First Failure

> Learn how to configure Catch2 to abort tests on first failure using the -a command-line option. Stop your test runs instantly after the first failed assertion for faster debugging.

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

---

**Use the `-a` or `--abort` command-line option to stop the entire test run immediately after the first failed assertion, or `-x <N>`/`--abortx <N>` to halt after N total assertion failures.**

Catch2 provides granular control over test execution failure behavior through command-line configuration options. While `REQUIRE` assertions automatically abort individual test cases by default, the framework continues executing subsequent test cases unless configured otherwise. According to the Catch2 source code, you can enable global abort behavior that terminates the entire test suite when specific failure thresholds are met.

## Default Failure Behavior in Catch2

By default, Catch2 distinguishes between two assertion macros with different failure semantics. A **`REQUIRE`** assertion failure immediately stops the current test case and marks it as failed, but the test runner proceeds to execute the next test case in the queue. In contrast, a **`CHECK`** assertion failure logs the error while allowing the current test case to continue executing. Neither behavior stops the overall test run automatically.

## Command-Line Options to Abort on First Failure

Catch2 exposes global abort functionality through CLI options parsed in [`src/catch2/cli/commandline.cpp`](https://github.com/catchorg/Catch2/blob/main/src/catch2/cli/commandline.cpp). These options populate the `ConfigData::abortAfter` member defined in [`include/catch2/catch.hpp`](https://github.com/catchorg/Catch2/blob/main/include/catch2/catch.hpp), which the test runner evaluates after each failed assertion in [`src/catch2/reporters/catch_reporter.cpp`](https://github.com/catchorg/Catch2/blob/main/src/catch2/reporters/catch_reporter.cpp).

### Abort Immediately on First Failure (-a / --abort)

The **`-a`** or **`--abort`** flag configures Catch2 to terminate the entire test run upon encountering the first failed assertion of any kind. This applies to both `REQUIRE` and `CHECK` failures, overriding the default behavior where only the individual test case aborts.

```bash
./my_tests --abort
./my_tests -a

```

### Abort After N Failures (-x / --abortx <N>)

The **`-x <N>`** or **`--abortx <N>`** flag configures Catch2 to stop the test run after **N** total assertion failures. This threshold counts failures across all assertion types and test cases. For example, `-x 3` stops execution immediately upon the third failed assertion.

```bash
./my_tests -x 3
./my_tests --abortx 5

```

## Implementation Details in the Catch2 Codebase

The abort-on-failure feature is documented in **[`docs/command-line.md`](https://github.com/catchorg/Catch2/blob/main/docs/command-line.md)** under the *Aborting after a certain number of failures* section and implemented across three key source files. The configuration structure in **[`include/catch2/catch.hpp`](https://github.com/catchorg/Catch2/blob/main/include/catch2/catch.hpp)** defines `ConfigData::abortAfter` to store the failure threshold. Argument parsing logic in **[`src/catch2/cli/commandline.cpp`](https://github.com/catchorg/Catch2/blob/main/src/catch2/cli/commandline.cpp)** processes the `-a` and `-x` flags to set this value. The assertion handling logic in **[`src/catch2/reporters/catch_reporter.cpp`](https://github.com/catchorg/Catch2/blob/main/src/catch2/reporters/catch_reporter.cpp)** checks the accumulated failure count against `ConfigData::abortAfter` after each failed assertion and terminates the run when the limit is reached.

## Practical Usage Examples

When combined with test cases using different assertion types, these flags provide precise control over failure handling:

```cpp
TEST_CASE("validation checks") {
    CHECK( false );          // Failure #1 - test continues by default
    CHECK( false );          // Failure #2 - test continues
    // With `-x 2`, the runner aborts here before the next test case
}

TEST_CASE("critical requirement") {
    REQUIRE( false );        // Fails and aborts this test case instantly
    // With `-a`, the entire run stops here with no further tests executed
}

```

Execute with abort flags:

```bash

# Stop on first CHECK or REQUIRE failure anywhere in the suite

./test_executable -a

# Stop after accumulating three total failures across all tests

./test_executable --abortx 3

```

## Summary

- **Default behavior**: `REQUIRE` aborts individual test cases while the test run continues; `CHECK` failures never stop execution.
- **`-a` / `--abort`**: Stops the entire test run after the first failed assertion of any type.
- **`-x N` / `--abortx N`**: Stops the run after **N** total assertion failures.
- **Source implementation**: Controlled via `ConfigData::abortAfter` in [`include/catch2/catch.hpp`](https://github.com/catchorg/Catch2/blob/main/include/catch2/catch.hpp), parsed in [`src/catch2/cli/commandline.cpp`](https://github.com/catchorg/Catch2/blob/main/src/catch2/cli/commandline.cpp), and enforced in [`src/catch2/reporters/catch_reporter.cpp`](https://github.com/catchorg/Catch2/blob/main/src/catch2/reporters/catch_reporter.cpp).

## Frequently Asked Questions

### What is the difference between REQUIRE aborting a test case and the -a flag?

When a `REQUIRE` assertion fails, Catch2 aborts execution of the current test case and proceeds to the next one. The `-a` flag extends this behavior to abort the entire test run, preventing any subsequent test cases from executing after the first failure of any kind.

### Can I configure abort-on-failure behavior programmatically instead of via CLI?

According to the Catch2 source, the `ConfigData` struct in [`include/catch2/catch.hpp`](https://github.com/catchorg/Catch2/blob/main/include/catch2/catch.hpp) contains the `abortAfter` member that controls this threshold. While the command-line interface in [`src/catch2/cli/commandline.cpp`](https://github.com/catchorg/Catch2/blob/main/src/catch2/cli/commandline.cpp) provides the standard mechanism for configuration, advanced users can set `ConfigData::abortAfter` programmatically when constructing custom test configurations, though command-line flags remain the documented approach.

### Does the abort option count CHECK failures or only REQUIRE failures?

Both `-a` and `-x` count **all** assertion failures. This includes `CHECK` failures, which normally allow the test to continue, and `REQUIRE` failures, which normally abort the test case. The abort threshold applies to the total accumulated count regardless of which macro generated the failure.

### How does --abortx interact with multiple test cases?

The `-x` flag maintains a global counter of assertion failures across all executed test cases. If you specify `-x 3` and the first test case contains two `CHECK` failures while the second test case contains one, Catch2 aborts immediately upon the third failure without completing the remainder of the second test case or executing any subsequent tests.