Behavior-driven development (short BDD) is all about examples. They are used to explain what should happen when certain events occur and what exactly the meaning of a certain requirement is. So far all is simple and straight-forward. The challenges come with writing those examples. There are different ways to express the same ideas and not every style works with every audience.
Code Style
As the name suggests, the code style looks very technically and contains a lot of details:
Given I navigate to http://localhost:9999/Person/Create
And I enter Sherlock into the input with an ID of FirstName
And I enter Holmes into the input with an ID of LastName
When I click the element with a CSS selector of .btn.btn-primary
Then the div with an Id of successMessage should contain the text Sherlock Holmes
Most developers who start writing examples use this style. You can see exactly what is going on and not much needs to be interpreted. And that is the biggest problem with this style of scenarios: they are too detailed. As a developer you can read the code. That’s the place where all the details and field names are specified. To write the examples in the same style means you duplicate code. Even worse, the business doesn’t understand this and stops participating.
Imperative Style
The imperative style addresses the problems of the code style and is often shorter:
Given I am on the movie character form
And I enter a first name of Sherlock
And I enter a last name of Holmes
When I submit my form
Then I should see the character created confirmation for Sherlock Holmes
The imperative style can be read with much less technical knowledge. However, the technical aspects and the user interface elements tend to come up on a regular basis. You still mix technical terms with business rules. For developers all seems to be ok, but what exactly is the business rule in this scenario? It looks as if the example above is about a form with two fields. How many of your forms are that simple? How do you write a scenario in this style when you have 10 or 20 fields?
Declarative Style
The declarative style is much more abstract and focus on the bigger context:
Given I am on the movie character form
When I submit a valid form
Then I should see a confirmation
Focusing on the business impact and what the measurable result should be helps to clarify what should happen. In this case the user doesn’t care what input the form will have, the important aspect is that there will be a visible confirmation when the action succeeds.
This style isn’t blocking the way for change – new fields in the form don’t interfere with this example. You even can change the confirmation completely; it doesn’t matter if you change the appearance or the text of the message. As long as there is still a confirmation this scenario works without modification.
(The glue-code who matches this example with your application does change – ideally by the same developer who changes the code of the application.)
What style to choose?
There isn’t a simple answer to what style is the right one. Try not to describe the user interface and capture the need behind a requirement. The need may stay while the technology, the user interface and the way things are done, change. If in doubt, go for a declarative style and skip the details until they are proven to be vital. Then add more scenarios to explicitly state the different aspects of a feature you want to cover. Only then dive into details should they still be needed.
The examples above show you different ways to describe the same feature. They differ in the details and the technical terms, but they all work with the same form in my demo application. Liz Keogh (@lunivore) explained something similar in her blog after exchanging ideas about this topic with Dan North.
While I support the idea of different levels of abstraction fully, I don’t go that far to say those styles don’t exist. I think they help communicating the difference and should be used until we find better names to express the abstraction in our examples.
Conclusion
Talk about the feature you try to implement and use only as much details as you need. If the problem demands details, describe it as such. But remember, more abstract examples don’t need to be changed that often.