We’re going to take a look at tags.

We add tags to our features like this, using the @ to prefix a name

@Calculator
Scenario: Calculate two values
# Given/When/Then steps

We can have multiple tags for a scenario, just comma separate them, like this

@Calculator, @Math
Scenario: Calculate two values
# Given/When/Then steps

Great, so what use do I have for tags?

Tags can be used to create documentation, they can be used to for start up and clean up code and they can be uses within the test runners to run groups of tests via their category, you guessed it, denoted by the tag, for example

// run tests on anything tagged Math
dotnet test MyTests.dll --filter Category=Math

// to run tests with both Calculator and Math tags
dotnet test MyTests.dll --filter "Category=Calculator & Category=Math"

// to run tests with either Calculator or Math tags
dotnet test MyTests.dll --filter "Category=Calculator | Category=Math"

The use case for this is, I have a step Set fields on view which takes a table like this

Scenario: With table
  Given Set fields on view 
    | A  | B  | C  |
    | a1 | b1 | c1 |
    | a2 | b2 | c2 |      
    | a3 | b3 | c3 |                            

The code for this step, currently just outputs the data set to it to the console or log file, so looks like this

[Given(@"Set fields on view")]
public void GivenFieldsOnView(Table table)
{
   table.Log();
}

Now in some cases, I want to set fields on a view using an Examples. So in the current case we’re sending multiple rows in one go, but maybe in some situations we want to set fields, one row at a time, so we uses Examples like this

Scenario Outline: Convert To Table
  Given Set fields on view A=<A>, B=<B>, C=<C>

  Examples:
    | A  | B  | C  |
    | a1 | b1 | c1 |
    | a2 | b2 | c2 |      
    | a3 | b3 | c3 |            

We’ll then need a new step that looks like this

[Given(@"Set fields on view (.*)")]
public void GivenFieldsOnView(string s)
{
}

Ofcourse we can now split the variable s by comma, then split by = to get our key values, just like a Table and there’s nothing wrong with this approach, but an alternative is to have this transformation as a StepArgumentTransformation. So our code above would change to

[Given(@"Set fields on view (.*)")]
public void GivenFieldsOnView2(Table table)
{
   table.Log();
}

and now in our hook class we’d have something like this

[Binding]
public class StepTransformer
{
  [StepArgumentTransformation]
  public Table TransformToTable(string input)
  {
    var inputs = input.Split(new[] { ',' }, StringSplitOptions.RemoveEmptyEntries);
    var d = inputs.Select(s =>
      s.Split(new[] { '=' }, StringSplitOptions.RemoveEmptyEntries))
        .ToDictionary(v => v[0], v => v[1]);

    // this only handles a single row 
    var table = new Table(d.Keys.ToArray());
    table.AddRow(d.Values.ToArray());
    return table;
  }
}

Note: This is just an example, with no error handling and will only convert a string to a single row, it’s just a demo at this point.

So, now what we’ve done is create a transformer which understands a string syntax such as K1=V1, K2=V2… and can convert to a table for us.

I know that you’re probably asking, why, we could we not just execute the same code in the public void GivenFieldsOnView(string s) method ourselves. Well you could ofcourse do that, but now you’ve got a generic sort of method for making such transformations for you.

What I really wanted to try to do is use a single step to handle this by changing the regular expression, i.e. we have one method for both situations. Sadly I’ve not yet found a way to achieve this, but at least we can reduce the code to just handle the data as tables.

In my post Running code when a feature or scenario starts in SpecFlow I showed we can use hooks to run before the feature and scenario. However, what if we have, for example, a lot of separate scenario hooks but the order that they run in matters. Maybe we need to have the logging of the scenario title and this should run first.

The BeforeScenario has a property Order which we can assign a number like this

[BeforeScenario(Order = 1)]
public static void BeforeScenario(ScenarioContext scenarioContext)
{
  Debug.WriteLine($"Scenario starting: {scenarioContext.ScenarioInfo.Title}");
}

This will run before other scenarios, including those with no Order property.

Beware, if you set the [AfterScenario(Order = 1)] it would also be run first. Which you might not want in a logging situation, then (the only solutions I’ve found thuis far is) you’ll have to actually have an Order property in all AfterScenario attributes, i.e. explicitly state the order or all such hooks.

