How to Configure Output Coloring and Formatting in Catch2

Catch2 enables precise control over terminal colors and text layout through compile-time macros like CATCH_CONFIG_COLOUR_WIN32 and runtime flags such as --colour and --reporter, allowing you to customize output for both local development and CI environments.

The catchorg/Catch2 testing framework provides multiple mechanisms to configure output coloring and formatting without modifying core library code. You can enforce specific color implementations at compile time using preprocessor definitions or adjust display settings dynamically via command-line arguments parsed in src/catch2/internal/catch_reporter_spec_parser.hpp. These options ensure test results remain readable across diverse platforms, from standard Windows consoles to POSIX terminals and automated build logs.

Compile-Time Configuration with Macros

Define configuration macros before including any Catch2 header to establish default behavior during compilation. These settings determine the initial state of color engines and console dimensions.

Forcing Win32 Color Implementation

On Windows, Catch2 automatically detects support for ANSI escape codes. To override this detection and force the legacy Win32 Console API, define CATCH_CONFIG_COLOUR_WIN32. Conversely, use CATCH_CONFIG_NO_COLOUR_WIN32 to disable the Win32 implementation and favor ANSI codes.

// Force Win32 API color handling (Windows only)
#define CATCH_CONFIG_COLOUR_WIN32
#include <catch2/catch_test_macros.hpp>

Disabling Colors Entirely

To produce plain text output without color codes on any platform, define CATCH_CONFIG_NO_COLOUR before including Catch2 headers. This macro disables all color infrastructure regardless of terminal capabilities.

// Disable all color output globally
#define CATCH_CONFIG_NO_COLOUR
#include <catch2/catch_test_macros.hpp>

Adjusting Console Width

Control text wrapping by defining CATCH_CONFIG_CONSOLE_WIDTH with your desired column limit. The default value is 80 characters, as specified in docs/configuration.md. This setting affects how the console reporter formats long assertion messages and test descriptions.

// Wrap text at 120 columns instead of 80
#define CATCH_CONFIG_CONSOLE_WIDTH 120
#include <catch2/catch_test_macros.hpp>

Runtime Configuration via Command Line

Override compile-time defaults without rebuilding by passing flags to your test executable. The parser in src/catch2/internal/catch_reporter_spec_parser.hpp processes these options and stores values in the ConfigData structure.

The --colour Flag and ColourMode

Use the --colour option (or -colour shorthand) to dynamically control color output. This flag accepts three values mapped to the ColourMode enum defined in src/catch2/internal/catch_console_colour.hpp:

• yes: Force colors on regardless of terminal detection
• no: Force colors off entirely
• auto: Automatically detect terminal capabilities (default)

# Force color output even when piping to a file

./tests --colour=yes

# Disable colors for CI logs

./tests --colour=no

# Default automatic detection

./tests --colour=auto

The parser converts the string argument to a ColourMode value via stringToColourMode() and stores it in m_colourMode.

Selecting Reporters for Layout Control

Change formatting styles while respecting color settings by specifying a reporter with --reporter. Available options include console, compact, and xml, registered in src/catch2/reporters/catch_reporter_registrars.cpp.

# Use compact reporter with forced colors

./tests --reporter compact --colour=yes

Each reporter derives from a common base class that initializes a platform-specific ColourImpl object based on the selected ColourMode.

Internal Architecture of Color Output

Understanding the implementation details in src/catch2/internal/catch_console_colour.hpp helps when debugging display issues or extending functionality.

Platform Abstraction with ColourImpl

The makeColourImpl(colourSelection, stream) function instantiates the appropriate color engine:

• ANSI implementation: Uses escape codes on POSIX systems and modern Windows terminals
• Win32 implementation: Calls Console API functions on legacy Windows systems

The selected implementation is stored as a unique pointer (m_colour) within the reporter base class.

RAII Color Guards

When writing colored text, reporters call m_colour->guardColour(colourCode), which returns a ColourGuard object. This RAII guard injects color codes when streamed to std::ostream and automatically restores the original terminal color upon destruction, preventing color state leakage between output operations.

Implementing Custom Colored Output

Access Catch2's color infrastructure directly within test cases for custom messaging:

#include <catch2/catch_test_macros.hpp>
#include <catch2/internal/catch_console_colour.hpp>

TEST_CASE("Custom colored warning output") {
    auto& output_stream = Catch::cout();
    auto color_impl = Catch::makeColourImpl(
        Catch::ColourMode::PlatformDefault, 
        &output_stream
    );
    
    // Create a guard for bright yellow text
    auto guard = color_impl->guardColour(Catch::Colour::BrightYellow);
    output_stream << guard << "Warning: Critical test condition detected" << std::endl;
}

This pattern uses the same ColourGuard mechanism employed by built-in reporters, ensuring consistent behavior across platforms.

Summary

• Compile-time macros: Use CATCH_CONFIG_COLOUR_WIN32 to force Windows API colors, CATCH_CONFIG_NO_COLOUR to disable all colors, and CATCH_CONFIG_CONSOLE_WIDTH to set text wrapping limits.
• Runtime flags: Pass --colour=yes|no|auto to override color detection and --reporter=<name> to select formatting styles.
• Architecture: The ColourMode enum drives ColourImpl platform abstraction, while ColourGuard provides RAII-based color management in catch_console_colour.hpp.
• Customization: Include catch_console_colour.hpp to use makeColourImpl() and guardColour() for custom colored output within tests.

Frequently Asked Questions

How do I completely disable color output in Catch2?

Define the CATCH_CONFIG_NO_COLOUR macro before including Catch2 headers to compile a test executable that never emits color codes. Alternatively, run any Catch2 executable with the --colour=no flag to disable colors at runtime without recompiling.

What is the default console width in Catch2?

The default console width is 80 characters. You can change this at compile time by defining CATCH_CONFIG_CONSOLE_WIDTH to your preferred column count, which affects how the console reporter in catch_reporter_console.cpp wraps long lines.

Can I use custom colors in my test output?

Yes. Include catch2/internal/catch_console_colour.hpp and use Catch::makeColourImpl() to obtain a color implementation. Call guardColour() with values from the Catch::Colour enum (such as Red, BrightGreen, or Cyan) to create a guard object that applies the color when streamed to Catch::cout().

How does Catch2 handle color output on Windows?

Catch2 attempts to detect Windows 10's support for ANSI escape codes automatically. If you need to force the legacy Win32 Console API (or explicitly disable it in favor of ANSI), use the CATCH_CONFIG_COLOUR_WIN32 or CATCH_CONFIG_NO_COLOUR_WIN32 macros before including the Catch2 header.

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