How to Configure Verbosity, Output Streams, and Color Modes in Catch2

You configure Catch2’s output behavior through global command-line flags for verbosity and colour modes, while per-reporter settings—including output file redirection—are specified via the ::out= and ::colour-mode= syntax in reporter specifications.

The catchorg/Catch2 testing framework separates output control into global configuration values stored in the Config class and per-reporter overrides defined in ProcessedReporterSpec objects. Understanding how to configure verbosity, output streams, and color modes in Catch2 requires examining the IConfig interface declaration, the command-line parser implementation, and the reporter specification builder.

Configuration Architecture

Catch2 defines two primary output control mechanisms in src/catch2/interfaces/catch_interfaces_config.hpp: verbosity determines detail levels, while colour mode selects the coloring implementation.

Verbosity Levels

The enum class Verbosity at lines 20-24 declares three levels that control how much detail reporters emit:

• quiet — Shows only failures and summary statistics
• normal — Standard test results with failure details (default)
• high — Lists all tests including successful ones with full expressions

The framework stores this value in Config::m_data.verbosity and exposes it through IConfig::verbosity(), implemented in src/catch2/catch_config.cpp. The parser in src/catch2/internal/catch_commandline.cpp (lines 124-131) maps the --verbosity flag arguments to these enum values.

Colour Modes

The enum class ColourMode at lines 46-54 specifies the coloring backend:

• ansi — Standard ANSI escape sequences for terminal colors
• win32 — Windows Console API specific calls
• none — Disables all color output
• PlatformDefault — Automatically selects based on system capabilities (default)

The global default lives in Config::m_data.defaultColourMode, accessible via IConfig::defaultColourMode(). During reporter construction, makeColourImpl in catch_reporter_helpers.cpp instantiates the concrete implementation based on these settings.

Global Command-Line Configuration

Set framework-wide defaults using these flags processed by catch_commandline.cpp:

--verbosity <quiet|normal|high> — Controls the global detail level stored in Config::m_data.verbosity.

--colour-mode <ansi|win32|none|default> — Sets the global colour implementation, replacing the legacy --colour flag (Catch2 3.0.1+).

# Maximum detail with forced ANSI colors

./my_tests --verbosity high --colour-mode ansi

# Minimal output without colors

./my_tests --verbosity quiet --colour-mode none

Per-Reporter Output Streams and Colour Overrides

Redirect output destinations and override color modes for individual reporters using the specification syntax parsed in src/catch2/internal/catch_reporter_spec_parser.cpp (lines 41-47). The format is:

--reporter <name>::out=<file>::colour-mode=<mode>

The Config constructor in src/catch2/catch_config.cpp (lines 55-60) builds ProcessedReporterSpec objects from these strings, allowing per-reporter settings to override global defaults.

# Console to stdout with ANSI colors, JUnit XML to file without colors

./my_tests \
  --reporter console::out=-::colour-mode=ansi \
  --reporter junit::out=results.xml::colour-mode=none

In this example, - represents stdout, while results.xml receives the JUnit XML output. The colour mode for each reporter is stored separately in its ProcessedReporterSpec, decoupling the console coloring from the XML file content.

Configuration File Defaults

Catch2 reads a .catch2 file in the project root directory to establish baseline settings before applying command-line overrides:

# .catch2

verbosity = high
colour-mode = ansi

When present, these values populate Config::m_data before CLI parsing occurs, allowing you to commit project-specific defaults to version control while retaining runtime flexibility.

Implementation Reference

These source files control the configuration lifecycle:

• src/catch2/interfaces/catch_interfaces_config.hpp — Declares Verbosity (lines 20-24) and ColourMode (lines 46-54) enums
• src/catch2/internal/catch_commandline.cpp — Parses --verbosity (lines 124-131) and --colour-mode flags
• src/catch2/internal/catch_reporter_spec_parser.cpp — Extracts out and colour-mode keys from reporter specs (lines 41-47)
• src/catch2/catch_config.cpp — Constructs ProcessedReporterSpec and applies overrides (lines 55-60)
• src/catch2/reporters/catch_reporter_helpers.cpp — Implements makeColourImpl for runtime color instantiation

Summary

Catch2’s output configuration follows this structural pattern:

• Verbosity is a global suggestion (quiet/normal/high) stored in Config::m_data.verbosity that reporters may interpret according to their capabilities
• Colour modes (ansi/win32/none/default) are defined in catch_interfaces_config.hpp and instantiated via makeColourImpl based on IConfig::defaultColourMode()
• Output streams are configured per-reporter using ::out=<file> syntax, with - indicating stdout, processed by catch_reporter_spec_parser.cpp
• Per-reporter overrides use the ::colour-mode= syntax, stored in ProcessedReporterSpec, and applied in Config’s constructor at lines 55-60 of catch_config.cpp

Frequently Asked Questions

How do I disable colored output entirely in Catch2?

Use the --colour-mode none flag for global disable, or specify ::colour-mode=none for specific reporters. According to catch_interfaces_config.hpp, this selects the none enum value, which makeColourImpl in catch_reporter_helpers.cpp handles by returning a null color implementation that suppresses all escape codes.

Can different reporters use different verbosity levels?

No, verbosity is strictly a global setting stored in Config::m_data.verbosity and accessed via IConfig::verbosity(). While all reporters receive this value during initialization (as seen in catch_config.cpp), each reporter implementation independently decides how to honor the setting. Console reporters respect all three levels, while structured reporters like JUnit XML typically ignore verbosity since their schema is fixed.

Why does Catch2 use "colour" instead of "color" in its API?

The framework maintains British spelling conventions throughout its codebase and user interface. The --colour-mode flag processed in catch_commandline.cpp and the ColourMode enum defined in catch_interfaces_config.hpp consistently use the "colour" spelling. You must use this exact spelling; the parser does not accept "color" variants.

Where does Catch2 store the output file configuration for reporters?

Per-reporter output streams are stored in ProcessedReporterSpec structures created in src/catch2/catch_config.cpp (lines 55-60). When you specify ::out=filename, the reporter spec parser in catch_reporter_spec_parser.cpp extracts this value, and the Config constructor associates it with the specific reporter instance, directing that reporter’s output to the specified file descriptor instead of the default stdout.

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