BDD: Setting the scene by setting an example

author avatar

Brian Ansems

I’ve mentioned before that requirements can be structured as tests, following the format of Given, When, Then. At least to my mind, this helps me write requirements with greater coverage of documentation. However, it’s important to not lose sight of the fact that you are creating a solution for real-world users who will only interact with what you’ve developed for their own specific needs. For this reason (and others), documenting your requirements as Scenarios is a valuable practice.

What do we mean when we say Scenario? Well, this is a simple example of what a scenario might look like when written as a requirement:

Scenario: User updates their profile information 
 Given my current profile information is out of date 
  And I update my profile information 
 When I save my changes 
 Then my profile information should now be up to date

Here, we’ve written a scenario with a user in mind with a clear want, to update their profile information. We’ve stated what would need to be true for the user to want to update their profile information. We’ve described that they should be able to provide new information, and have stated that there should be a trigger to implement and save those changes. This should result in a valuable outcome for the user. And importantly, we’ve written this scenario using plain, natural language. It’s easy to understand and read, while still following that testing format we’ve discussed earlier.

Be more specific

Depending on the level of specificity your client would like, or even that of your developers, we can also provide more value within our requirements by detailing a clear example for our scenario. In the case of the above scenario, we can supply what sorts of information the user may wish to update.

Scenario: User updates their username 
 Given my current username is JohnSmith 
  And I enter a new username BillStevenson 
 When I save my changes 
 Then my username should be BillStevenson

Now, our scenario is quite a bit more specific and takes advantage of using a real-world example of a user’s interaction with our solution. Using examples, we further our goal of providing more coverage in our documentation. Specifically, we’ve established that users will have usernames as part of their profile information. And we’ve also managed to retain our plain language format when being more specific.

Be detailed

It can be difficult for people to understand solutions in abstract thoughts. This can be especially true for people involved with software development. Developers require specifications that are detailed enough for them to know that they have built a solution appropriate for the problems attempted to be solved. And clients need to know that the solution you are going to build will actually provide value to either themselves or their own clients who have specific use cases and behaviour.

As analysts, training ourselves to document our requirements using clear examples can help us achieve both of these goals. Without trying to use too much jargon, this practice is specification by example. The more we can document using examples, the more we can understand the intended user while communicating the value of our solution to clients and providing the specificity required by our developers.

Clear examples equals more value

Our example shown above is very simple. It is only meant to illustrate how when we think in terms of clear examples of user behaviour, we end up providing more value to all stakeholders involved. However, there are plenty of tools available to us to continue this practice with greater clarity, uniformity, and efficiency. And if it’s an option for you and your team, documenting your requirements with detailed examples will help provide the necessary data when automating your requirements as acceptance tests. Check out some of the resources below on how specification by example can be achieved.

More articles

; ;