The Continuous Integration Workflow

We’ve been working ’round the clock here at NCover to maintain the best code coverage tool in the world! I’d like to explain the tools we’ve introduced in NCover 4 to make it as simple as possible to integrate NCover into your build. So far we have seen a bit of confusion surrounding which CI solutions support NCover 4 and vice versa. NCover 4 is build server agnostic, it should work with any CI solution you can find, providing you have control over how your tests are run.

*UPDATE*

– If you’re looking for a simpler way to accomplish the functionality provided by the USE and SUMMARIZE commands, read about the RUN command here.

NCover USE

The NCover 4 command line utility offers several commands, 2 of which are very helpful when using NCover in your build: USE and SUMMARIZE. The first order of business is to set up a project that can cover the tests you need to run. So add a match rule to your project to catch nunit-agent.exe or whatever testing framework you are using. Once this is done you can work on your build script. NCover can use environment variables to limit coverage data to a particular project. So if you have several projects that all collect data on the same process, you can use an environment variable to notify NCover of which project should be used. You can also add an environment variable to provide a build id for NCover to attach to executions going into that project. This can even come from variables provided by your CI environment. To find out what these environment variables are, you can use the NCover Use command like this:

ncover use --project="MyProject" --buildId="$(build-id)"

This will basically print out the environment variables you need in batch format. You can either manually set these variables in your build script or you can run the USE command redirecting the output to a batch file and run that file before your build.
You could even use the following trick to set the environment variables automatically:

for /f "usebackq tokens=*" %%a in (`ncover use --project=MyProject --buildId=$(build-id)`) do %%a

Once the environment is set, you can run your unit tests with the testing framework of your choice; NCover should be using the project specified in the environment.

NCover SUMMARIZE

At this point, NCover is collecting coverage data on your process, and once your process finishes, your build is complete. So how can we make sure we are notified when NCover finishes collecting? (NCover 4 does not keep processes from exiting when they are finished). We’ve provided the SUMMARIZE command so that you can keep your build from finishing before NCover is finished collecting. It looks at the latest execution of a specified project (or the execution with the specified build id), and prints out a summary:

ncover summarize [--project="MyProject"] [--buildId="$(build-id)"] [--wait] [--fail-build]

If NCover is currently collecting coverage data for the specified project and you specify the –wait option, the program will wait for NCover to finish that latest execution before printing out the summary and exiting. If the –fail-build option is specified, NCover will return an error code if there are stats that did not pass the threshold tests for that project.

As you can see, all of these arguments are optional. This is because NCover will check for the environment variables set using the NCover use command, so in our example we would not need to specify the project or the build id because it has already been set with the use command. Combining all of these together we have a workflow that looks something like this (using nunit as an example and redirecting “NCover Use” to a batch file):

ncover use --project="MyProject" --buildId="$(build-id)" > ncover-env.bat
ncover-env
nunit-console.exe mytests.dll
ncover summarize --wait

This could be put in a cmd file and run in your build script, or it can be translated to MSBuild, NAnt, or whichever CI solution you use!

We are adding new features each day, and we’re excited about some features coming up that will continue to make your life easier… stay tuned and enjoy!

*UPDATE* – We’ve added a simpler way to accomplish the functionality provided by the USE and SUMMARIZE commands. Read about the RUN command here.