自动单元测试示例代码

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

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

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

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

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

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

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

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

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

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

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

   /// 

   /// Gizmo which can act as client or server.
   /// 
   /// 
   /// The following example shows how to use the gizmo as a client:
   /// 
   /// 
   public class Gizmo

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