Executable specifications are scenarios created by developers, testers and stakeholders working in collaboration that check the behaviour of a system every time code is committed. For more information and a podcast about Executable specifications check out this Hanselminutes episode ‘Executable Specifications with Gojko Adzic, Jonas Bandi and Aslak Hellesoy’.

The need for change

A few months ago after joining the team, there was a lot confusion how a previous project worked.

Stakeholders weren’t sure what functionality had been implemented, testers weren’t sure if everything had been tested and developers didn’t want to go anywhere near the code.

While there was a wiki no one was sure if was 100% accurate which meant it could do more harm than good because it could lead to false assumptions.

As a result of this the relationships between the groups had suffered.

Inspired by Dan North’s talk ‘How to sell BDD to the business’ I suggested using BDD (behavior driven development) and executable specifications to help prevent this happening in the future.

Testers and business owners were open to the idea but were skeptical to how valuable it would be.

So we decided to try it out on a small part of the project.

And it worked!

Working collaboratively we found relationships started to improve and there was a lot more trust between the groups.

At the end of the project stake holders, testers and developers agreed executable specifications were an excellent way to develop software and keen to adopt the approach for other projects.

So what sold executable specifications to the stakeholders, testers and developers?

• Scenarios that matched the business problems the stakeholders wanted to solve.

  This gave stakeholders confidence and lowered fear and resistance to change.

• Easy to read scenarios that matched the domain language the stakeholders were using.

  Stakeholders could relate to scenarios and therefore felt involved.

• Using scenarios to fill out the blanks.

  When the test team or developers found new scenarios they communicated using with stakeholders leaving out what should happen (the then step) for them to fill in.

• The use of tables.

  Tables allow the reader to visualise the data, reduce reputation and mean you don’t have to cram in lots of words.

  For example instead of having

  Scenario: Submitting form with invalid password displays error
    Given I am on the registration page
    When enter the password 'a'
    And submit the form
    Then I should see the message 'Passwords must be 8 to 16 characters long and include at least one capital letter, one lower case letter, and one number'
  

  and then repeating this for every permutation of invalid passwords, you can do this

  Scenario: Entering an invalid password displays error
    Given I am on the registration page
    When enter the password
      | a						|
  	| aaaaaaaa				|
      | AAAAAAAA				|
  	| aaaaAAAA				|
  	| 12345678				|
  	| 1234567A				|
  	| 1234567a				|
  	| 12345678aaaaaaaaA		|
    And submit the form
    Then I should see the message 'Passwords must be 8 to 16 characters long and include at least one capital letter, one lower case letter, and one number'
  

  We found this gave us valuable input from stakeholders and testers who were able to come up with scenarios much faster than before.

• Living documentation.

  Running tests to ensure the scenarios still reflected the behaviour of the system after every code change meant documentation was reliable and accurate.

The future

I’m pleased stakeholders, testers and developers have recognised the value of using BDD, scenarios and executable specifications.

By taking small steps, inspecting and adapting along the way, I hope that more projects I work on can adopt this approach.

One thing that has stuck in my head ever since has been her tip about getting people to draw a picture to represent how the sprint went.

The fact that it’s simple and easy to do is what makes it’s great.

She gave two examples, one was a group of people climbing half way up a very steep mountain and the other was a stretched limousine packed full of people without a driver.

This is definitely worth trying out in your retrospectives becuase it’s an excellent way to lighten the mood and get people contributing.

Whether you decide to keep it anonymous or not is up to you.

Here’s a drawing I’ve shown in a retrospective.

Since that day I’ve noticed that parenting shares many similarities with agile development.

I say this becuase from the moment a baby enters the world it’s all about inspect and adapt.

You’re forever analysing what they’re doing, checking they’re alright and planning and pirotising what to do next.

And while friends, parents and books give sound advice you have to look at your own context, every baby is different and so not every tip will work.

And this is when you’ll start doing mini retrospecives as parents. Every so often you’ll sit down with your partner discuss what went well, what didn’t and what to try next.

Using short feedback cycles you’ll soon work out what works best with the aim of developing sort form of structure.

You can’t do this waterfall becuase babies are unpredicatble and constantly changing.

As soon as you think you sussed it and plan too far ahead, the baby will go thru a growth spurt or learn something new and you’re back to square one before you know it.

It’s like a game of snakes and ladders, you’ll look at your partner and say this didn’t happen yesterday.

We’re four months in by working together and constantly sharing throughts and ideas we’re developing a routine which can cope with changes and… getting more sleep as each week passes!

While it’s not open source it’s definitely worth the investment if you use NHibernate because it can give you alerts about any potential issues and information about how to resolve them.

Something that a profiling tool like SQL Profiler just can’t do.

For example by running the code below to insert 200 apples and then retrieve them from the database

Note: this code is meant to be written like this to generate alerts

[Test]
public void NHibernate_Profiler_Demo()
{
    using (IStatelessSession session = FruitDatabase.SessionFactory.OpenStatelessSession())
    {
        using (ITransaction txn = session.BeginTransaction(IsolationLevel.ReadCommitted))
        {
            for (int i = 0; i < 200; i++)
            {
                var apple = new Fruit() { Name = "Apple" };
                session.Insert(apple);
            }
            txn.Commit();
        }
    }
    using (IStatelessSession session = FruitDatabase.SessionFactory.OpenStatelessSession())
    {
            var results = session.Query<Fruit>().ToList();
    }
}

the NHibernate Profiler gives a warning about the ‘large number of individual writes’ and a suggestion about having ‘too many database calls per session’.

As you can see in the screenshot there are links to read more which takes you to a takes you to a page with helpful tips to resolve issue and a link to ignore the alert (not recommended!).

This isn’t the only alert that is raised when writing, so you should repeat the cycle of test and fix until no further alerts are raised, the queries/execution plan and/or code have been optimized e.g. changing how/where identifiers are created.

NHibernate Profiler alerts about reads

In addition to detecting problems when writing data the NHibernate profiler can give you tips when reading data.

For the example in this post there are alerts for an unbounded result set and an implicit transaction. Again these probably won’t be the only alerts raised.

Additional features in the NHibernate Profiler include being able to see the result of the query and the execution plan, the ability to compare sessions and a general overview of how an application is interacting with a database.

Check out this live HTML Demo to give it a test run.

There are also versions available for other ORMs like Entity Framework, unfortunately you’ll have to buy a separate licence for each one.

So while you could write your own solution to log and analyse interactions between your app and the database, the NHibernate Profiler will save you so much time because it can do the investigative work for you.

Something I definitely agree with.

Just as guns don’t kill people, ORMs don’t kill databases. Developers do.

It was a nightmare and the finger pointing began.

The problem was we assumed (always a bad thing) the queries generated by the ORM would be as good as if we had written them ourselves.

So when we looked at what was being generated it came as a bit of a shock to see what was going on.

But while it was easy to use the ORM as a scapegoat the reality was developers were at fault.

Here’s a simple example of how even the smallest of changes can make a difference in the SQL ORMs generate.

In the code below all we want nHibernate to do is select the of the fruit that is NOT also a color.

[Test]
public void Tale_Of_Two_Queries()
{
    var fruitDatabase = new FruitDatabase();
    using (ISession session = fruitDatabase.Session)
    {
        using (ITransaction txn = session.BeginTransaction())
        {

            var apple = new Fruit() { Name = "Apple", IsAlsoAColor = false};
            var orange = new Fruit() { Name = "Orange", IsAlsoAColor = true };

            session.Save(apple);
            session.Save(orange);
            txn.Commit();
        }

        var firstQuery = session.Query<Fruit>()
        .Where(f => !f.IsAlsoAColor)
        .Select(f => f.Name)
        .ToList();        

        var secondQuery = session.Query<Fruit>()
                .Where(f => f.IsAlsoAColor == false)
                .Select(f => f.Name)
                .ToList();
    }
}

For the query that uses !f.IsAlsoAColor the SQL query looks like this

select fruit0_.Name as col_0_0_
from   Fruits fruit0_
where  not (fruit0_.IsAlsoAColor = 1)

For the query that uses f.IsAlsoAColor == false the sql generated looks like this

select fruit0_.Name as col_0_0_
from   Fruits fruit0_
where  case
         when fruit0_.IsAlsoAColor = 1 then 1
         else 0
       end = case
               when 0 /* @p0 */ = 1 then 1
               else 0
             end

While this is a trivial example it highlights the fact you don’t know what the generated SQL will be, let alone the execution plan.

And if your query returns the results you want are you really going to spend time finding out what’s going on ‘under the hood’?

How comes nobody talks about this?

I can’t ever recall a presenter warning about this during any ORM talk I’ve been to. The focus always on what it can do and how it compares to other ORMs rather than best practices.

It’s not just a .Net problem either

After talking to Ruby on Rails developers this is a problem for them too, because Active Record doesn’t work 100% of the time. When it goes wrong they have to implement workarounds to execute queries without using active record.

So how can I make sure it doesn’t happen to me?

The first thing is to know what issues to look out for. The nHibernate profiler alerts page is an excellent resource for this.

With this information you can use profiling tools to see what queries your ORM is generating and how your application is performing.

My last tip is to always use the best data access method for what you’re doing. It’s easy to become complacent or aim to everything using an ORM, but if it makes more sense to use a stored procedure then that’s what you should do.

It would be good to hear what your experiences are with issues like this and to share any tips/tools you have used to avoid ORM performance issues.

In the meantime I’ll leave you with this excellent DBA vs. Developer (Star Wars Style) video

Why would you want to do this?

Let’s say to find out about nutritional information about fruits users clicked the relevant check boxes and press the button to submit the form e.g.

Back on the server we need to get nutritional information for each fruit selected.

To get this information we could write a nHibernate LINQ query like this

[Test]
public void Getting_Fruits_Using_LINQ_Query()
{
    var fruitIds = new List<int>() { 2, 3 };

    var fruitDatabase = new FruitDatabase();
    using (ISession session = fruitDatabase.Session)
    {
        using (ITransaction txn = session.BeginTransaction())
        {
            // Arrange
            var apple = new Fruit() { Id = 1, Name = "Apple", NutritionalInformation = "An apple a day" };
            var banana = new Fruit() { Id = 2, Name = "Banana", NutritionalInformation = "Energy Boost" };
            var orange = new Fruit() { Id = 3, Name = "Orange", NutritionalInformation = "Lots of Vitamin C" };
            var pear = new Fruit() { Id = 3, Name = "Pear", NutritionalInformation = "It's green" };

            session.Save(apple);
            session.Save(banana);
            session.Save(orange);
            session.Save(pear);
            txn.Commit();
        }

        // Act
        var result = (from f in session.Query<Fruit>()
                        join i in fruitIds
                            on f.Id equals i
                        select f).ToList();

        // Assert
        Assert.IsFalse(result.Exists(f => f.Name == "Apple"));
        Assert.IsTrue(result.Exists(f => f.Name == "Banana"));
        Assert.IsTrue(result.Exists(f => f.Name == "Orange"));
        Assert.IsFalse(result.Exists(f => f.Name == "Pear"));
    }
}

but doing so gives us the following error

System.NotSupportedException : Specified method is not supported.

However if we wrote the query like this the join works as expected