The use case I have is as follows.

Using SpecFlow for running UI automation tests, we have lots of views off of the main application Window, we might write out scenarios specific to each view, such as

Given Trader view, set fields
Given Middle Office view, set fields
Given Sales view, set fields

and these in turn are written as the following steps

[Given(@"Trader view, set fields")]
public void GivenTraderViewSetFields()
{
  // set the fields on the trader view
}

[Given(@"Middle Office view, set fields")]
public void GivenMiddleOfficeViewSetFields()
{
  // set the fields on the middle office view
}

[Given(@"Sales view, set fields")]
public void GivenSalesViewSetFields()
{
  // set the fields on the sales view
}

obviously this fine, but if all our views had the same automation steps to set fields, then the code within will be almost exactly the same, so we might prefer to rewrite the step code to be more generic

[Given(@"(.*) view, set fields")]
public void GivenViewSetFields(string viewName)
{
  // find the view and set the fields using same automation steps
}

This is great, we’ve reduced our step code, but the (.*) accepts any value which means that if we have a view which doesn’t support the same steps to set fields, then this might confuse the person writing the test code. So we can change the (.*) to restrict the view names like this

[Given(@"(Trader|Middle Office|Sales) view, set fields")]
public void GivenViewSetFields(string viewName)
{
  // find the view and set the fields using same automation steps
}

Now if you add a new view like the step below, your SpecFlow plugin will highlight it as not having a matching step and if you run the test you’ll get the “No matching step definition found for one or more steps.” error.

Given Admin view, set fields

We can ofcourse write a step like the following code, and now the test works

[Given(@"Admin view, set fields")]
public void GivenAdminViewSetFields()
{
}

But this looks different in the code highlighting via the SpecFlow extension to our IDE but also, what if Admin and Settings views both can use the same automation steps, then we’re again back to creating steps per view.

Yes, we could reuse the actual UI automation code, but I want to reduce the number of steps also to a minimum. SpecFlow allows, what we might think of as regular expression overrides, so let’s change the above to now look like this

[Given(@"(Admin|Settings) view, set fields")]
public void GivenAdminViewSetFields(string viewName)
{
}

Obviously we cannot have the same method name with the same arguments in the same class, but from the Feature/Scenario design perspective it now appears that we’re writing steps for the same method whereas in fact each step is routed to the method that understands how to automate that specific view.

This form of regular expression override also means we might have the method for Trader, Middle Office and Sales in one step definition file and the Admin, Settings method in another step definition file making the separation more obvious (and ofcourse allowing us to then use the same method name).

What’s also very cool about using this type of expression is the the SpecFlow IDE plugins, will show via autocomplete, that you have a “Admin view, set fields”, “Trader view, set fields” etc. steps .

One really useful option in SpecFlow, which maybe most people will never need, is the ability to intercept input and potentially transform it. So the example I have is, we want to include tokens wrapped in { }. These braces will include a token which can then be replaced by a “real” value. Let’s assume {configuration.XXX} means get the value XXX from the configuration file (App.config).

With this use case in mind, let’s assume we have a feature that looks like this

Feature: Transformer Tests

  Scenario: Transform a number
    Given The value {configuration.someValue1}

  Scenario: Transform a table
    Given The values 
    | One                        | Two                        |
    | {configuration.someValue1} | {configuration.someValue2} |

We’re going to hard code our transformer to simple change configuration.someValue1 to Value1 and configuration.someValue2 to Value2, but ofcourse the real data could be read from the App.Config or generated in some more useful way.

Our step file for the above feature file, might look like this

[Given(@"The value (.*)")]
public void GivenTheValue(string s)
{
  s.Should().Be("Value1");
}

[Given(@"The values")]
public void GivenTheValues(Table table)
{
  foreach (var row in table.Rows)
  {
    var i = 1;
    foreach (var rowValue in row.Values)
    {
      rowValue.Should().Be($"Value{i}");
      i++;
    }
  }
}

We create a class, usually stored in the Hooks folder which looks like the following, where we include methods with the StepArgumentTransformation attribute, meaning these methods are call for the given type to do something with the step argument.

