Using Doxygen’s \test command with C++

I’m working on some C++ code that is documented using Doxygen. Nothing earth-shattering there.

But I’m doing unit testing, and writing unit tests. In this case, I’m using the boost C++ libraries. That means my tests don’t look like classes, the way they might look if I was using CppUnit or CxxUnit. Instead, they look like macros:

BOOST_AUTO_TEST_CASE( null_ctor ) {

Arena & sut = Simple::Arena();
BOOST_CHECK( sut.capacity() != 0 );
}

The macro expansion is really quite clever, in a Lovecraftian “there are secrets man was not meant to know” fashion. And reading them has certainly improved my knowledge of C++. (But it also permanently lowered my SAN by a few points, I think.)

Anyway, Doxygen offers this command called \test that seems tailor-made for testing.

Well, it’s not. The command description is very “vague,” in that you use it to add entries (paragraphs) to the “test list.”

Some experimentation will show that the apparent use is to document something (a class, a function) and add a bunch of these \test entries, just like adding \param commands. And the entity you are documenting will then have a Test: section in its documentation.

This is totally not what I want. And I’m pretty sure it’s not what anybody doing TDD wants. What I want is to somehow tie my tests, which are in a separate location (different file, different class, different namespace, etc.), back to the class or function that I’m testing.

The best way I’ve found so far to accomplish this is to lie to Doxygen about what is being documented. Here’s my current scheme:

#define BOOST_TEST_DYN_LINK
#include <boost/test/unit_test.hpp>

#include <Bronze/Memory/Simple/Arena.h>

using namespace Bronze::Memory;

BOOST_AUTO_TEST_SUITE( Memory_SimpleArena )

/// \class Bronze::Memory::Simple::Arena
/// \test \b null_ctor Confims that a SimpleArena no-args construction will
/// use the default size, whatever that is. (1m)

BOOST_AUTO_TEST_CASE( null_ctor ) {

Arena & sut = Simple::Arena();
BOOST_CHECK( sut.capacity() != 0 );
}

Adding the \class command tells Doxygen to re-open the documentation of the target class. The \test command is then associated with the “right” class, and I include the testcase name in bold as part of the test description.

This still doesn’t generate a link to the right source file (containing the test), and it doesn’t really know anything about the test case. So it’s not a perfect solution. But it does enable me to put my testcase documentation with my testcases, while having the documentation actually show up attached to the right class.

Leave a Reply