The goal when writing requirements in Gherkin for automation can be expressed this way:
It is the quest for the sweet-spot between lucid language and efficient test implementation.
If we focus on just one goal without the other, we will frustrate one of our primary audiences.
Writing for business users only
We might write Gherkin scenarios that communicate effectively to the business user, but are not readily implemented by a developer. For example, consider this scenario:
Scenario: Widgets must have ISO Standard temporal flubargle settings When a widget has incorrect temporal flubargle settings according to ISO 5432 Then that is an unacceptable widget
The business user might like this requirement very much. But, the developer implementing the test will have a multitude of unanswered questions: What are correct and incorrect temporal flubargle settings? What action is being evaluated in this test? What does it mean for the widget to be unacceptable? What behavior should the system exhibit for an unacceptable widget?
Writing for developers only
Even worse, we might write Gherkin scenarios that are tailored for the developer, but are incomprehensible for a business user. For example:
Scenario: Widgets must have valid CF_101 and RV_999 values Given a widget entity with these fields: | CF_101 | RV_999 | | 10-2-2015 | 33 | When I POST that entity Then the HTTP status code should be 400
If you write API code for a living, you can probably picture how to implement that test. But, the business user will need every clause of that scenario interpreted for him. That will seriously inhibit the meaningful conversation a scenario is intended to initiate.
Writing for both audiences
Requirements writers earn their keep when they keep implementation in mind while they write in the language of the business user.
Perhaps the scenario could be worded this way to serve both audiences:
Scenario: Widgets must have ISO Standard temporal flubargle settings Given this widget: | Sample Date | Flubargle Value | | 10-2-2015 | 33 | When I attempt to create this widget Then I should be prevented from adding this invalid widget
The search for the ideal balance has few absolute rules. The right balance for one organization may differ from another organization. The important thing is the constant focus on serving both needs.