[Test]
public void Getting_Fruits_Using_LINQ_Query()
{
    var fruitIds = new List<int>() { 2, 3 };

    var fruitDatabase = new FruitDatabase();
    using (ISession session = fruitDatabase.Session)
    {
        using (ITransaction txn = session.BeginTransaction())
        {
            // Arrange
            var apple = new Fruit() { Id = 1, Name = "Apple", NutritionalInformation = "An apple a day" };
            var banana = new Fruit() { Id = 2, Name = "Banana", NutritionalInformation = "Energy Boost" };
            var orange = new Fruit() { Id = 3, Name = "Orange", NutritionalInformation = "Lots of Vitamin C" };
            var pear = new Fruit() { Id = 3, Name = "Pear", NutritionalInformation = "It's green" };

            session.Save(apple);
            session.Save(banana);
            session.Save(orange);
            session.Save(pear);
            txn.Commit();
        }

        // Act
     var result = session.Query<Fruit>()
                .Where(f => fruitIds.Contains(f.Id))
                .ToList();

        // Assert
        Assert.IsFalse(result.Exists(f => f.Name == "Apple"));
        Assert.IsTrue(result.Exists(f => f.Name == "Banana"));
        Assert.IsTrue(result.Exists(f => f.Name == "Orange"));
        Assert.IsFalse(result.Exists(f => f.Name == "Pear"));
    }
}

For which the SQL generated by nHibernate looks like this

select fruit0_.Id                     		as Id1_,
       fruit0_.Name                   		as Name1_,
       fruit0_.NutritionalInformation 	as Nutritio3_1_
from   Fruits fruit0_
where  fruit0_.Id in (2 /* @p0 */,3 /* @p1 */)

So to back up my opinion I’ve decided to write a tutorial about how to deploy an ASP.NET MVC application to AppHarbor.

The application we’ll be deploying will be the ASP.NET MVC Music Store (created by James Senior, Jon Galloway and Scott Hanselman) which uses ASP.NET MVC 3 with Razor syntax and data access via Entity Framework 4.

Click here to a deployed version of the ASP.NET MVC Music Store running on AppHarbor.

To follow along with the tutorial you’ll need to have the following installed:

• Visual Web Developer 2010 Express or Visual Studio 2010
• SQL Server 2008 Express or SQL Server 2008
• ASP.NET MVC 3
• Git (use this guide to help you install)
• A downloaded an unzipped version of the ASP.NET MVC Music Store

If you’re also going to use the ASP.NET MVC Music Store please ensure you change the ..\Views\Shared\_Layout.cshtml to include HTML to indicate the site is a sample available from codeplex and a noindex robots meta tag.

<!DOCTYPE html>
<html>
<head>
    <meta name="robots" content="noindex,nofollow" />
    <title>This is a ASP.NET MVC sample application which can be downloaded at http://mvcmusicstore.codeplex.com</title>
    <link href="@Url.Content("~/Content/Site.css")" rel="stylesheet"
        type="text/css" />
    <script src="@Url.Content("~/Scripts/jquery-1.4.4.min.js")"
        type="text/javascript"></script>
</head>
<body>
 <p style="padding:20px;background-color:#000;color:#FFF;text-align:center">
        This is a ASP.NET MVC sample application which can be downloaded at <a href="http://mvcmusicstore.codeplex.com">http://mvcmusicstore.codeplex.com</a>
    </p>
    <div id="header">
        <h1>
            <a href="/">ASP.NET MVC MUSIC STORE</a>
        </h1>
       <ul id="navlist">
           <li class="first"><a href="@Url.Content("~")" id="current">Home</a></li>
           <li><a href="@Url.Content("~/Store/")">Store</a></li>
           <li>@{Html.RenderAction("CartSummary", "ShoppingCart");}</li>
           <li><a href="@Url.Content("~/StoreManager/")">Admin</a></li>
       </ul>
    </div>
    @{Html.RenderAction("GenreMenu", "Store");}
    <div id="main">
        @RenderBody()
    </div>
    <div id="footer">
        built with <a href="http://asp.net/mvc">ASP.NET MVC 3</a>
    </div>
</body>
</html>

Let’s get started

1. How to add a ASP.NET MVC solution to a Git repository
2. How to push a ASP.NET MVC Git repository to AppHarbor
3. How To Create a SQL Server Database in AppHarbor
4. How to configure ASP.NET MVC to use a SQL Server database in AppHarbor

I can browse around the store and add things to my cart but can’t log in as an administrator

That’s because you can only have one database per application… something I didn’t know when I started this series.

As AppHarbor doesn’t support file storage (yet) you can’t use the ASPDBNET.MDF database which the music store uses for ASP.NET Membership. See this AppHarbor support entry for more details.