[Binding]
public class StepTransformer
{
  private string SimpleTransformer(string s)
  {
    switch (s)
    {
      case "{configuration.someValue1}":
        return "Value1";
      case "{configuration.someValue2}":
        return "Value2";
      default:
        return s;
    }
  }
        
  [StepArgumentTransformation]
  public string Transform(string input)
  {
    return SimpleTransformer(input);
  }
        
  [StepArgumentTransformation]
  public Table Transform(Table input)
  {
    foreach (var row in input.Rows)
    {
      foreach (var kv in row)
      {
        row[kv.Key] = SimpleTransformer(kv.Value);
      }
    }
    return input;
  }
}

This is a very simple example of such code, what we’d do in a real world is create some more advanced transformer code and inject that via the constructor but the basic Transform method would look much like they are here.

One of the useful capabilities within SpecFlow is for us to define hooks which starts when the feature or scenario starts and ends.

An obvious use of these is to log information about the feature or scenario – we’ll just use Debug.WriteLine to demonstrate this.

All we need to do is create a binding and then supply static methods marked with the BeforeFeature and AfterFeature attributes, which might look like this

[Binding]
public class FeatureHook
{
  [BeforeFeature]
  public static void BeforeFeature(FeatureContext featureContext)
  {
    Debug.WriteLine($"Feature starting: {featureContext.FeatureInfo.Title}");
  }

  [AfterFeature]
  public static void AfterFeature(FeatureContext featureContext)
  {
    Debug.WriteLine($"Feature ending: {featureContext.FeatureInfo.Title}");
  }
}

as you can probably guess, we can do the same with the BeforeScenario and AfterScenario attributes like this

[Binding]
public class ScenarioHook
{
  [BeforeScenario]
  public static void BeforeScenario(ScenarioContext scenarioContext)
  {
    Debug.WriteLine($"Scenario starting: {scenarioContext.ScenarioInfo.Title}");
  }

  [AfterScenario]
  public static void AfterScenario(ScenarioContext scenarioContext)
  {
    Debug.WriteLine($"Scenario ending: {scenarioContext.ScenarioInfo.Title}");
  }
}

Over the last few months I’ve been helping develop an Appium/WinAppDriver framework (or library if you prefer) to allow one of the application to look to move one of my client’s application away from CodedUI (support is being phased out for this).

One of the problem I had is, I wanted to be able to put text into the Windows Clipboard and paste it into an various edit controls. The pasting made things slightly quicker but also, more importantly, bypassed some control’s autocomplete which occasionally messes up using SendKeys.

The problem is that the clipboard uses OLE and NUnit complains that it needs to be running in an STA.

To fix this, SpecFlow classes are partial so we can create new classes within another file with the same classname (and mark as partial) and namespace and then add the NUnit require attribute as below

[NUnit.Framework.Apartment(System.Threading.ApartmentState.STA)]
public partial class CalculatorFeature
{
}

This is all well and good. It’s hardly a big deal, but we have hundreds of classes and it’s just more hassle, remembering each time to do this, or you run the tests and when it hits a Paste from the Clipboard, it fails, wasting a lot of time before you’re reminded you need to create the partial class.

SpecFlow has the ability to intercept parameters passed into our steps, it has tags and hooks which allow you to customize behaviour and it also comes with a way to interact with the code generation process which we can use to solve this issue and generate the required attributes in the generated code.

The easiest way to get started is follow the steps below, although if you prefer, the code I’m presenting here is available on my PutridParrot.SpecFlow.NUnitSta GitHub repo., so you can bypass this post and go straight the code for this article if you prefer.

• Grab the zip or clone the repo to get the following GenerateOnlyPlugin
• You may want to update SampleGeneratorPlugin.csproj to

  <TargetFrameworks>net472;netcoreapp3.1</TargetFrameworks>
  

  I would keep to these two frameworks to begin with, as we have a few other places to change and it’s better to get something working before we start messing with the rest of the build properties etc.

