Question

我正在尝试使用doxygen来记录我的单元测试，但是我想在代码中而不是在测试头中记录它们，以减少进行类似测试时的复制/粘贴错误。值得注意的是，我正在使用RTF输出格式。

    /** @brief A method for testing doxygen method documentation
     * @test
     *     -#Step 1
     *     -#Step 2
     *     -#Step 3
     */
    [TestMethod()]
    public void DoxygenScratchPadInHeader()
    {
        // code that may or may not be in sync with header
    }

    /** @brief A method for testing doxygen method documentation
     * @test
     */
    [TestMethod()]
    public void DoxygenScratchPadInLine()
    {
        /// @par
        ///     -#  Initialize the value to 0
        int i = 0;

        /// @par
        ///     -# Add a number
        i += 3;

        /// @par
        ///     -# Assert that the number is three
        Assert.AreEqual(3, i);
    }

测试列表输出：

成员UpdateProtocolQATests.CUpdateProtocolTest.DoxygenScratchPadInHeader（）

第1步
第2步
第3步

成员UpdateProtocolQATests.CUpdateProtocolTest.DoxygenScratchPadInLine（）

{注意这里没有步骤}

功能描述输出：

void UpdateProtocolQATests.CUpdateProtocolTest.DoxygenScratchPadInHeader（）

测试doxygen方法文档的方法。测试：

第1步
第2步
第3步

void UpdateProtocolQATests.CUpdateProtocolTest.DoxygenScratchPadInLine（）

测试doxygen方法文档的方法。测试：

1.  Initialize the value to 0


1.  Add a number


1.  Assert that the number is three

{将最后一位显示为代码，因为stackoverflow正在纠正重复的1.到1. 2. 3 ......这实际上是我最终想要的......}

实施在线测试步骤文档的任何更好的想法？我不太关心没有出现在测试列表中的步骤，我们可以只使用对函数的引用。

Answer 1

使用支持内联注释生成文档的工具：

Doxygen有helpers for perl，这就是NaturalDocs所写的。

Answer 2

我非常同情你的困境，但就我所知，Doxygen确实仅旨在记录特定的代码对象（文件，类，名称空间，变量等）而不是任意代码行。

目前，我唯一可以考虑绕过这个缺点的方法是生成评论，其中包含您希望通过\code command进行记录的实际代码。

我可以通过两种方式来实现这一目标：

在Doxy注释中放置一些特殊字符串（例如，DOXY_INLINE_CODE），这些注释应该与一行代码相关联。然后编写一个过滤器（请参阅FILTER_PATTERNS），将此字符串替换为\code <nextline> \endcode，其中<nextline>是过滤器看到的下一行代码。我不确定Doxygen会把这些评论放在哪里或者他们看起来如何;不幸的是，它们可能非常丑陋。（我不喜欢的一个奇怪的行为是\code命令似乎剥离了前导空格，所以你不会让缩进正常工作。）
写一个＆＃34; Doxygen runner＆＃34;这会在调用.dox之前自动生成代码中的doxygen个文件。这些自动生成的.dox文件将包含从相应的.cpp或其他源文件生成的文档。您可以使用各种Doxygen命令来link back to实际源代码的文档，还可以insert a copy源代码文档中的.dox文档（反之亦然）。< / LI>
这些都是黑客攻击，你不得不用很多方法来解决这个问题，但是我希望这些建议有所帮助。祝你好运。（我目前正在做类似的工作，让Doxygen能够很好地记录Google测试，同时也是针对高度监管行业的项目。）

Answer 3

当我在寻找类似的解决方案时，我记得遇到过这个问题。我想将用户测试程序尽可能地记录到相应的单元测试或单元测试组中。以下是我们使用Doxygen组/子组实现的解决方案的子集。

定义了一个单独的manual-test.dox文件来创建一个顶级组和几个子组，在这些子组下收集特定的手动测试。

/**
@defgroup manualtest Manual Testing Instructions
@{
This section contains a collection of manual testing...

@defgroup menutest Menu Tests

@defgroup exporttest Import/Export Tests

@}
*/

以下显示了Java单元测试类的示例，其中包含单元测试文档和手动测试说明。

public MenuTests {
   ...

   /**
    * @addtogroup menutest
    * **Open File Test**
    * 
    * The purpose of this test is to...
    *
    * -# Do something
    * -# Verify something
    */
   /**
    * This unit test verifies that the given file can be created via
    * the File->Open... menu handler. It...
    */
   @Test
   public void open_file_test() {
      ...
   }
}

生成的HTML文档将包含手动测试说明页面在模块部分下。所述页面将包含manual-test.dox中给出的标记详细信息以及每个已定义子组的模块页面链接，例如菜单测试。

菜单测试页面将显示添加到此的所有手动单元测试步骤子组，从而提供可以包括的单独文档作为软件测试计划或用户测试计划的一部分参考。

唯一需要注意的是，没有办法明确定义将测试指令添加到组的顺序。在单个类中定义时，它们按照定义的顺序添加，并按字母顺序解析多个类。

对于需要更多控制测试收集方式的项目，Doxygen用于创建XML输出。使用XSLT模板提取测试用例并根据需要进行排序，但这是另一个问题。

记录单元测试符合代码

3 个答案: