Undocumented Macros

[capsocrates]

I was working on writing some thread-safe versions of the catch macros (see below) when I noticed several macros I had never seen before. I checked the docs to see what they do and I see that they're not documented. I would like to see some documentation about what they do. This seems like a win all around, since showing that the library has even more functionality make it more appealing, while current users are introduced to cool things they already have access to.

Here are the macros I couldn't find documentation for:

• CHECKED_IF
• CHECKED_ELSE
• CHECK_NOFAIL
• METHOD_AS_TEST_CASE
• REGISTER_TEST_CASE
• SUCCEED
• ANON_TEST_CASE
• DYNAMIC_SECTION

As for my idea for thread-safe catch macros, it's something like this...

std::mutex & GetCatchMutex() {
    static std::mutex catchMutex;
    return catchMutex;
}

#define TS_CORE(catchMacroWithExpression)	\
{	\
	std::lock_guard<std::mutex> guard{ GetCatchMutex() };	\
	catchMacroWithExpression;	\
}

#define TS_REQUIRE(expression) TS_CORE(REQUIRE(expression));
#define TS_REQUIRE_FALSE(expression) TS_CORE(REQUIRE_FALSE(expression));
#define TS_REQUIRE_NOTHROW(expression) TS_CORE(REQUIRE_NOTHROW(expression));
#define TS_REQUIRE_THROWS_AS(expression, exceptionType) TS_CORE(REQUIRE_THROWS_AS(expression, exceptionType));

#define TS_CHECK(expression) TS_CORE(CHECK(expression));
#define TS_CHECK_FALSE(expression) TS_CORE(CHECK_FALSE(expression));
#define TS_CHECK_NOTHROW(expression) TS_CORE(CHECK_NOTHROW(expression));
#define TS_CHECK_THROWS_AS(expression, exceptionType) TS_CORE(CHECK_THROWS_AS(expression, exceptionType));

#define TS_INFO(msg) TS_CORE(INFO(msg));
#define TS_WARNO(msg) TS_CORE(WARN(msg));
#define TS_CAPTURE(msg) TS_CORE(CAPTURE(msg));

#define TS_FAIL(msg) TS_CORE(FAIL(msg));
#define TS_FAIL_CHECK(msg) TS_CORE(FAIL_CHECK(msg));
#define TS_SUCCEED(msg) TS_CORE(SUCCEED(msg));

This adds thread-safe versions of the macros on an opt-in basis. Something worth considering if thread-safe macros by default has been considered and rejected.

[cstratopoulos]

I think this probably fits as an addition to your issue rather than opening my own. The DYNAMIC_SECTION macro in particular is, as far as I can tell, only documented in release notes for 2.3.0: https://github.com/catchorg/Catch2/blob/master/docs/release-notes.md

When I read about it I thought instantly of the limitation regarding sections nested in loops, it could be good to add a blurb saying something like

As of Catch 2.3.0, this can be written as DYNAMIC_SECTION("Looped section " << i)

[onqtam]

@cstratopoulos out of curiosity - why would one want to use a section inside of a loop in that manner? Why not just use CAPTURE or INFO as seen here?

Sections are designed for re-entering the whole test case multiple times and sharing setup/teardown code - not for labeling loop iterations... This use case doesn't stop amusing me.

[cstratopoulos]

@onqtam not sure why you're asking this here, or asking me, I'm just quoting from (and suggesting a one-line addition to) the existing Catch docs. Is it really that hard (or "amusing") to imagine running common setup code to generate intermediate inputs that get mutated and/or asserted on in some manner parametrized by a loop counter or range-for loop elements? This is left as an exercise to the reader, I'd rather not further derail this issue 🙈🙉🙊

[horenmar]

I am in the process of adding some documentation for these macros, so they should be documented soon(ish). The work-in-progress can be found in branch dev-macro-docs.

I am going to comment on the rest of this thread later.