Paul Stovell says…

Yesterday I announced a tool that we’ve built at Readify called the Scenario Coverage Analyser for Team Foundation Server. Today I wanted to give a brief walkthough in setting it up.

The Package

The first thing you’ll need to do is head over to the download page for the tool, and download the ZIP file attached at the bottom of the page:

http://readify.net/Default.aspx?tabid=269

The zip file is structured as follows:

• /ScenarioCoverageAnalyser-1.0.0.0/
  • /Readify.Traceability.Attributes.dll
    This assembly contains the custom .NET attribute classes that you’ll need to reference from each of the assemblies you want to analyse.
  • /MSBuildTasks/
    • [A whole bunch of DLL’s used by the custom task]
    • Readify.Traceability.BuildTasks.targets
      The targets file for the custom MSBuild task that you’ll need to call as part of your build process.

Step 1: Add the Attributes

You will need to add the [Requirement] attribute to every unit test and class that you want to link to a work item. If you forget to add the attribute, the code will be classed as “untraceable” (refer to yesterday’s post).

The attribute uses a params array to specify the requirements, meaning it can be used like this:

[Requirement(3902, 3903)]
public class Customer { ...

Any code in that class will be assumed to be traced back to TFS work items #3902 and #3903. Likewise, when you apply the attribute to a method, all code in that method is assumed to be traced back to the work items you specify. Take a look at the following snippet:

[Requirement(1)]
public class CustomerService {
    [Requirement(2)]
    public void Save() { ... }

    [Requirement(2, Mode=RequirementOverrideMode.Override)]
    public void Delete() { ... }
}

In this case, Save() is assumed to belong to work items #1 and #2, while Delete() is assumed to only belong to work item #2 (and not #1). The RequirementOverrideMode enumeration simply lets you specify whether a requirement attribute at the method level “overrides” that of the containing class, or whether it “adds” to it, with the default being “add”.

Once you’ve applied the attribute to your code, you simply have to update your team build.

Step 2: Edit Build

I’ll assume you already have an existing team build to which you want to add the task onto. There are a couple of things you must do to get the task to work:

• You must have code coverage enabled.
• You must run unit tests as part of the build.

In truth, to generate the matrix you shouldn’t even need to do both of those, they should only be needed for the coverage information. But it was easier to implement it this way, so for this beta it’s a requirement (though it’s on the top of my list of things to fix).

Assuming you have both of those enabled, all you’ll need to do is reference the targets file and call the task. Here’s an example of referencing the targets file:

<Import
    Project="IncludeReadify.Traceability.BuildTasks.targets”
    />

Add this right near the top of your team build file, just under the Projects root node. In my case, I like to keep any custom tasks used in the build under an Include directory in the Team Build definition.

Now to call the task. You’ll need to call this after the unit testing and code coverage phase has passed. I personally did it by overriding the AfterDropBuild task:

<Target Name="AfterDropBuild">
    <TraceabilityMatrixReport
        ProjectName=”Test Project”
        DropLocation=”$(DropLocation)$(BuildNumber)”
        OutputFileLocation=”$(DropLocation)$(BuildNumber)TraceabilityMatrix.html”
        />
</Target>

The only parameters are:

• ProjectName
  This is only used as the title for the HTML report, so set it to anything you like (though preferably something indicative of the real project )
• OutputFileLocation
  Tells the task where to store the resulting HTML file.
• DropLocation
  This will usually be set to $(DropLocation)\$(BuildNumber). This parameter exists so that you can run the task from an MSBuild file without using Team Build.

After you’ve made those changes simply run the build and then take a look at the resulting matrix

Filed under: TFS, Projects