Documenting google tests

Question

I recently started using google tests to help me with testing procedures. It is working well but now my test cases are growing...

#include <gtest/gtest.h>

TEST(MyTest, FirstTest) {
    // stuff
};

TEST(MyTest, SecondTest) {
    // stuff
};

TEST(MyTest, ThirdTest) {
    // stuff
};

int main(int argc, char* argv[]) {
    ::testing::InitGoogleTest(&argc, argv);
    return RUN_ALL_TESTS();
};

I would like to create a nice auto-generated documentation for all my tests that would be separated from the documentation of my program. For that purpose I commonly use doxygen but google tests use macros and it is unclear how doxygen can handle that. More precisely we have

#define TEST(test_case_name, test_name)\
  GTEST_TEST_(test_case_name, test_name, \
             ::testing::Test, ::testing::internal::GetTestTypeId())

I tried

/** 
* @def TEST(MyTest, FirstTest)
* @brief My first test
*/
TEST(MyTest, FirstTest) {
    // stuff
};

But it does not produces any output on doxygen...

Answer 1

Appearantly your question was just answered with Rob Kennedy's answer. But nevertheless I want to offer a completely different approach.

I use the RecordProperty() method of gtest to create an extra description attribute in the test log XML and just pass it a short description of what the test method is doing as string literal. I've created a little macro named TEST_DESCRIPTION that's supposed to be called as first statement in any test case:

#define TEST_DESCRIPTION(desc) RecordProperty("description", desc)

TEST(MyTest, SecondTest) {
    TEST_DESCRIPTION("This test does 'stuff'");
    // stuff
};

Additionally I have a simple XSLT transformation that creates a HTML test report from the XML testlog output and shows this @description attribute.

A drawback of this method is that the description attribute won't appear for disabled tests, since RecordProperty() won't be executed for those of course.

The whole thing was invented as my boss asked for test case descriptions of unit tests and I didn't want to describe these in a separate tool (e.g. we have Polarion for requirements analysis and you could also describe test scenarios there) because this is likely to become inconsistent quickly.

But maybe doxygen may provide additional benefits as it's able to show the call references from your test methods.

Answer 2

You're using @def, but that's the command for macro definitions. That command is not followed by a #define statement, so Doxygen ignores it. The Doxygen command for functions is @fn, so use that instead.

Also keep in mind that for Doxygen to document global functions, the enclosing file needs to be documented, too.