catchorg / catchorg/Catch2

Recommendations for include order / stream operators?

Open
#2,718 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
C++
Stars
21.5k
Forks
3.5k
Avg merge
3d 16h
Merged PRs (30d)
2

Description

The Catch2 documentation states that any custom stream operators (or equality operators) must be declared before including Catch2 (https://github.com/catchorg/Catch2/blob/devel/docs/tostring.md#top). My question is how to accomplish this best while following other established C++ guidelines.

My project is split into lots of libraries. Each library has data structures with stream operators. Each library has a Catch2 test executable. I would usually compile files like this into test executables:

```cpp
// STL and third-party headers first
#include
#include

// Project headers second
#include "MyLibrary/MyDataStructure.hpp" // defines stream operators
#include "MyOtherLibrary/TestUtilities.hpp" // also includes Catch2

TEST_CASE("...") { ... }
```

This structure fails to compile, because Catch2 can't find the stream operators.

Do I have to move the Catch2 include to the bottom? But how is that possible when including other headers with test utilities that need to include Catch2? Relying on the include order so much seems very fragile. So do I have to add forward-declaration files for all stream operators and include them at the top? That also seems very fragile, and requires me to make a lot of invasive changes to the project (lots of stream operator declaration files, probably same for equality operators). And this breaks if the declaration headers are included through other headers.

Does anyone have suggestions for me?

Contributor guide

Open the contributing guide

Research direction

Start with docs/tostring.md#top and reproduce the include order shown in the issue using the referenced Catch2 and project headers. Determine what guidance the documentation should provide for custom stream and equality operators across test utilities, and consider the work complete when the recommended arrangement is clear and addresses nested Catch2 includes.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
documentation, testing-qa
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.