A BDD Journey With SpecFlow

2021-11-15 21-11-15
by Ali Mollahosseini


Our passion and obsession with Behaviour Driven Development (BDD) has taken us here at SpecFlow to extreme lengths; we live and breathe this practice. We also believe other development teams would immensely benefit from this practice, and to make it easier for them to adopt BDD, we have put together a range of products to facilitate a quicker and more intuitive adoption.

This article is based on a webinar held by the SpecFlow team and will look at developing a simple feature for an equally simple application from a BDD perspective. The idea is to understand the different phases or steps of BDD, which can then be applied to any project regardless of the size and complexity.

Sample Application

The application used in this example is a simple content submission form developed using:

  • .NET 5
  • ASP.NET Core
  • EF Core
  • MS SQL Server
  • Docker

The CI/CD tool used is TeamCity, and the work item tracking tool we used in this example is Atlassian Jira. We also used Mural to hold brainstorming sessions during the discovery phase. Please note you are not bound to use the above tools and tech stack; you can stick to the tools you and your team are familiar with.


In the context of BDD, Discovery refers to a structured, collaborative practice for specifying software requirements with examples. The idea is rather simple; get the developers, testers, and the business together in the discovery brainstorming sessions, so the new feature is looked at from all perspectives. This would diminish any possible ambiguity in the future and forms a shared understanding amongst the team.

In our example project, the product owner identifies the need for a name field to be added to the application. Since it’s a new feature, a discovery session is held with testers, developers, and product owners. As its a relatively straightforward feature, a couple of developers quickly come up with the following points on the board:

This is when things get interesting; if this session was held with developers only, it would have ended at this point. But, the product owner and a couple of the testers are in the meeting, and they start to ask the crucial “What if….” questions. Things start changing rapidly:

As shown above, the team questions the validations put in place by developers at the start; thus, they decide to proceed with a single field, no chars limitation, and allow special characters.


In the context of BDD, Formulation is the step at which the examples explored in the Discoverystep are formulated into business readable and executable scenarios using a specification language such as Gherkin. Writing quality Gherkin scenarios is key to the success of BDD; consequently, at SpecFlow, we have taken it upon us to educate newcomers to Gherkin and provide the right tools for them to do so. Check out our Given-When-Then blog series to learn tips and tricks on writing good Gherkin and use our Online Gherkin Editor, which adds handy features such as syntax highlighting to aid you in writing better Gherkin.

Gherkin feature files also evolve and go through different phases. In our example project, we started off with a rather complex one first with some information that was unnecessary but with feedback from the team pouring in it finally got to a simple but informative form:

At this point, a developer raises the fact that the development team and testers know exactly what fields already exist in the application; therefore, the table in the Given step is unnecessary as it contains data that can be moved to automation with some default values. The feature file goes through its first “refactoring”:

Another feedback comes in from a tester that the Then step also contains information related to saving the data and not validations, which is what this feature file is about. The Then step is then refactored to only include relevant information:


A final touch here is to link the work item that this feature file refers to. This can be added as soon as the work item is prepared. The real advantage of this will be demonstrated in the Validation step when living documentation is generated. To link a feature file to its relevant work item in any tracking system, you must first tag the work item ID in the feature file and later on during the living documentation generation step, add in the URL. Further details on how to do this can be found here.

In our example project, we used Jira as our tracking tool. The work item ID is CCSP-1; hence the tag is added in the feature file as per above. The feature file is then saved directly from the Gherkin Editor and attached to the work item in Jira:

With the feature file ready and in final form and linked to its corresponding work item, all the team members now understand precisely what is being developed. The team then moves on to the next step, Automation.


In the context of BDD, Automation is where formalized scenarios are turned into automated acceptance tests to check if the system conforms to the specified behavior.

In our example project, the developer downloads the feature file from Jira, adds it to the project and begins implementing the step definitions. The step definitions are the automation code behind each Gherkin step that actually does the testing. The SpecFlow for Rider plugin has been used in this project to take advantage of its various features for an easier automation experience. Any other necessary step, e.g., adding the new field to the database, is implemented in this step.

If you like to see the details of the code behind this application, you can download the entire project repo here. Some key/interesting points from the code:

[When(@"the submission entry is submitted")]
public void WhenTheSubmissionEntryIsSubmitted()
var restRequest = new JsonRequest<Submission, string>("api/Submit", _submission);
_submitFormResponse = _restClient.Post(restRequest); 
[Then(@"the submitting of data was possible")] 
public void ThenTheSubmittingOfDataWasPossible() 

With the Automation work done implemented, and the test results passing the team moves on to the next phase, Validation.


The Validation step is where, as the name implies, the automation work is validated against the formulated steps. This phase can get a bit complicated for non-technical users to keep up with as the test results usually reside within IDEs. Not every user is comfortable navigating around in the project within IDEs; luckily, SpecFlow+LivingDoc bridges this gap. LivingDoc can be added to any CI/CD system as a separate build step and every time a new release is triggered a new version of LivingDoc is also generated. LivingDoc carries all the necessary information needed to understand what steps have been implemented and the test results for each step.

In our example, we used the JetBrains TeamCity CI/CD tool. The LivingDoc build step was added so that a new version of LivingDoc is available for the entire team to view with every new release. Here is a view of the build:

As shown above, the LivingDoc build step is added after the application build and test. The generated living documentation is a local self-hosted HTML file that can then be shared easily within the team. SpecFlow+LivingDoc can also be generated without test results; therefore, worth adding it at the start of every project to have an overview of all the feature files before any implementation is added. Check here to learn more about SpecFlow+LivingDoc and how it can help you and your team.

The LivingDoc shows all the tests for the new feature passing and development completed on this new feature.

The important and key takeaway from this article is gaining a perspective on how Behaviour Driven Development can bring down the barricades between technical and non-technical team members of a development team and promote a shared understanding amongst them and also how different SpecFlow products can facilitate this journey for development teams to have a seamless and intuitive experience.

This article is based on a webinar held by the SpecFlow team, you can watch it here.