Friday, August 26, 2011

Hudson: Installation and Configuration for Dot.NET Projects

Hudson is a tool for continuous build, integration and deployment widely used in the Java world. Hudson can be used also with other platforms and programming languages and on many operating systems. A lot of plug-ins are available for Hudson.

For the Dot.NET world Hudson provides complete environment for continuous integration. The tool compile code with MSBuild, can run NAnt scripts, can run NUnit tests, check for code rules with FxCop or Gendarme, create documentation with Sandcastle.

The Hudson server by default provides integration with Subversion. It can be installed on Windows to run as a windows service.

The configuration of the jobs to run on the Hudson server is done completely from the web-based console of the tool. Also from there we install plug-ins.

Installing Hudson: Prerequisites

Installing Hudson on Windows is easy task. Following are the steps we needed in our case.

In this scenario we'll be using Hudson for Dot.NET development in conunction with the following tools: MSBuild, NUnit, FxCop, Gendarme, Sandcastle, so that we'll build, run unit tests, check code styles and create API documentation for our projects.

I will demonstrate using Subversion for source control system. But with Hudson you can easily use other version control systems too.

  • Install Java. Hudson is a Java application.

Download Link:

Add to the system environment variable %PATH% the directory name where the java.exe is:

"C:\Program Files (x86)\Java\jre6\bin"

Open new command window and try to check the version of Java installed:

C:\>java -version
java version "1.6.0_26"
Java(TM) SE Runtime Environment (build 1.6.0_26-b03)
Java HotSpot(TM) Client VM (build 20.1-b02, mixed mode, sharing)

  • Install the Dot.NET SDKs you need.

You can install all together 2.0, 3.5, 4.0 and use one or another as needed. Check if the MSBuild is installed:

Microsoft (R) Build Engine Version 2.0.50727.4016

Microsoft (R) Build Engine Version 3.5.30729.1

Microsoft (R) Build Engine Version 4.0.30319.1

You can even leverage this on that MSBuild version depending on the different projects you integrate in Hudson.

Add though the directory where the 4th version of Dot.NET is to the system PATH variable:


then test if you can run the MSBuild from new command prompt:

Microsoft (R) Build Engine Version 4.0.30319.1

  • Install the NUnit framework.

NUnit is a unit-testing (xUnit) framework. It comes with GUI tests runner and command line test runner.

Download Link:
In our case it is the version 2.5.10 from the URL:

Once the NUnit is installed, configure a version of the runner for the Dot.NET 4.0 framework. Copy directory:

C:\Program Files (x86)\NUnit 2.5.10\bin\net-2.0


C:\Program Files (x86)\NUnit 2.5.10\bin\net-4.0

Edit the nunit.exe.config file from the new directory and add at the end of that file:

  <requiredRuntime version="v4.0.30319" />

just before the closing "configuration" tag. Please note the version number, make the same as you've got installed.

Add to the system environment variable %PATH% the directory name:

"C:\Program Files (x86)\NUnit 2.5.10\bin\net-4.0"

Open new console window and check to see if the command line test runner is in the %PATH%:

NUnit version
Copyright (C) 2002-2009 Charlie Poole.

  • Install FxCop.

FxCop is a tool from Microsoft that analyzes managed code assemblies and reports information about design, localization, performance and security improvements.

The tool comes a part of the Windows SDK for Windows 7 and Dot.NET 4.
All other installers of the FxCop are outdated, that's why we have to get the SDK on the machine.

Download the SDK from URL:

Install with the default options.

The SDK was in our case installed into:

C:\Program Files\Microsoft SDKs\Windows\v7.1

The Samples into:

C:\Program Files\Microsoft SDKs\Windows\v7.1\Samples

A part of the SDK is the help library manager that gives you a chance to download locally on your computer part of the SDK documentation. The help library will be installed into:


and you (optionally) can install help content in there.

After this install finished, there is yet another installer now to run. The FxCop installer will be into directory:

C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\FXCop

Run the FxCopSetup.exe file from there.

The installer suggested in our case the following install folder:

c:\Program Files (x86)\Microsoft Fxcop 10.0\

After this installation finished, add to the system environment variable %PATH% the directory name:

"C:\Program Files (x86)\Microsoft Fxcop 10.0"

Open new console window and test if you can run the application:

Microsoft (R) FxCop Command-Line Tool, Version 10.0 (10.0.30319.1) X86
Copyright (C) Microsoft Corporation, All Rights Reserved.

  • Install Gendarme.

Gendarme is part of the mono-tools. It a rule based tool for finding problems in .NET applications and libraries much like the FxCop is.

Download and install the tool from the following URL:

The installer suggested to following target folder:
C:\Program Files (x86)\Gendarme\

After this installation finished, add to the system environment variable %PATH% the directory name:
"C:\Program Files (x86)\Gendarme"

Open new console window and test if you can run this application:
Gendarme v2.10.0.0
Copyright (C) 2005-2011 Novell, Inc. and contributors

  • Install Sandcastle, htmlhelp and SHFB.

Sandcastle produces MSDN style documetation from the source assemblies integrating the XML documentation from the source code.

Download and install Sandcastle from:

In our case the installer suggested by default the following install directory:
C:\Program Files (x86)\Sandcastle\

Download and install the Microsoft HTML Help Workshop from:

Run the downloaded file htmlhelp.exe and follow the instructions.

The default installation path was in our case:
C:\Program Files (x86)\HTML Help Workshop

Download and install the Sandcastle Help File Builder from:

Unpack the downloaded zip file and run the SandcastleInstaller.exe installer application. It comes with nice wizard GUI. Follow the instructions. The installer will ask you to download and install for you all the additional applications it will need in order to work. Just answer with "Yes" on those questions.

You will skip the installation of Microsoft Help 2, this is not a necessary part to have.

It also will ask you to apply a patch to Sandcastle. Answer with "Apply Patch" on this screen.

If you wish you can install also language pack for German language.

Optionally it will download for you the MAML guide - the guide from Microsoft for the documentation markup language, web project custom providers - a package with information for producing XML documents for web applications and website projects, a HTML to MAML converter.

If you don't have Visual Studio installed skip the section :MAML Schema InteliSense"

After this step it will suggest to install for you the SHFB - Sancastle Help File Builder. Cilck on "Install SHFB" on this screen.

The SHFB in our case was installed into:
C:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder\

On the last screen of the wizard click on the 'Reboot' in order all the changes to take effect on your system.

  • Visual Studio Templates

If on the machine where Hudson will be running the visual studio is not installed you may need to come some Visual template files from developer's machine. For example copy to the machine the complete directory:
C:\Program Files (x86)\MSBuild\Microsoft\VisualStudio\v10.0

as for Visual Studio 2010 Express Edition with default installation path.

Installing Hudson: Prepare Visual Studio Project Structure for Hudson

To easily integrate a Visual Studio Project into Hudson, I would suggest the following project structure and files to be created.

Suppose we've got a project named "WebAPI"

In my project directories in Subversion I would prefer having structure like:

directory .\References - copy here all the third party DLLs you'll be referencing from the project

directory .\WebAPI - here is the project with the production code: a Visual Studio project named like the directory - WebAPI.csproj

From project properties in the Visual Studio, in section "Build" go to sub-section "Output" and enable check the box "XML documentation file". The name of the output file in "Debug" target build configuration should be the same as the specified in the Sandcastle project (below).

directory .\WebAPITests - contains the project with the unit tests for the WebAPI project: another Visual Studio project with Visual Studio project file named WebAPITests.csproj

The project with the unit tests references the project with the production code.

file WebAPI.sln - the Visual Studio solution file.

file WebAPI.shfbproj - the Sandcaslte project file

To create the Sandcastle project file run the "Sandcastle Help File Builder GUI" application. From the project properties the make the HelpFileFormat to be "HtmlHeml 1, Website".

Documentation sources are:

which is the output after compiling the WebAPI.csproj with target build configuration "Debug".

note the OutputPath from the "Project Properties" panel. The output goes to:

This is the directory to which we'll make link in Hudson for the API documentation of our project once the documentation is generated. That way we'll publish the generated from the continuous integration API documentation as a web-site.

file run-fxcop.bat - a batch command to run FxCop from Hudson. Example:

FxCopCmd.exe /file:WebAPI\bin\Debug\WebAPI.dll  /rule:DesignRules.dll /out:fxcop-result.xml

exit 0

note it takes the Debug output from the the WebAPI project and the output of running the FxCop application goes to file fxcop-result.xml.

file run-gendarme.bat - a batch command to run Gendarme from Hudson. Example:

gendarme.exe --xml gendarme-result.xml WebAPI\bin\Debug\WebAPI.dll

exit 0

note it takes the Debug output from the the WebAPI project and the output of running the Gendarme application goes to file gendarme-result.xml

file run-nunit.bat - a batch command to run NUnit tests from Hudson.

nunit-console-x86.exe WebAPITests\bin\WebAPITests.exe /xml=nunit-result.xml

exit 0

note it takes the Debug output from the the WebAPI project and the output of running the NUnit console goes to file nunit-result.xml

file run-sandcastle.bat - a batch command to generate documentation

MSBuild.exe /p:CopyrightText="Copyright Company" /p:FeedbackEMailAdress="" WebAPI.shfbproj

exit 0

note we specify the MSBuild from the version 4.0 of Dot.NET and as a project file for the build project we point to the file WebAPI.shfbproj

And here we've got structure similar to this:

All the output xml files from the batch commands will be used by Hudson to show us results of running unit tests, checking code style, etc.

Installing Hudson: Installation

At this point we are ready to install the Hudson. We'll install Hudson as a Windows service on Windows.

  • Prepare working directory

Create directory

In this directory Hudson will be installed. From the Windows control panel set up system environment variable:

Open new command prompt and test the new variable:
C:\>echo %HUDSON_HOME%

In this directory Hudson will check out from Subversion our code and will run the jobs to compile and run unit tests. So, this will be the Hudson's working directory. There Hudson will accumulate files with historical information.

  • Install Hudson

Create directory where to install the Hudson server:
C:\Program Files (x86)\Hudson

Download into this directory the latest version of Hudson from:

Note: you can always upgrade Hudson automatically to the latest version directly from the Hudson's web console - after the Hudson installed as windows service.

Rename the file as removing the version information from the file name. Check the install directory of the Hudson server:

C:\Users\Administrator>dir "C:\Program Files (x86)\Hudson"
08/20/2011  09:24 AM    <DIR>          .
08/20/2011  09:24 AM    <DIR>          ..
08/20/2011  09:23 AM        38,948,136 hudson.war

  • Run Hudson

Now open a command prompt and go to this directory, run the Hudson server from there:

java -jar hudson.war
C:\Program Files (x86)\Hudson>java -jar hudson.war
Running from: C:\Program Files (x86)\Hudson\hudson.war
[Winstone 2011/08/20 14:11:50] - Beginning extraction from war file
Aug 20, 2011 2:11:52 PM hudson.WebAppMain contextInitialized
It will start doing  thinks, just wait until it says: "Completed initialization".
INFO: Home directory: C:\Hudson

note: look on the log messages, somewhere at the beginning it should say:

hudson home directory: C:\Hudson

Hudson will start by default HTTP web server on port 8080, open the following URL into your web browser, this is the Hudson's console there:

  • Install as windows service

Click on Hudson/Manage Hudson, then on “Install as Windows Service”. It will take time to finish.

Watch the application on the command prompt, it will restart as windows service. After the installation complete confirm to restart.

You can close the window with the command prompt. From here on only work happens on the web interface of Hudson!

Note: You can delete the service using this command:
sc delete hudson

Note: Later you can always upgrade to the latest version your copy of Hudson.

From the web console of Hudson go to Hudson\Manage Hudson and click on "Upgrade Automatically".
Wait for Hudson to finish the installation.
Click on "Restart when no jobs are running".

  • Install Plug-Ins