You can of course workaround this by adding membership tables etc. to the existing SQL Server database by via an alternative membership provider which includes using another application hosted on AppHarbor.

This tutorial is part of a series about how to deploy ASP.NET MVC applications to AppHarbor.

If you haven’t installed Git yet use this guide to get you started.

Before you initialize you git repository it’s a good idea to have a .gitignore file in root of the repository which instructs Git what files to ignore.

As you can see in the example below it excludes things which you don’t need to version control such as output directories and anything created by ReSharper.

*git
#ignore thumbnails created by windows
Thumbs.db
#Ignore files build by Visual Studio
*.obj
*.exe
*.pdb
*.user
*.aps
*.pch
*.vspscc
*_i.c
*_p.c
*.ncb
*.suo
*.tlb
*.tlh
*.bak
*.cache
*.ilk
*.log
[Bb]in
[Dd]ebug*/
*.lib
*.sbr
obj/
[Rr]elease*/
_ReSharper*/
[Tt]est[Rr]esult*

In the directory containing your ASP.NET MVC solution, right click and start Git Bash, or start Git Bash and navigate to the directory.

If this is the first time you’re using Git I recommended executing the following commands to set your user name and email address in the git.config which are used to track commits in the Git repository.

git config --global user.name jagreehal
git config --global user.email jag.reehal@gmail.com

To initialise a repository execute the following command

git init

Because we’ve used a gitignore file we can use the following Git command to add all files in the directory (and sub directories) into the repository.

git add .

Alternatively you could have added each file individually like this (for those who want total control)

git add <filename>

The final step is to commit your changes. The –m option allows you to add a message (otherwise you’ll be promoted for one)

git commit -m "Initial commit"

In the next part of the series we’ll be looking at how to push your ASP.NET MVC Git repository to AppHarbor.

This follows on from the tutorial for adding a ASP.NET MVC solution to a Git repository.

The first steps are to create an AppHarbor account if you haven’t got one, and then create an application

on the following page keep a note of the URLs where you’ll be pushing your Git repository to

In the directory containing your ASP.NET MVC solution start Git Bash, or start Git Bash and navigate to the directory.

Execute the following commands (substituting your URLs) to push your ASP.NET MVC solution to AppHarbor.

git remote add appharbor https://jagreehal@appharbor.com/MvcMusicStoreDemo.git
git push appharbor master

When you’re prompted to enter your password, use the same one for your AppHarbor account.

Next go to the build page on AppHarbor to see the status of your app.

If you’re following along with the example to deploy the ASP.NET MVC Music Store to AppHarbor you’ll see the site doesn’t work yet.

That’s because you can’t use MDF database files in AppHarbor yet so the next step is create the ASP.NET MVC Music Store SQL Server database in AppHarbor.

Although the build was successful an error occured when viewing the site becuase it couldn’t connect to the attached database.

To fix this we need to create a SQL Server Database in Appharbor.

On the AppHarbor application management page click the link to ‘Add database’

Next choose SQL Server as the database type, enter a connection string name and click the create button.

I used the same connection string name used by Entity Framework 4 in the ASP.NET MVC Music Store application.

The following screen shows you what connection string should be used in your config file and information about how to connect to the Appharbor database from Microsoft SQL Server Managemnt Studio.

When you connect to the database in Microsoft SQL Server Managemnt Studio you’ll see the database is empty.

In the Assets/Data folder in the ASP.NET MVC Music Store you’ll find a ‘MvcMusicStore-Create.sql’ SQL script which can be used to create and populate the tables required by the application.

Before running the script delete the first line that looks like this

USE [C:\USERS\JON\DOCUMENTS\JON-SHARE\MVCMUSICSTORE-MVC3\MVCMUSICSTORE\MVCMUSICSTORE\APP_DATA\MVCMUSICSTORE.MDF]

When the script has been completed successfully the tables will have been created and populated

In the next step of this tutorial we will see how to configure ASP.NET MVC to use a SQL Server database in AppHarbor.