Saturday, May 30, 2009

Your First Concordion.Net Project (Part 5)

Running Specs with Gallio

Part 1Part 2Part 3Part 4

We have our specifications developed so now we want to actually run this beasty! After trying to develop my own test runner for Concordion I decided to settle on writing a plugin for the Gallio framework instead.

Gallio is an open testing framework that runs all sorts of .Net test frameworks on a number of different platforms. You can find out more about its adaptability and rich reporting capabilities here.

So how do we get Gallio to run our specifications? We need to use a plugin. In the Concordion distributable file you will notice a directory called Gallio.ConcordionAdapter. This is the plugin specifically written to allow Concordion specifications to be run on Gallio.

What I like to do when running specifications is to start off by running them with Gallio.Echo. This is the command-line executable and I find this easiest to debug problems with. There are a number of other runners for Gallio (like Icarus (the GUI); or runners for Visual Studio, Test-Driven.Net, etc.).

I like to create the specification file in the root directory of the specification project so let’s do that right now. Here’s the file in the Calculator.Spec project folder

Calculator.Sample.11

The file is called run-spec-with-echo.cmd … as you can tell I really like long and descriptive names!

Now let’s fill this up with a command-line. We will need to tell Gallio where to find the Gallio.ConcordionAdapter plugin and where to find our specification assembly. This folder has contents like this:

Calculator.Sample.12

To tell Gallio to find this directory we add the command-line option

/pd:c:\Concordion\Gallio.ConcordionAdapter

This tells Gallio to search in this directory for a .plugin file that it can use to work with the Concordion plugin. Now we need to tell Concordion where our specification assembly is.

bin\Debug\Calculator.Spec.dll

Since the batch file is in our project directory but our specification assembly is in the project output folder we need to add the relative path to the specification assembly. Unless otherwise specified, Gallio.Echo’s working directory is the current folder. Our command file should now resemble this

set GALLIO_PATH=C:\Dev\concordion-net\tools\Gallio-trunk\bin
%GALLIO_PATH%\Gallio.Echo.exe /pd:c:\Concordion\Gallio.ConcordionAdapter bin\debug\Calculator.Spec.dll
pause

So let’s try and run the file! If you do you should see the following results on screen

Calculator.Sample.13

Uh oh … Houston we have a problem! Notice that there is a failure in our specification. If you remember back to the last post we intentionally made our ArithmeticTest fixture a dumb one so that we could see it fail.

Fixing the Fixture

Red-Green-Refactor is the name of the game here! Ok, let’s fix up our test by filling out the Calculator class in our Calculator project and calling that from the specification to perform the arithmetic operations. Our Calculator class should resemble this:

public class Calculator
{
public long Add(long first, long second)
{
return first + second;
}

public long Subtract(long first, long second)
{
return first - second;
}

public long Multiply(long first, long second)
{
return first * second;
}

public long Divide(long first, long second)
{
return first / second;
}
}

And we will want to modify our fixture like so

    [ConcordionTest]
public class ArithmeticTest
{
public long firstOperand;
public long secondOperand;

public long Addition(long first, long second)
{
return new Calculator().Add(first, second);
}

public long Subtraction(long first, long second)
{
return new Calculator().Subtract(first, second);
}

public long Multiplication(long first, long second)
{
return new Calculator().Multiply(first, second);
}

public long Division(long first, long second)
{
return new Calculator().Divide(first, second);
}
}

Ooops … we forgot something! Did you notice? For the above code to work we need to add a reference to the Calculator project in the Calculator.Spec project

Calculator.Sample.14

Good, now we have our reference so it should compile and run successfully now. Let’s see how it goes.

image

Woot! All of our tests now pass! Let’s take a peek at the output now.

image

Notice the green surrounding the results now? That means our Calculator class successfully performs the arithmetic we want!

Epilogue

If you want to see the source code for this series of posts you can download it here.

This sample was pretty basic but it should be enough to get you up and running!

Thanks for trying out this tool, I hope you enjoy it. Stay tuned, there will be more to come on advanced features of Concordion!

Thursday, May 28, 2009

Your First Concordion.Net Project (Part 4)

More Specifications!

Part 1Part 2Part 3Part 5

In the previous post we got our project set up and added the first specification.  The sad part was it didn’t really do much.  It only acted as a gateway into our other specifications.  Let’s add something a bit juicier!