Go to Hudson\Manage Hudson and click on Manage Plugins. Click on "Available" and select:
MSBuild Plugin
NAnt Plugin
NUnit Plugin
Analysis Collector Plugin
Static Code Analysis Plug-ins
Task Scanner Plugin
Warnings Plugin

Scroll down the page and click on "Install". After Hudson installed all those plugins, click on "Restart when no jobs are running".

Go to Hudson\Manage Hudson\Pugin Manager, open tab Installed and check if all these Plugins are installed:

Go to Hudson\Manage Hudson and click on "Configure System".
Scroll down to "MSBuild Builder" and click on "Add".

Write for name "MSBuild Dot.NET 4.0".
Write for path the full path name of the msbuild.exe file for Dot.NET 4.0, in our case it was

You can add for other Dot.NET frameworks if you need. Later from the concrete jobs you'll use them as appropriate in your case.

Scroll down, click "Save".

Configure Hudson: Add Jobs

Now we can add our project for continuous integration as a job on the Hudson server.

  • Continuous build

This is a build which will be checking every minute for changes in the Subversion repository, if they are some changes will check out the latest changes, build our project and run the unit tests.

Click on Hudson\New job. Set the name of the job, in this example "WebAPI continuous build" and select the option "Build a free-style software project". Click on "OK".

In section "Source Code Management" select "Subversion". Set the Repository URL as appropriate.

Move the focus to another field. Hudson will try to access your Subversion server and if the authentication failed will show red colored message next to the text box with the repositiry URL. The message should contain an html link "enter credentials". Click the link and follow the instructions. Eventually you'll be able to give your user name and password if you choose this form of authentication.

Once you successfully finish this, you'll come back to the previous page.

In section "Build Triggers" select "Poll SCM" and specify "*/1 * * * *" to check every minute for changes in the source repository.

In section "Buld" click on "Add build step", then "Build a Visual Studio project or solution using MSBuild". Select/write (we are following the example file and VS project names from above):
MsBuild Version   : MS Buld Dot.NET 4.0
MsBuild Build File :  WebAPI.sln
Command line arguments :  /p:Configuration=DEBUG

Click on "Add build step", then on "Execute Windows batch command". Write:

In section "Post-build Actions" select "Publish NUnit test result report and enter for "Test report XMLs:


Click on Save to save the job. In short time Hudson should start a build for this job. If the build failed, check the "Console Output" from the job menus.

Note: you can at any time schedule run for a job. Go to the home page of the tool, click on the link to the job "WebAPI continuous build", from the left-side menus click on "Build now".

You can check the result of your unit tests from the link "Latest Test Result". Also you can browse your source code tree from the "Workspace" link and check for latest changes from the link "Resent Changes".

Now that we added a build project we've got nice dashboard on the home page of our Hudson server:

  • Extended build

This is a build which will run once in a day and will run code-style checks and will create documentation for the API.

Click on Hudson\New job. Set the name of the job, in this example "WebAPI extended build" and select the option "Build a free-style software project". Click on "OK".

In section "Source Code Management" select "Subversion". Set the Repository URL as appropriate.

Move the focus to another field. Hudson will try to access your Subversion server and if the authentication failed will show red colored message next to the text box with the repositiry URL. The message should contain an html link "enter credentials". Click the link and follow the instructions. Eventually you'll be able to give your user name and password if you choose this form of authentication. Once you successfully finish this, you'll come back to the previous page.

In section "Build Triggers" select "Build periodically" and specify "40 02 * * *" - just an example - to run the job once a day at 02:40 PM.

In section "Buld" click on "Add build step", then "Build a Visual Studio project or solution using MSBuild". Select/write (we are following the example file and VS project names from above):
MsBuild Version   : MS Buld Dot.NET 4.0
MsBuild Build File :  WebAPI\WebAPI.csproj
Command line arguments :  /p:Configuration=DEBUG

Note: this only is going to build the project with production code, we don't need to build the complete Visual Studio solution, but won't be wrong as well.

Add one after other the following Windows batch commands clicking on the button "Add build steps" as "Execute Windows batch command":




