Originally posted at specflow.org, 2 July, 2020

In Part 1 we have discussed how we can ensure shared understanding in remote environments using examples during the online requirement workshops. As mentioned there, those workshops focused on getting the most out of the precious time together, therefore the result (the rules and the examples) have been captured in a simple form, not using Given/When/Then.

Let’s say we had an online discovery meeting where we collected illustrative examples for our user story on a Miro board as virtual sticky notes. Those examples are enough for the participants to start working on the story, but we want more. We would like to have our findings properly documented (so that it is understandable even a few months later) and we would like to verify whether the implementation that we are going to produce is fulfilling those expectations. Such documentation would be also useful for those team members who could not join the requirement workshop.

With BDD, we transform the examples into BDD scenarios using the Given/When/Then keywords and save them to feature files. This transformation, the practice of writing BDD scenarios is often called “Formulation“. The format of the scenarios and keywords is called Gherkin. The scenarios written with the Gherkin syntax can be executed as automated tests by different tools, like SpecFlow or Cucumber. With the scenarios automated and executed, our documentation can be kept up-to-date all the time, hence it can also be called living documentation.

There are plenty of good hints and practices on how to write good BDD scenarios and these are also true and important in remote environments. In our book “Rose, Nagy. Formulation – Express examples using Given/When/Then (BDD Books 2)“, we have summarized the most important principles using the BRIEF mnemonic: Business readable, Real data, Intention revealing, Essential, Focused and brief.

The formulation can be done in a distributed way, but doing it by a single person is not ideal, because it is easy to get stuck in a wrong thinking model. In many BDD teams, the scenarios are formulated by a pair of people. Most typically a tester works in pair with a developer, where the tester can focus on the business and testability concerns and the developer can match them to the automation and the system architecture. Finding an hour’s time where the pair can work together on the formulation of the examples is not that difficult, even if we need to adjust our daily routine to other family members we are home officing together with.

For online formulation no special tooling is necessary.  Any editor would be sufficient that you can share with your pair. As the feature files are normally version controlled (e.g. using Git), the pairs can also choose to save their newly formulated scenarios to a source control branch and submit them as a pull request. Using this approach, you can let other team members or business stakeholders get a review of the scenarios and/or formally approve the expectations that the team is going to work on. You remember, don’t you, we wanted to avoid rework caused by the reduced chances of feedback. So it is better to make sure that we work on the right thing.

Good Gherkin scenarios are business readable, and via automation, they verify the application. When they fail, the failure is understandable both by the business side and the delivery side of the project. So essentially they make a connection between the problem and the solution or with other words the members of the distributed team. Scenarios represent our shared knowledge and shared responsibility to produce quality software.

In the next part…

In this post, we have seen how the expected behavior can be efficiently documented using the Gherkin syntax so that it provides exact guidance for remote team members to work in a distributed setup. Formulation, the activity of turning an example to a scenario, can be done the best by a pair of people. The pair should review the business language and the phrases used in the existing scenarios and based on that write the scenario. The scenarios capture the expected behavior in a business readable format but can be processed by BDD tools, like SpecFlow or Cucumber to turn it into automated tests. These tests can drive the development process.

To get the full benefits of the BDD process, we would like to turn these automated BDD scenarios into living documentation. In remote environments, we are more dependent on shared information that we can access in a distributed way. In Part 3, we are going to give some hints on how to make the living documentation better accessible.