Everything You Need to Get Started with SpecFlow and WatiN

I’m adding SpecFlow to an application I’m working on so that I can add some acceptance tests that actually exercise the user interface.  I’ve only spent a couple of hours on it thus far, but I have it working with a single specification running through the tests via WatiN.  I found the following resources helpful as I was going through this exercise:

I’m assuming that you’re just interested in getting up to speed with SpecFlow for acceptance testing and that you don’t want to waste any time on hidden gotchas or visiting all of the above URLs just to figure out what you actually need.  Let me just give you the Stuff You Need To Know™.

Installing SpecFlow

First, you need to install SpecFlow from this URL.  When I wrote this, the latest version was 1.6.1.  Alternately, you can get SpecFlow via Nuget here.  If you run the installer, specflow will be installed in your Program Files (x86) folder under TechTalk, like so:


Next, you’ll want to add a new Class Library project to whatever solution you’re working with (I’m going to assume you have an ASP.NET web project in the solution that you’re trying to test).  You can name it Specifications or AcceptanceTests or whatever you prefer.  There isn’t a special project template set up, but there are item templates, so after you have the class library, add a New Item and choose a SpecFlow Feature File:


This will give you a sample .feature file to start from.  I’m not going to go into detail about the gherkin language, but rather will simply show you my first .feature file which is a bit more real-world than the one provided (this one will end up working against a scaffolded ASP.NET MVC 3 app):


Note that there is a generated C# (.cs) file that goes along with each .feature file.  This generated code is responsible for all of the test setup.  In my case I’m using the default NUnit test runner, but you can also use MSTest.  To install NUnit, I simply used the Package Manager to add it, like so:

install-package nunit

Once you have NUnit installed, you can run the tests.  I’m using ReSharper so this screenshot shows its integrated test runner:


Note that since I haven’t defined any Step definitions, my tests don’t actually do anything yet.  However, part of the workflow of SpecFlow that you can follow is to run the test without the steps, and then copy and paste the step methods from the test results shown here.  You can just add a new class and replace its contents with one of the classes above, or you can Add –> New Item and add a new SpecFlow Step Definition.  I’m still figuring out how best to organize my Specifications project but for now I’m naming things by feature name, so I have a CreatePublicationFeature.feature file and a CreatePublicationSteps.cs file, so the two will sort together.

Now that we have some yellow tests, we can work toward making the test pass.  We also can produce an HTML report, showing all of our features and our progress on them thus far.  I’ll show the reporting last, but if you’re defining a lot of features up front, having the reporting early on can be a great thing to share with project stakeholders, since they’ll be able to see with each iteration how many features are going from yellow to green (and hopefully none turning red) as they are implemented and tested.

Testing ASP.NET MVC with WATIN

In my scenario I decided to give WatiN a try.  To install it, I once again turned to Nuget.  The install was easy, however, there were a few gotchas that I encountered.  The first one was the dreaded STAThread issue, which you can resolve by adding an attribute to your unit test class marking it as a Single Threaded Apartment.  However, since SpecFlow generates our test classes, this isn’t ideal.  So the alternate approach is to add an app.config file with the following configuration to force NUnit to run in STA mode:


The other issue I encountered was related to the Interop.SHDocVw assembly, which is referenced and is in my /packages folder, but still my tests would fail saying they could not load the assembly.  The fix that worked for me (VS2010, Windows 7 x64, if that matters) was to change the Embed Interop Types property of the reference to False (it defaulted to True).  This eliminated that issue, and allowed my tests to launch an Internet Explorer window.  Here’s the setting:


I mention the above up front because they were immediate roadblocks to my being able to use WatiN in my project, and I don’t want you to get hung up on them when you get started with the next bit of code.  I did add one helper class that I found on one of the links I listed at the top of this post, which lets me reference the same browser instance between test methods.  It’s a simple static class with a static method that leverages the SpecFlow ScenarioContext collection.  If you’re following along with my code exactly, you’ll need this:

Now back to the Step .cs class.  We cut-and-pasted the empty step definitions from our test output so that we now have some [Given] [When] and [Then] methods in our class, CreatePublicationSteps.  For my scenario, I don’t actually have any setup to do in my [Given], so I could omit it entirely.  But if I do keep it, it’s sufficient for it to look like this:

I opted to leave it in here for now.  It’s likely that I’ll update it at some point to include a requirement like “Given I am on the site and logged in” which might require some actual setup work.  Next I have [When] statements for the scenario.  Note that any “and” between your “When” and the “Then” is simply treated as another “When” statement.  So for my scenario, where I have

When I navigate to the Publication/Create page

And I enter "Test Publication" in the Publisher textbox

that’s going to result in two separate [When] methods, which I was able to cut-and-paste “scaffolded” versions from my test output.  Once filled in with appropriate WatiN calls, they look like this:

Note that you probably don’t have a .TypeTextQuickly() method – you can replace that with TypeText for now, which I recommend so you can see how things work by default.  Note that for this to work, your web application has to be running (if you’re using the Dev Web Server).  If you’re using IIS or actually hitting a site on the Internet, then this shouldn’t be an issue.  Note in the second function that I’ve changed the attribute value, replacing the original (C# escaped quotes) “”Test Publication”” with this “”(.*)””.  This is a regular expression, and .* basically will match any series of characters.  The result of this match is then provided as the string parameter on the method, string publicationName.  It will be populated from the scenario, so when the test is run, publicationName will be “Test Publication”.  Since at the moment I’m not resetting the database between each test, I made the test a bit more robust by adding a random number to the name, and then storing the resulting modified name in the ScenarioContext.  I’ll use that in the assertions within the [Then] methods.

By the way, I’m using a simple ASP.NET MVC 3 application with some default controllers and view set up using Entity Framework.  You can see how to do this in ScottGu’s post on EF Code First and Data Scaffolding with the ASP.NET MVC 3 Tools Update.  If you want to follow along, just create a class called Publication with a Name property (and an ID column), build your project, and then Add Controller and (assuming you have the tools update referenced in Scott’s post) you should then choose the Controller with read/write actions and views, using Entity Framework template, which will generated a Create controller action and view that you can use to run the exact tests I’m showing.  Here’s what my view looks like:


Before you can fully run the test, we need to implement the [Then] methods.  These are both pretty simple:

With these in place, you should be able to run your test, and with any luck it will come back green.  Two things to note at this point, however:

  1. The test is pretty slow.
  2. The IE window created sticks around, and a new one is made every time you run the test.

To fix the speed problem, you can add this extension method (create a class WatinExtensions and add it to your project):

This should speed up your test dramatically – on my machine it makes it about twice as fast.  It’s still slow compared to unit tests, but twice as fast is certainly an improvement, and in this case I don’t need any keypress events or in fact any client-side events at all.

To fix the window problem, you can uncomment the call to WebBrowser.Current.Close() in the last [Then] method.  As you add additional features, you’ll no-doubt want to come up with a better approach to recycle the browser windows.  From what I’ve been able to learn, it seems like the typical usage of WatiN is to use test class level setup and teardown methods to create and close the window.  With SpecFlow, if you want to go this route, you can either manually edit the .feature.cs file (which I don’t recommend), or since it’s a partial class, you can create your own partial class and add the following to it:

This will destroy the current WebBrowser at the end of each scenario.  With that in place, you should be able to run your tests, run them reasonably quickly, and not have any browser instances to clean up when you are finished.

Automation and Reporting

It would be nice if we could automate the running of these tests, so that we could schedule them or run them as part of a build process.  Likewise, one of the nice features of creating executable specifications is that they should produce documents that you can share with project stakeholders.  SpecFlow supports both of these scenarios, but getting it set up can take a little bit of work.  In order to use SpecFlow to create reports as part of your automated build process, you’ll need some of the SpecFlow DLLs and the specflow.exe file in source control, so they can work on any machine without requiring SpecFlow to be installed on that machine.  If you’re using Nuget, I think everything you need should be in the /packages folder, but I haven’t tested that scenario.  In my case, I simply copied the DLLs I needed into a /lib folder in my project’s source control repository.  Here are the files I ended up needing:


To create an HTML report, you need to first run your unit tests using NUnit’s command line tool, with a few switches enabled.  I like to use a combination of MSBuild and a ClickToBuild.bat batch file in the root of my source repository so that whenever someone grabs the source they can immediately run that batch file and get a working build of the software (with all tests run).  Here is my current build.proj file, that is in the root of my solution:

Then I also include a build.bat and a ClickToBuild.bat file with every solution.  They look like this (one line each):


%systemroot%Microsoft.NetFrameworkv4.0.30319MSBuild.exe build.proj /t:%*


build.bat ReleaseBuild & pause


The main work is all performed in the BuildAndTest target of the MSBuild .proj file.  If you’re just testing this out from a command prompt, you can pull the commands you need from the <Exec /> elements there.  For NUnit to generate a TestResult.xml file, you need to pass in the /xml:TestResult.xml switch.  Note that at this time ReSharper cannot generate an NUnit TestResult.xml file, so you have to resort to using the command line (or the NUnit GUI).  Once you have that XML file, you can generate the SpecFlow HTML report by running specflow.exe with the command nunitexecutionreport and providing it with /out:SomeFile.html.  Assuming that’s all correct, you should end up with an HTML file that looks something like this:


Note that if you are using the ClickToBuild the first time when you grab the source, you will need to start the web project (if using Web Dev Server) or otherwise set it up in IIS or IIS Express.  You can script this as well (launch webdevserver from the MSBuild task if you like, on a known and otherwise unused port), but what I’m showing you here does not include that one step in any automated fashion.


There’s not a whole lot to getting SpecFlow and WatiN working with your ASP.NET (MVC) application.  There are a few hidden gotchas that I’ve tried to cover in this post.  Hopefully this will provide all of the resources you need.  If there’s something missing, please let me know and I will provide an update to address the issue.  The nice thing about the final HTML report you get is that you can sit down with the customer or project stakeholder and create all of the major features and many of the known scenarios prior to an iteration or release cycle, and then provide regular updates showing progress being made on a feature-by-feature (and scenario-by-scenario) level.  Assuming the documented executable specifications accurately reflect the customer’s needs, these acceptance tests provide a common definition of what “done” is for the project, reducing the frequency of the team delivering incomplete or incorrect features.

  • Marcus Hammarberg

    Hi Steve,

    nice article and nice trick with the TypeTextQuickly that should help up speed a lot.

    Two thing that I noted when I read this; the first is your use of [NUnit.Framework.TearDownAttribute()]

    You could (and I say should :)) use a SpecFlow version of that instead. It’s called AfterTestRun (see this github.com/…/HooksDemoSteps. for an example of all the hooks in SpecFlow).

    The reason I suggest you use that is that you will become testframework agnostic by this. You can simply switch to for example MsTest, SpecFlow will pick that up and ask to recreate your .feature.cs files for you. The rest will still work as before.

    The second thing I noted is a bit picky, and I know that this is an intro post but… I would recommend against using "textbox", "button" or other lowlevel GUI language in your specifications.

    Keep your language on a higher plane and you will simplify the maintaince of the files a great deal. The details should be in the step definitions (as you have already).

    For example you can use the phrases; "When I enter ‘Test Publication" and "Given I am on the Publication page".

    I have written about this here; http://www.marcusoft.net/…/clean-up-your-s

    But again – that’s picky and maybe to much for a intro post. Just my two cents.

    You’ve done a great job introducing SpecFlow and WatIn.


  • Steve Smith


    Thanks for pointing out the hooks for SpecFlow – I decided to use the [AfterTestRun] method to close my browser window. Also, if you get a process activation error when WatiN is trying to launch IE, one thing to check is whether you are running VS as admin. I’m running on another machine now and at one point the web page would load but WatiN wouldn’t type into the textbox. Restarting VS as administrator fixed the issue.

  • Scott Hanselman

    Really useful stuff. Thanks for exploring this space.

  • Steve Smith

    By the way, I tried adding this to my Steps file:


    public static void AfterTestRun()




    but it throws a NullReferenceException. So far to clean up the browser the only solution I’ve found that works reliably is to put WebBrowser.Current.Close() in my last [Then] method call. Anybody know a better way?

  • Matt Frear

    Great post, very useful, thanks!

  • Nick Meldrum

    So it seems you can’t put that line in AfterTestRun() as the ScenarioContext object where you are holding the current browser reference has already been disposed.

    At the moment I am putting it in an AfterScenario method:


    public void AfterScenario() {



    However this means a new webbrowser instance per scenario. Naturally slower but cleaner.

    My scenarios generally want a clean browser session – so this can be an advantage.

    I am working on a way of getting it to use the same browser session and clean up inbetween scenarios however.

    I will post back here if I sort it (and I remember :))

  • Nick Meldrum

    It seems that clearing the cache and cookies a la:



    Doesn’t have the desired effect as it only clear’s the cache on disk, not in memory. Therefore for Watin I think reopening the IE instance is probably needed anyway.

    This has the advantage of being able to handle all the webbrowser lifetime stuff in the one place though. Adding this to the WebBrowser static class seems okay:


    public static void Close()


    if (ScenarioContext.Current.ContainsKey("browser"))



    Taken from Steve Sanderson’s example here: github.com/…/GuestbookDemo

    Question though:

    I would prefer to add the "WebBrowser" dependency via IOC into my StepDefinition class in SpecFlow rather than using a Singleton instance.

    Anyone know how to do that? Cheers!

  • Ivan Franjic

    This is a great post! Just what I needed, thanks 🙂

  • Mark Broadhurst

    @Nick I wouldnt use a singleton nor would I use IOC. SpecFlow provides 2 classes to help you persist objects there is a ScenarioContext and FeatureContext depending on the scope you require. Each has a Current propery which exposes a number of methods to carry objects between steps.

    The main ones I use are Get and Set.

    For example:


    public void BeforeEach()


    Browser browser = new IE();




    public void AfterEach()


    Browser browser = ScenarioContext.Current.Get<Browser>();



  • Hyperlegend

    You can close the browser using one of Specflow hooks AfterScenario or AfterTestRun or AfterFeature. I don’t think closing the browser in a partial class of a feature is a good practice since you would have to do this for every single feature this would go against DRY principles.