• In the build folder edit the .targets file to reflect the Core and !Core frameworks, i.e.

  <_SampleGeneratorPluginFramework Condition=" '$(MSBuildRuntimeType)' == 'Core'">netcoreapp3.1</_SampleGeneratorPluginFramework>
  <_SampleGeneratorPluginFramework Condition=" '$(MSBuildRuntimeType)' != 'Core'">net472</_SampleGeneratorPluginFramework>
  

  Again I’ve left _SampleGeneratorPluginFramework for now as I just want to get things working.

• Next go to the .nuspec file and change the file location at the bottom of this file, i.e.

  <file src="bin\$config$\net472\PutridParrot.SpecFlow.NUnitSta.*" target="build\net472"/>
  <file src="bin\$config$\netcoreapp3.1\PutridParrot.SpecFlow.NUnitSta.dll" target="build\netcoreapp3.1"/>
  <file src="bin\$config$\netcoreapp3.1\PutridParrot.SpecFlow.NUnitSta.pdb" target="build\netcoreapp3.1"/>
  

• Now go and change the name of the solution, the project names and the assembly namespace if you’d like to. Ofcourse this also means changing the PutridParrot.SpecFlow.NUnitSta in the above to your assembly name.

At this point you have a SpecFlow plugin which does nothing, but builds to a NuGet package and in your application you can set up your nuget.config with a local package pointing to the build from this plugin. Something like

<packageSources>
  <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
  <add key="Local" value="F:\Dev\PutridParrot.SpecFlow.NUnitSta\PutridParrot.SpecFlow.NUnitSta\bin\Debug"/>
</packageSources>

Obviously change the Local package repository value to the location of your package builds.

Now if you like, you can create a default SpecFlow library using the default SpecFlow templates. Ensure the SpecFlow.NUnit version is compatible with your plugin (so you may need to update the package from the template one’s). Finally just add the package you built and then build your SpecFlow test library.

If all went well, nothing will have happened, or more importantly, no errors will be displayed.

Back to our Plugin, thankfully I found some code to demonstrated adding global:: to the NUnit attributes on GitHub, so my thanks to joebuschmann.

• Create yourself a class, mine’s NUnit3StaGeneratorProvider
• This should implement the interface IUnitTestGeneratorProvider
• The constructor should look like this (along with the readonly field)

  private readonly IUnitTestGeneratorProvider _unitTestGeneratorProvider;
  
  public NUnit3StaGeneratorProvider(CodeDomHelper codeDomHelper)
  {
     _unitTestGeneratorProvider = new NUnit3TestGeneratorProvider(codeDomHelper);
  }
  

• We’re only interested in the SetTestClass, which looks like this

  public void SetTestClass(TestClassGenerationContext generationContext, string featureTitle, string featureDescription)
  {
     _unitTestGeneratorProvider.SetTestClass(generationContext, featureTitle, featureDescription);
  
     var codeFieldReference = new CodeFieldReferenceExpression(
        new CodeTypeReferenceExpression(typeof(ApartmentState)), "STA");
  
     var codeAttributeDeclaration =
        new CodeAttributeDeclaration("NUnit.Framework.Apartment", new CodeAttributeArgument(codeFieldReference));
           generationContext.TestClass.CustomAttributes.Add(codeAttributeDeclaration);
  }
  

  All other methods will just have calls to the _unitTestGeneratorProvider method that matches their method name.

• We cannot actually use this until we register out new class with the generator plugins, so in your Plugin class, mine’s NUnitStaPlugin, change the Initialize to look like this

  public void Initialize(GeneratorPluginEvents generatorPluginEvents, 
     GeneratorPluginParameters generatorPluginParameters,
     UnitTestProviderConfiguration unitTestProviderConfiguration)
  {
     generatorPluginEvents.CustomizeDependencies += (sender, args) =>
     {
        args.ObjectContainer
           .RegisterTypeAs<NUnit3StaGeneratorProvider, IUnitTestGeneratorProvider>();
     };
  }
  

• If you changed the name of your plugin class ensure the assembly:GeneratorPlugin reflects this new name, the solution will fail to build if you haven’t updated this anyway.

Once all these things are completed, you can build your NuGet package again. It might be worth incrementing the version and then update in your SpecFlow test class library. Rebuild that and the generated .feature.cs file should have classes with the [NUnit.Framework.Apartment(System.Threading.ApartmentState.STA)] attribute now. No more writing partial classes by hand.

