# How to Configure Output Coloring and Formatting in Catch2

> Learn to configure Catch2 output coloring and formatting using compile-time macros and runtime flags for custom terminal output and improved CI integration. Master your test results display.

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

---

**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`](https://github.com/catchorg/Catch2/blob/main/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.

```cpp
// 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.

```cpp
// 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`](https://github.com/catchorg/Catch2/blob/main/docs/configuration.md). This setting affects how the console reporter formats long assertion messages and test descriptions.

```cpp
// 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`](https://github.com/catchorg/Catch2/blob/main/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`](https://github.com/catchorg/Catch2/blob/main/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)

```bash

# 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`](https://github.com/catchorg/Catch2/blob/main/src/catch2/reporters/catch_reporter_registrars.cpp).

```bash

# 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`](https://github.com/catchorg/Catch2/blob/main/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:

```cpp
#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`](https://github.com/catchorg/Catch2/blob/main/catch_console_colour.hpp).
- **Customization**: Include [`catch_console_colour.hpp`](https://github.com/catchorg/Catch2/blob/main/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`](https://github.com/catchorg/Catch2/blob/main/catch_reporter_console.cpp) wraps long lines.

### Can I use custom colors in my test output?

Yes. Include [`catch2/internal/catch_console_colour.hpp`](https://github.com/catchorg/Catch2/blob/main/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.