In the gateway specification document (Calculator.html) we put a link to an Operations.html specification.  Let’s add that now.  Remember to add the .html and class file then set the properties on the .html file as per the gateway specification and set up the fixture just like the CalculatorTest class.

Calculator.Sample

The content of Operations.html should resemble this when finished

Calculator.Sample.8

Now we have a document describing the various operations that we can perform.  So let’s add two more specifications: one for the arithmetic and one for the trigonometric.  Your project should now look like this:

Calculator.Sample.9

Did you remember to set the .html and .cs files up like the others? I hope so … otherwise you’re in for some heartache :-)

Arithmetic Operations

Let’s add some basic arithmetic operations to our specification: addition, subtraction, multiplication, division.  The specification file is much like our other specification files excepting that it now contains some special markup.  Here is an excerpt from the page’s Multiplication example:

<h3>Example - Multiplication</h3>

<p>
    The result of <b concordion:set="#firstOperand">2</b> * <b concordion:set="#secondOperand">2</b>

    the result will be:
    <b concordion:assertEquals="Multiplication(#firstOperand, #secondOperand)">4</b>
</p>

The rendered html file will resemble this:

Calculator.Sample.10

You can see the source in the included project but the items to note are the concordion:set and the concordion:assertEquals attributes.  concordion:set is used to set a value of a public field or property in the fixture class.  The assertEquals checks the value in the element (the expected value) against the value returned by the operation defined in the concordion:assertEquals attribute.  It is the concordion:assertEquals that will actually turn red or green (maybe yellow, but hopefully not yellow … cross your fingers!)

Creating the fixture

Now that we have a specification, we need some code in the fixture to back it up!  So let’s add some.  Note that this code is going to fail.  True TDD practitioners follow the red-green-refactor methodology so we will try and follow suit.  Our fixture code will look like this:

[ConcordionTest]
public class ArithmeticTest
{
    public long firstOperand;
    public long secondOperand;

    public long Addition(long first, long second)
    {
        return -1;
    }

    public long Subtraction(long first, long second)
    {
        return -1;
    }

    public long Multiplication(long first, long second)
    {
        return -1;
    }

    public long Division(long first, long second)
    {
        return -1;
    }
}

We should now have a complete fixture that should be able to run, albeit with some errors!

Next time we will work on how to run your project with Gallio and produce some results so that we can refactor the above code and turn it into something more meaningful!

Monday, May 25, 2009

Your First Concordion.Net Project (Part 2)

Setting Up Visual Studio

Part 1Part 3Part 4Part 5

If you’re a diligent .NET Developer then you have probably read Microsoft’s guidelines for setting up a Visual Studio project. If you have read this then I would also point you towards this excellent posting

Most Concordion.Net projects should follow the same basic structure of three assemblies:

  • <project-name> – the assembly containing your business logic
  • <project-name>.Test – an assembly for your unit tests
  • <project-name>.Spec – an assembly for your Concordion.Net specifications.

In our example we will be creating a project called Calculator. This will be a very simple project that contains only a calculator class API for others to use in their own code. Yes, I know this is a very simple example but it will have to do for now because I’m not feeling very imaginative! With Calculator we will have the following three projects:

  • Calculator
  • Calculator.Test
  • Calculator.Spec

Calculator.Sample.1

This will be the basic structure of our assembly. While I normally use xUnit for my open source projects I won’t be covering the Calculator.Test project much more than to say that you should have one there, it’s more for completeness.

We will talk about adding references later on as they’re required.

The ConcordionAssembly Attribute

One of the very first things you need to do on any Concordion.Net project is to mark your assembly with a ConcordionAssembly attribute. This allows Gallio (the thing that runs the specifications) know that this assembly contains Concordion specifications. If this attribute is not present then your tests will not be found. You can mark the assembly like this

[assembly: ConcordionAssembly]

place this declaration in the AssemblyInfo.cs file of the Calculator.Spec project.

The next part in this series will talk a bit about how to add specifications to the Calculator.Spec project.

Your First Concordion.NET Project (Part 1)

What is Concordion.Net?

Part 2 - Part 3Part 4Part 5

So, you’ve stumbled across Concordion or Concordion.Net on the internet, maybe liked the style of specification writing Concordion promotes and now you want to do something with it! So where to begin … ?

  • Read about Behaviour Driven Development on Dan North’s classic blog post.  This post describes the basic ideas behind behaviour-driven development and is very informative.
  • Read about Concordion technique on the main Concordion web page.  No matter what testing framework you choose it is important to get the basics down before attempting to use it.
  • Read through the Concordion.Net wiki.  It is still growing but there is some useful information there on how to setup Concordion.Net, what the version compatibility is with the Java version, etc.

