自动单元测试示例代码

Question

我的团队负责为我们编写的大型系统开发API.我们需要提供示例代码,以便使用我们的API的其他开发人员可以学习如何使用它.我们一直在使用xml文档注释来记录代码.例如.

/// <summary>Summary here</summary>
/// <example>Here is an example  <code>example code here</code> </example>
public void SomeFunction() 

然后我们使用Sandcastle并构建我们需要的帮助文件(chm和在线网站).

当示例代码不起作用时,这是非常尴尬的,这通常是因为某些功能已更改或一个简单的错误.

有没有人做过这样的事情,还配置了单元测试来运行示例代码,以便知道它们在构建期间工作？

Answer 1

我建议在XML中使用一个特殊的标记,即"从这个地方获取代码示例".它将引用一个普通的C#文件,它可以通过单元测试运行.举个例子,你可能有:

/// <summary>Summary here</summary>
/// <example>Here is an example
/// <code>!!sourcefile:SomeClassTest.cs#SomeFunction!!</code></example>
public void SomeFunction()

您的单元测试正常运行,然后在"创建XML"和"运行Sandcastle"之间插入构建步骤,您将用适当的内容替换每个"文件令牌".甚至可能会有一些钩子你可以把它放到Sandcastle这样做的时候在doc生成时间 - 我不太了解Sandcastle肯定知道.

发明你自己的标记当然很难看,但它应该有效.

当然,这假设代码示例很容易进行单元测试 - 有些可能不是(如果他们正在处理资源等).至少你知道它编译虽然:)

Answer 2

是的,sandcastle支持这一点,保持示例的正确性非常好.你可以指向这样的代码区域:

   /// <summary>
   /// Gizmo which can act as client or server.
   /// </summary>
   /// <example>
   /// The following example shows how to use the gizmo as a client:
   /// <code lang="cs"
   ///    source="..\gizmo.unittests\TestGizmo.cs"
   ///    region="GizmoClientSample"/>
   /// </example>
   public class Gizmo

然后,您可以在TestGizmo.cs中使用一些测试代码作为示例,将其封装在一个区域中:

[Test]
public GizmoCanActAsClient()
{
   #region GizmoClientSample
   Gizmo gizmo = new Gizmo();
   gizmo.ActAsClient();
   #endregion
}

警告:如果您移动或重命名测试文件,当您尝试使用sandcastle重新生成文档时,您将只会收到有关此错误的错误.