From the "Post-build Actions" section select "Publish Javadoc" and enter "help" as "Javadoc directory".

Then select "Report Violations" and configure the rows for fxcop and gendarme reports as appropriate.

Click on "Save" button down the page.

Click on "Build now" from the left-side menus of the project.

Once the build finished you can check for the generated documentation and the code violations.

Take some time to explore both of them, you'll find very useful suggestions in there.

Hudson: Links

Hudson CI Server:

Links to some of the Plugins we mentioned:
MSBuild Plugin:
NAnt Plugin:
NUnit Plugin:
Analysis Collector:

Atanas Hristov

Shout it

Thursday, February 3, 2011

TDD with jsTestDriver - find image size with Java Script

In my last post I created small java script function that finds the size of image by URL. I used YUI 3 test framework for doing unit tests while I worked on that function.

Because YUI 3 test framework is in-browser framework we are facing the challenge how to automate our unit tests and how to apply TDD with automated continuous build and automated continuous integration. As we have to manually re-run tests it is a challenge to keep testing our java script on several web browsers on different platforms.

jsTestDriver is automation tool for unit testing for java script. It is a server written in Java. From several several browsers you open URL hosted on the jsTestDriver server. The jsTestDriver can then automatically re-run the unit tests whenever they are some changes in the source code and thereof shows if the unit tests failed or passed on the currently connected web browsers. That way you can test as many as you like combinations of browsers and platforms in an automated way.

I'll be working on Linux for the examples, but the jsTestDriver works on Windows too. Also, it is always a good idea to develop your java script libraries outside your web projects and ideally to use in your web projects already tested, optimized and minified java script file.

The installation of jsTestDriver is very simple. Download the jar file from the project's web site:

Just copy the jar file on directory where it is convenient for you. Here is a snipped from my directory structure:

ahristov@medion:~/Desktop/Projects/js/bin$ ls
compiler.jar  JsTestDriver-1.2.2.jar  SoyToJsSrcCompiler.jar

You should export environment variable $JSTESTDRIVER_HOME (%JSTESTDRIVER_HOME% on Windows, go to My Computer -> Properties -> System -> Advanced and change the Environment Variables to make the changes permanent).

ahristov@medion:~/Desktop/Projects/js/bin$ cat ~/.bashrc | tail -n 7

export PATH=".:$HOME/bin:$PATH:/var/lib/gems/1.9.1/bin"
export JSBIN="$HOME/Desktop/Projects/js/bin"

The directory structure for our small project looks like this:

ahristov@medion:~/Desktop/Projects/js/proj/play$ ls
build  deps  jsTestDriver.conf  src  test

As I mentioned in my last post build you can ignore, I normally have build directory where I would generate minified, tested java script - the stuff that I'll be using in my web project. We don't need the deps folder this time, as we will not have any dependencies on 3rd party java script.

The file jsTestDriver.conf is a configuration file for the jsTestDriver with the following content:

ahristov@medion:~/Desktop/Projects/js/proj/play$ cat jsTestDriver.conf
server: http://localhost:4224