The next part in this series will detail how to setup Visual Studio to prepare for your Concordion.Net project.

Your First Concordion.Net Project (Part 3)

Adding Specifications

Part 1Part 2Part 4Part 5

As with any sort of Test-Driven Development or Behaviour-Driven Development we should start by writing our tests or specifications first.

First, let’s do some basic setup of our specification assembly, Calculator.Spec.

Style Sheet

I like to cheat a little bit and steal from David’s style sheet included with the original Concordion. It’s simple, clean and very easy to read so we’ll use it. You will want to drop it at the top level of your Calculator.Spec project. You should change the Build Action on this file to Embedded Resource and set the Copy To Output Folder action to Copy Always.

This will ensure that the style sheet file is always included with the output when you build. Here is what it looks like

Calculator.Sample.2

Folder Structure

Now that we have a style sheet we need a place to put our documentation. I like to have a top-level folder that is used as an entry point to all of the other fixtures. So let’s make a folder at the top-level of the Calculator.Spec project and call it Calculator. In this folder we will place two files: Calculator.html and CalculatorTest.cs

Calculator.html will be our HTML specification and CalculatorTest.cs will be the fixture class for Calculator.html. Note the naming convention here: The fixture name is the specification with the word ’Test’ appended. You should now see something like this

Calculator.Sample.3

Filling in the Specification

The next step is to fill in the specification html file. To do this I will do a little more cut and paste magic from the main Concordion.Net specifications. You will want to replace the DOCTYPE and HTML tags that Visual Studio inserts with the following statement
<html xmlns:concordion="http://www.concordion.org/2007/concordion">

This statement declares the xml namespace for all of the concordion elements that we will be decorating our HMTL with.

Note: while I intend for Calculator.html to be a specification that doesn’t actually check anything I am still declaring the xml namespace. This is because it is required by Concordion.

Now we should add a link to our style sheet at the root of our folder structure like so

<link href="../concordion.css" rel="stylesheet" type="text/css" />

Now we can start adding text. I will add a little blurb about our calculator on this page and then add some “Further Details” reference links. In the end our Calculator.html page should resemble this

Calculator.Sample.4

Last, but not least, you will need to set the Build Action to Embedded Resource and the Copy To Output Folder action to Copy Always

Calculator.Sample.6

IMPORTANT: You should set those two properties on every html specification file you write! If you do not then they will not copy tot he output folder and Concordion.Net will not be able to find them.

Writing the Specification

We haven’t actually written any code to support this fixture yet so we should probably do that next! The discerning reader may even be wondering why haven’t we added a reference to Concordion.Net yet? We must add a reference to Concordion.Net to the project now. I will create a folder at the level of the solution called ‘lib’ and place the Concordion.Net assembly there and then add a reference to it in the project.

Calculator.Sample.5

Now we will need to open up CalculatorTest.cs and do some touch-up work to it so that Concordion.Net can find it properly:

  1. Make the class public. If you do not it won’t be exported and if it isn’t exported then the test runner will not find it. Then you will be sad and I will be too!
  2. Decorate the class with the [ConcordionTest] attribute. This tells the test runner that this class is intended to be a test. It also allows you to use other classes that support the tests without the test runner trying to find and run them.

Your final class should look like this

using Concordion.Integration;
namespace Calculator.Spec.Calculator
{
[ConcordionTest]
public class CalculatorTest
{
}
}

One last thing … Concordion Files and Namespaces

Concordion has to have some means of linking a specification with a fixture class. The way that Concordion.Net does this is based on the namespace of the class. Thus, if a class has a fully-qualified name of Calculator.Spec.Calculator.CalculatorTest (like above) then Concordion.Net will look in the path Calculator\Spec\Calculator for the Calculator.html file.

Since we are embedding our specifications and they will be copied directly to the output it is necessary to modify the namespace a bit so that Concordion.Net can link the fixture to the specification. We do this by trimming the namespace like so:

using Concordion.Integration;
namespace Calculator
{
[ConcordionTest]
public class CalculatorTest
{
}
}

Notice that namespace has been reduced to just Calculator? Now Concordion.Net will look for Calculator\Calculator.html which is exactly where the html file will be when the project is built.

Next we will look at how to add some real specifications … that actually run tests!