Rory Primrose

Learn from my mistakes, you don't have time to make them yourself

View project on GitHub

Using GhostDoc to document unit test methods

GhostDoc is one of the coolest tools around for Visual Studio. Sometimes it needs a little help though and unit test methods are a classic example. The format of my unit test method names usually identifies the method name, parameter list, parameter value conditions, expected outcome and end in “Test”. The default rule that GhostDoc applies to this format is fairly ugly.

For example,

/// <summary>
/// Creates the returns cache store instance test.
/// </summary>
[TestMethod] 
[Description("Black box tests")]
public void CreateReturnsCacheStoreInstanceTest()
{
    ICacheStore actual = CacheStoreFactory.Create();
     
    Assert.IsNotNull(actual, "Create failed to return an instance");
}    

Creating a custom GhostDoc rule for unit test methods can assist in cleaning the documentation up a little.

First, open up the GhostDoc configuration.GhostDoc configuration

Under methods, click Add.GhostDoc configuration dialog

Click Ok.Add Rule dialog

Enter the new rule name, identify that the method name must end in “Test” and fill out the summary using the value “Runs test for $(MethodName.Words.ExceptLast).”.Edit Rule dialog

Using this new rule, the example above now gets the following documentation generated.

/// <summary>
/// Runs test for create returns cache store instance.
/// </summary>
[TestMethod]
[Description("Black box tests")]
public void CreateReturnsCacheStoreInstanceTest()
{
    ICacheStore actual = CacheStoreFactory.Create();
     
    Assert.IsNotNull(actual, "Create failed to return an instance");
}

It’s not perfect, but its a lot better.

Written on March 18, 2009