- src/*.js
- test/*.js

It states, we'll run the jsTestDriver on port 4224, the server will load all the java script files from directories src and test. All the load paths are relative to the directory where the jsTestDriver.conf file is. Please note that the order the directories and file names are important. In our case the jsTestDriver will first load the source code java script files, then the unit test java script files. More information for the jsTestDriver configuration file you can find on the projects wiki page:

src - this directory holds just one java script file in which is the source code of function ImgSize()

ahristov@medion:~/Desktop/Projects/js/proj/play$ cat src/ImgSize.js
* Calculate the size of image.
* @param {string} url Url of the image which size to find
* @param {function(number, number)} onSizeCalculated Callback function to run once
*   the size of the image calculated
function ImgSize(url, onSizeCalculated) {

// Once the image is loaded, the calls the callback function onSizeCalculated
function setDimensions() {
// scope changed: this = Image object
if (onSizeCalculated) {
onSizeCalculated(this.width, this.height);

// Initialization:
// - sets callback on image loaded - setDimensions;
// - loads the image.
function init() {
var img = new Image(); = url;
img.onload = setDimensions;
img.src = url;

// Run initialization

This is the same function that we developed and tested with the YUI 3 test framework in my last post.

test is the directory where the java script files with the unit tests are

ahristov@medion:~/Desktop/Projects/js/proj/play$ ls test/
ImgSize  ImgSize.html  ImgSize-test.js
ahristov@medion:~/Desktop/Projects/js/proj/play$ ls test/ImgSize

File ImgSize.html is from my last post, you can ignore it for now. The file 137x38.gif is an image with the size 137px / 38px which I'll use for the purpose of the unit testing.

If we were about to test synchronous java script we would use the traditional TestCase runner. Our ImgSize-test.js would look like:

// holds tests for the ImgSize() function
TestCase("ImgSizeTest", {
"test image size should be 137x38": function() {
new ImgSize('',
function assertOnSizeCalculated(width, height) {
assertEquals(137, width);
assertEquals( 38, height);

How that we are going to test asynchronous calls we should use the AsyncTestCase runner, so that our ImgSize-test.js contains:

var ImgSizeTest = AsyncTestCase('ImgSizeTest');

ImgSizeTest.prototype.testImgSizeFunction = function(queue) {


var onSizeCalculated = queue.add(function() {
assertEquals(137, arguments[0][0]);
assertEquals( 38, arguments[0][1]);

new ImgSize('',

The queue parameter accepts inline function via method add(), the function will run whenever the browser downloaded the image and calculated the size of the image.

As you can see, the image file should be accessible from URL from the testing browsers, so I just put the gif image on web server on the following URL above. Keep in mind, you have to adjust that the way you need it.

The syntax is very similar to YUI 3 test and even simpler. Whenever the browser loaded the image, we are going to check if the ImgSize() function gets the proper image size information. Please note that we are not dealing with DOM and UI. If you want to test DOM operations you can add HTML to the unit test files, for more information check the wiki pages of the jsTestDriver project:

The page containing documentation for asynchronous unit tests with jsTestDriver is:

How it is time to start the jsTestDriver server:

ahristov@medion:~$ java -jar $JSTESTDRIVER_HOME/JsTestDriver-1.2.2.jar --port 4224

Next step is to open the URL where the jsTestDriver server is listening:

Enter the URL to the server in the web browser and click in "Capture This Browser"

This browser started waiting for automation from the server to run unit tests. Let's add another browser to the testing:

Clicking on "Capture This Browser":

Connect several web browsers to the jsTestDriver server.

As we are ready to start our unit tests, we have to first run the jsTestDriver server. From the directory where the configuration file jsTestDriver.conf is we run:

ahristov@medion:~/Desktop/Projects/js/proj/play$ java -jar $JSTESTDRIVER_HOME/JsTestDriver-1.2.2.jar --tests all

Which gets the following output:

The test passed on 3 different browsers.

Now, how to repeat the tests automatically whenever the source code of our java script changed?

If you have Ruby installed on your system, you can install the jstdutil package:

gem install jstdutil

It provides a wrapper to jsTestDriver so instead of writing every time this long command lines on the shell, you just - from the directory where the jsTestDriver.conf file is run:

ahristov@medion:~/Desktop/Projects/js/proj/play$ jsautotest

Every time we do changes on our java script source code the jsTestDriver will automatically start doing the unit tests and then will report the result:

Let's change the test, make the test fail, change the following line:

assertEquals( 38, arguments[0][1]);


assertEquals( 39, arguments[0][1]);

as the jsautotest is running. At the moment we save the javascript file, jsautotest automatically re-runs the tests sending the appropriate command to the jsTestDriver server and all currently captured browsers start running the tests. We get error in our tests and the jsautotest console explains this with output similar to:

Changing the assert back from 39 to 38 in the ImgSize-test.js makes jsautotest again to re-run the tests on the jsTestDr4iver server, and this time they successfully pass.

The jsTestDriver project has the following URL:

The home page of the jstdutil Ruby package:

Atanas Hristov

kick it on
Shout it