In this article, I give a brief tutorial on how to use PartCover, a free, open-source code coverage analysis tool for .NET developers. Code coverage can help you to determine whether or not your software has been adequately unit tested, and is particularly useful in highlighting edge cases that may have been overlooked.

As far as free code coverage tools for .NET developers are concerned, neither the NCover Community Edition nor PartCover are 64-bit compatible out of the box yet, which is quite a shame, since I think most developers have moved on to 64-bit boxen by now. Luckily, the solution was readily available on the venerable StackOverflow. Note that if you’re running Windows 7, there is a a minor additional step: you will have to launch PowerShell or cmd as an administrator, because otherwise Program Files is read-only. Alternatively, you can download this version of PartCover.exe that has already been converted and place it in your installation directory.

Running the Analysis from the GUI

Before you can view the results of your analysis, you’ll have to run it. It’s not exactly immediately clear how to set up the analysis from within the PartCover Browser, so here’s a quick rundown of the dialog you’ll see when you do a File –> Run Target…

The Executable File should be set to the 32-bit version of your unit testing framework’s runner – in my case, that’s nunit-console-x86.exe. It should not be the path to your project’s binary.

Set the Working Directory to your unit test project’s bin folder. Working Arguments is where you’ll finally specify the path to your unit test project’s binary – in my case, this is Debug\SuffixArrayTests.dll.

Last, you need to specify the rules for what to run. Each rule takes the form of +filter or –filter, where +filter causes a class to be included in the coverage report, and –filter causes it to be excluded even if a previous rule would have included it. Filters, in turn, take the form [Namespace]Class, with support for wildcards. In the case depicted here, coverage analysis will be provided for all classes in the SuffixArray namespace, and all classes in the SuffixArrayTests namespace.

You can save these settings for later, but remember that the Save / Load buttons here are not the same as the Save/Open report buttons in the main window, which are for the results of the coverage analysis, not for these settings. That is to say, if you want to load your target settings again later, you’ll need to do so within this window.

Running the Analysis from the Console

You can also run the coverage analysis from the command line or with a batch file like this one. This is useful if you’d like to run the same coverage report frequently, or if you’d like the analysis to be performed as part of your continuous integration.

set partcover="C:\Program Files (x86)\Gubka Bob\PartCover .NET 2.3\partcover.exe"
set nunit="C:\Program Files (x86)\NUnit 2.5.3\bin\net-2.0\nunit-console-x86.exe"
set tests="Debug\YourTests.dll"
%partcover% --target %nunit% --target-args %tests% --include [*]* --output PartCoverResults.xml

Once your coverage report has been generated, you can open it in the PartCover Browser exactly as if it had been created from within the GUI.

What Your Coverage Is Telling You

Before you do anything else, enable “View Coverage Details.” Frankly, I’m not sure why this isn’t enabled by default, because it’s what reveals most of the information you’re interested in.

The pane to the left shows you the structure of your code, as well as how much of the code was reached during execution. Code that is reached is green, while code that is never reached is red. If code is not reached, a unit test is probably missing.

Essentially, unreached code means that there is a path of execution that is not hit by any of your unit tests. This doesn’t necessarily mean that you’re missing a unit test – there is some grey area – but it is definitely a warning light. Even if you’re confident that the code works, it’s worth remembering that unit tests are one of the few kinds of documentation capable of yelling at you when they’ve become outdated or inaccurate.

What Your Coverage Is Not Telling You

Remember that a code coverage analysis tool can only analyze the coverage of your unit tests in terms of how many paths through your code get exercised. It can’t tell you if you’re exercising these paths properly, or whether you are checking for meaningful conditions.

Another case where your coverage tool cannot help you is when your unit tests are conflated. In my example, there is a SuffixArray class and a SuffixComparer class. In this example, I did not even load the unit tests for the latter class, but it’s still considered to have 100% coverage. This is because the SuffixComparer’s sole method has only one execution path, and it is used by SuffixArray methods which are tested, despite not having been tested itself. That’s not to say that code coverage analysis is useless in this case, though – if you’re like me, unexpectedly covered code can also help you realize when you’ve forgotten a unit test. I’ll be honest with you: although I’ve fixed it now, when I first started writing this article, I didn’t forget to load the tests for SuffixComparer -- I forgot to write them. As I looked at the results, it jumped out at me that SuffixComparer was “covered” even though I had failed to write tests – and having noticed this, I went back and created the missing tests. Even when code coverage does notice your failures, it may help you to notice them yourself.