How to Configure Catch2 to Abort Tests on First Failure

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. These options populate the ConfigData::abortAfter member defined in include/catch2/catch.hpp, which the test runner evaluates after each failed assertion in 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.

./my_tests --abort
./my_tests -a

Abort After N Failures (-x / --abortx )

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.

./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 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 defines ConfigData::abortAfter to store the failure threshold. Argument parsing logic in 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 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:

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:

# 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, parsed in src/catch2/cli/commandline.cpp, and enforced in 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 contains the abortAfter member that controls this threshold. While the command-line interface in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}