Gojko Adzic

At the Oresund Developer conference in Sweden about two months ago, Aslak Hellesoy talked about recent changes to his Cucumber Behaviour-Driven Development tool, aimed at providing better support for platforms other than Ruby. Instead of using the tool through slow Ruby ports, .NET and Java developers got a chance to benefit from much quicker native integrations using a new wire protocol that allows Cucumber to talk to external systems. Richard Lawrence and Matt Wynne were very kind to work on a native .NET integration for Cucumber, called Cuke4Nuke, which recently got up to speed with Cucumber Ruby features. In this article, I’ll show you how to set up and use Cuke4Nuke to use Cucumber for .NET BDD development.

Basic Software

• If you don’t already have Ruby installed, install it using the new one-click Ruby Installer. You don’t have to know Ruby to write Cuke4Nuke tests, but you still need it to run Cucumber. Install the Ruby development kit as well. Alternatively use the old 1.86 installer which comes with the development kit.
• Add GemCutter.org to the list of Ruby Gem sources. Execute the following command from the command line:

  gem sources -a http://gemcutter.org/

• Install the Cuke4Nuke gem. Execute the following command from the command line:

  gem install cuke4nuke

• Install the Win32Console gem to get colour reports in the windows console window:

  gem install win32console

  You might also need WAC to work around console colour problems so download that Exe and put it somewhere on the disk.

• If you don’t already have NUnit, grab the latest version from NUnit.org. We’ll need this later as Cuke4Nuke uses NUnit assertions.

To verify that the system is set up, execute Cuke4Nuke from the command line. You should see a help screen with Cuke4Nuke options. If you see an error that the command Cuke4Nuke isn’t found, check if there is a Cuke4Nuke.bat executable in your Ruby bin folder (C:\Ruby\bin if you accepted the default installation options for Ruby), whether that folder is on your executable path and whether Cuke4Nuke gem exists in the gems folder (C:\Ruby\lib\ruby\gems\1.8\gems\cuke4nuke-0.3.0 on my system).

Project setup

Create a normal C# class library project and add a Features folder to it. This is where your Cucumber scenarios will go. Add a step_definitions subfolder to that and create a file called cucumber.wire, with the following content:

host: localhost
port: 3901

This tells Cucumber to connect to an external system on port 3901, the default port for Cuke4Nuke. Now let’s add a test scenario to make sure that everything is working correctly. Create a file called basic.feature in the Features folder, with the following content:

Feature: Hello World
	In order to ensure that my installation works
	As a Developer
	I want to run a quick Cuke4Nuke test

	Scenario: Hello World
		Given The Action is Hello
		When The Subject is World
		Then The Greeting is Hello, World.

At this point, your project structure should look as on the picture below:

Now let’s run Cuke4Nuke for the first time. Build the project, open the console, go to your project folder and run the following command:

Cuke4Nuke bin\debug\Cuke4NukeExample.dll -q

(replace the DLL path with your project output DLL). You should see the Cucumber output telling you that there is one scenario with three steps, all of which are undefined. If you do not see the colours, add the -c flag and pipe the output to WAC.exe, making the command similar to the following:

Cuke4Nuke bin\debug\Cuke4NukeExample.dll -q -c | d:\apps\wag.exe

In any case, the command result should be similar to one on the picture below:

Now let’s add the step definitions that help Cucumber talk to our project code. Create a C# class file (say Steps.cs) and paste the following code:

using System;
using System.Text;
using Cuke4Nuke.Framework;
using NUnit.Framework;
namespace Cuke4NukeExample
{
    public class HelloWorldSteps{
        private String action;
        private String subject;
        [Given("^The Action is ([A-z]*)$")]
        public void ActionIs(String action)
        {
            this.action = action;
        }
        [When("^The Subject is ([A-z]*)$")]
        public void SubjectIs(String subject)
        {
            this.subject = subject;
        }
        [Then(@"The Greeting is ([^\.]*).")]
        public void CheckGreeting(String greeting)
        {
            Assert.AreEqual(greeting, action + ", "+subject) ;
        }
     }
}