This plugin is very simple, all we’re really doing is creating a really minimal implementation of IUnitTestGeneratorProvider which just adds an attribute to a TestClass and we registered this with the GeneratorPluginEvents, there’s a lot more why could potentially do.

Whilst this was very simple in the end. The main issues I had previously with this are that we need to either copy/clone or handle these build props and targets as well as use .nuspec to get our project packaged in a way that works with SpecFlow.

SpecFlow is a BDD (Behaviour Driven Development) tool that supplies templates and integration for Visual Studio.

If you are new to BDD (or TDD or unit testing in general) go off to your favourite search engine and search. I’m sure there are far better definitions out there than I’ll probably come up with or try here. For those of you not wishing to waste a moment let’s start looking at SpecFlow.

The idea behind a feature is to define a test scenario in a more human readable way, in fact the perfect situation would be for the domain expert to write the scenarios to act as acceptance tests. SpecFlow is based upon Cucumber and uses the DSL Gherkin to allow the domain experts to write the scenarios.

Enough waffle let’s write a feature. We’ve got a Trade object which has a TradeDate and a StartDate. The StartDate should be calculated to be the TradeDate + 3 days.

Feature: Check the trade date is defaulted correctly
Scenario: Default the trade date
	Given Today's date is 23/10/2012
	When I create a trade
	Then the resultant start date should be 26/10/2012

The Feature text is just a name for the feature and can be followed by free form text to add documentation, in the above case I’ve not bothered. Instead I’ve gone straight to creating a Scenario.

A Scenario is basically the definition of what we want to test. Using the keywords Given, When, Then, And and But (note: I’ve not checked this is the full list). We can create the scenario for the test (don’t get too excited we still need to write the test) and then the Visual Studio integration will by default run the SpecFlowSingleFileGenerator custom tool against this feature file and create a feature.cs which contains the code for calling into your tests.

So we now have a feature file, potentially supplied by our domain expert. From this we get a .cs file generated which calls our code in the correct order and potentially passing arguments from the scenario to our test code. In the above case we want the dates to be passed to our tests. So now to write the code which will be run from the scenario generated code and here we add NUnit (or your preferred unit testing lib.) to check things are as expected.

[Binding]
public class Default_the_trade_date
{
   private Trade trade;
   private DateTime todaysDate;

   [Given("Today's date is (.*)")]
   public void Given_Todays_Date_Is(DateTime today)
   {
      todaysDate = today;
   }

   [When("I create a trade")]
   public void When_I_Create_A_CreateTrade()
   {
      trade = new Trade {TradeDate = todaysDate};
   }

   [Then("the resultant start date should be (.*)")]
   public void Then_Start_Date_Should_Be(DateTime dateTime)
   {
      Assert.AreEqual(trade.StartDate, dateTime);
   }
}

Note: I’ve named this class Default_the_trade_date this is the name I gave the scenario, this is not a requirement but makes it obvious what this code is for.

In the above you’ll notice the use of attributes which match the text in the scenario for each step, i.e. Given, When, Then. The text uses regular expressions, so matches the text to the scenario text but in this case the (.*) converts the dates into arguments to be passed into the test methods.

You can now right mouse click on your project or better still your .feature and select Run SpecFlow Scenarios. Unfortunately the above code will fail. As I’m using British date formats, i.e. dd/MM/yyyy and the default DateTime parser is en-US. So we need to edit the App.config for our scenarios to have

<language feature="en-GB" tool="{not-specified}" />

within the specFlow element.

If all went to plan, when you run the specflow scenarios the tests show green.

Note: If we have multiple features and/or scenarios which maybe use the same text, for example in the above code maybe we have several features and scenarios which use the Given “Today’s date is “. We can set the Scope attribute on the test classes and either mark the scenario with a tag

@tradeDate
Scenario: Default the trade date
   ...

or we can use the Feature and/or Scenario name such as

[Binding]
[Scope(Feature = "Check the trade date is defaulted correctly")]
public class Default_the_trade_date
{
   // code
}

See Scoped bindings for more on this and note the preference is towards not using such couplings.