Documenting test case files with Doxygen?

[Charlie Schultz]

Hi,
Anyone try to make Doxygen work a little nicer with test case files? As is, it seems to (rightly so) interpret TEST (x, y) as a function call and only "TEST" shows up in the contents. And if you have a file with 20 test cases, then it makes it hard to find the one of interest by looking at the contents list (you'll see 20 rows of just "TEST"). I tried a couple predefined macro expansions but didn't make any (forward) progress.

It'd be nice if it would somehow interpret the args as class name and function name.

[Bas Vodde]

Hi Charlie,

I've never used Doxygen over my tests, sorry :( Never found much of a need for it.

Anyways, the macro (TEST) eventually becomes a class with the name of the argument. If it would expand the macro, then it *shouldn't* just come up as TEST though…

Not sure that helps?

Bas

[Andreas Stenius]

Hi,

I just started documenting our project using doxygen too, and the
solution is to configure doxygen to expand the TEST macro.

In

# Configuration options related to the preprocessor

Check these options:

ENABLE_PREPROCESSING = YES

MACRO_EXPANSION = YES

EXPAND_ONLY_PREDEF = YES

# make sure doxygen can find the CppUTest headers...
INCLUDE_PATH = @top_srcdir@/deps/cpputest/include

EXPAND_AS_DEFINED = TEST_GROUP \
TEST


Each of these have a descriptive comment in the config file, and are
also in the doxygen documentation.

But these settings should get you off the ground :)

Cheers,
Andreas

2013/1/13 Bas Vodde <ba...@odd-e.com>:

[Charlie Schultz]

Thanks for the replies!

Yes, I thought it should be able to expand the macros and I've tried all the settings that Andreas suggested (and then some), but no luck. If I run doxygen from the command line with the -d Preprocessor option, it does complain about include files not being found, e.g. "#include c:\root\CppUTest\include\cpputest\testharness.h: not found! skipping...". But the file is there, it does compile and run ok (vs2010).

I found a couple bugs in the doxygen buglist relating to include_path and includes in general, so I think the problem is in doxygen (I'm using 1.8.3 which I think is the latest).

[Andreas Stenius]

2013/1/14 Charlie Schultz <cj.sch...@gmail.com>:
> Thanks for the replies!
:)

Indeed it is.
What setting have you for INCLUDE_PATH?
What is your working dir when invoking doxygen?
And under what environment? (windows command prompt or cygwin, or mingw?)

As it complains it doesn't find the cpputest headers, I'd bet that is
the issue. Once that is resolved it should work just fine.

[Charlie Schultz]

Include path = "../../../CppUTest/include/CppUtest" (using the doxygen browser). I've also tried "c:\root\CppUTest\Include\CppUTest", "c:\root\CppUTest\Include", and a couple other variations. All give the same results.

I invoke doxygen from "c:\root\pluggable optics\potest\potest", which is where the (test) source files are.

I'm using Win7 and run doxygen using its GUI frontend. VS2010 for the test code compiler.

I did just find that if I copy the TEST and TEST_GROUP macros into the PREDEFINED box in doxygen, it does seem to work. E.g.:
TEST_GROUP(testGroup)= \
  TEST_GROUP_BASE(testGroup, Utest)

TEST(testGroup, testName)=\class TEST_##testGroup##_##testName##_Test : public TEST_GROUP_##CppUTestGroup##testGroup \
{ public: TEST_##testGroup##_##testName##_Test () : TEST_GROUP_##CppUTestGroup##testGroup () {} \
       void testBody(); }; \
  class TEST_##testGroup##_##testName##_TestShell : public UtestShell { \
      virtual Utest* createTest() { return new TEST_##testGroup##_##testName##_Test; } \
  } TEST_##testGroup##_##testName##_TestShell_instance; \
  TestInstaller TEST_##testGroup##_##testName##_Installer(TEST_##testGroup##_##testName##_TestShell_instance, #testGroup, #testName, __FILE__,__LINE__); \

[Andreas Stenius]

My guess is that you should drop the ending CppUTest from your include
path, if you have #include "CppUTest/TestHarness.h" in your test
file...

2013/1/14 Charlie Schultz <cj.sch...@gmail.com>:

[Charlie Schultz]

That was one of the things I tried, but it did not work for me.

Perhaps if it shared the same top level folder (see https://bugzilla.gnome.org/show_bug.cgi?id=685695)

[Bas Vodde]

Hi Charlie,

Perhaps also be careful on the case sensitiveness.

I noticed the error in an earlier mail said:
c:\root\CppUTest\include\cpputest\testharness.h

And TestHarness.h and CppUTest seem in small caps. VS probably doesn't care, but perhaps doxygen does?

Bas