Add a reference to NUnit.Framework.dll (from your NUnit installation) and Cuke4Nuke.Framework.dll (you’ll find it in C:\Ruby\lib\ruby\gems\1.8\gems\cuke4nuke-0.3.0\dotnet\Cuke4Nuke.Framework.dll). Now build the project again, go to the console and re-run the Cuke4Nuke command. The output should now say that the steps passed.

When it runs the feature specification, Cuke4Nuke will look for methods marked with Given, When and Then attributes that match steps by regular expression. Any capture groups in the regular expression are passed to the method as arguments (they don’t have to be Strings, you can use other .NET types as well). So, for example, the line “When The Subject is World” matches the following method:

[When("^The Subject is ([A-z]*)$")]
public void SubjectIs(String subject)
{
     this.subject = subject;
}

Our simple script will set the subject and the action and then verify the greeting using the standard NUnit assertion Assert.AreEqual. Just to see it when it fails, modify the CheckGreeting method or feature source so that they don’t match and re-run Cuke4Nuke.

Of course, for a proper project this code would talk to our domain classes but let’s keep it simple.

Build integration

We can add Cuke4Nuke as a post-build step so that all the specifications get executed after every build. Open your project .csproj file and add this just above the closing tag:

<PropertyGroup>
<PostBuildEvent>cuke4nuke $(TargetPath) $(ProjectDir)features -q
 </PostBuildEvent>
</PropertyGroup>

You can now inspect the results of Cuke4Nuke in your output window every time a project is built.

Continuous Integration

To complete the project setup, let’s run Cucumber tests within a continuous integration environment and store test outputs next to project build results. I use TeamCity even for .NET projects, so I’ll use it in this tutorial as well. (Setting up TeamCity is outside the scope of this tutorial, but it is fairly easy to do. Grab it from jetbrains.com). TeamCity 5 should support Cucumber out of the box but I haven’t been able to make it work. Cucumber/ANT docs for TeamCity suggests that a few environment variables should do the trick for ANT/Java builds but this doesn’t work for Cuke4Nuke. The Cucumber Teamcity template uses a deprecated API and fails to build with the latest Cucumber version, and the only other blog post I found on TeamCity and Cucumber uses the same (broken) API. However, Cucumber can export a JUnit XML test report file, which is more than enough to get us nicely integrated with TeamCity (even with the previous versions). We’ll make Cucumber save the test results into the test subfolder of our project folder, and tell TeamCity to monitor that. First, let’s change the .csproj project file. Modify the PropertyGroup block you just added to the following:

  <PropertyGroup>
    <PostBuildEvent>cuke4nuke $(TargetPath) $(ProjectDir)features -q
     -f junit -o$(ProjectDir)test</PostBuildEvent>
    <PreBuildEvent>del $(ProjectDir)test\*.xml</PreBuildEvent>
  </PropertyGroup>

This will save test output in the JUnit format (-f junit) into the test subfolder of our project directory (-o$(ProjectDir)test). It will also delete any previous test results from that folder when the build starts. Now set up your TeamCity project as normal. On the Build Runner configuration screen, select “ANT Junit” in the “XML Report Processing” section and set the import path as test/*xml (if you are working without a version control system, this will probably have to be a full path to your project folder rather than a relative path):

Everything should now be set up. You should be able to run the TeamCity build and get the “Tests passed:1″ message in TeamCity.

That’s it. Now continue writing feature specifications and implementing them in nice little iterations. Good luck! If you’re interested in this topic, you might also be interested in my new BDD with Cucumber workshops.

• BDD in .NET with Cucumber part 2: Making scenarios easier to read with tables
• BDD in .NET with Cucumber part 3: Scenario outlines and tabular templates
• Download source code

Get notified when I post something new - subscribe via RSS or Twitter!

Trackback URI | Comments RSS