Delightful Requirements: Scenario Names - Read well when collapsed

in

When I first began writing Gherkin scenarios, I tended to use scenario names as labels.  For example, I almost always started with:

Scenario: Happy Path

The subsequent scenarios would also often get a tag-like name.  For example:

Scenario: Required fields

Or

Scenario: Daylight savings time change

But, I have come to view scenario names as playing an important role in communicating to business stakeholders.  They provide an opportunity to articulate a behavior concisely and in expressive business-oriented language.

In fact, I love to see scenario names written in such a way that, when the steps are collapsed out of view, the scenario names read well as a description of how the feature works.  The collapsed view of the feature file becomes a valuable tool in communicating to certain audiences.  

For example, on a recent project, we prepared scenarios for a new feature and began to review them with a key business stakeholder.  It quickly became clear that he was finding the detail in the steps tedious.  So, we collapsed all of the scenarios down to their titles.  He was immediately more engaged, confirming scenarios and asking meaningful questions that gave rise to new scenarios.  Of course, we still collaborated with other business stakeholders on the details in the steps.  But, it was extremely helpful to have an intermediate level of detail that encouraged good communication.

Here is a simplified example.  Do you find this list of collapsed scenario names more helpful?

Happy Path
Required Fields
Valid id format

Or, would you rather discuss these scenario names with a business stakeholder?

Creating a widget adds a new widget to the system
Prevent creating a widget unless the widget name and category are provided
Prevent creating a widget with an id that is too long

I believe scenario names deserve careful attention for the purpose of readability.  Future posts in the Delightful Requirements series will offer suggestions for expressive, readable scenario names.

Delightful Requirements: Hide distracting details

in

One of the most common mistakes made when adopting Gherkin style requirements is to simply port existing test scripts into the Gherkin syntax.  The result is a scenario detailing every mouse click and value entered on the way to the behavior being tested.  It is extremely hard for a business stakeholder to focus on the requirement amid all of the details.

So, good Gherkin scenarios will hide all of the distracting details.  When testing a user interface behavior, hide as many navigation details as possible.  When laying out the data involved, list only the elements that matter to the test.  Other scenarios have likely described all of the intermediate navigation requirements and have focused on the other data elements.  Let the test implementer worry about how to get there and how to fill in all of the other fields with valid values.  Make it easy for your readers to focus on the specific requirement at hand.  

Hide distracting details!

Delightful Requirements - Examples are your friend

in

At Amplified Development, we are strong proponents of using examples liberally in your specifications.  Examples just make requirements better.

The main objection to examples is that they make test implementation more difficult.  This is true; but, the level of difficulty may depend on your strategy for test data.  (Test data strategies deserve a discussion of their own.)  But, regardless, you should work to overcome or mitigate the difficulties, because examples are just so important to good requirements.

So, why are examples so wonderful?

  • Examples ensure you are on the same page.  Have you ever had a discussion about requirements where, after investing quite a bit of time, you discover you aren't talking about precisely the same thing?  No?  Then, I'm guessing you haven't worked on many requirements.  As soon as you introduce an example, such misunderstandings get revealed.
  • Examples promote exploration.  When a requirement is expressed with an example, there is a strong tendency for stakeholders to raise other examples with interesting variations.  True, even without examples, it is possible to have a discussion of variations and exception conditions.  But, without examples, focus is given to the phrasing of the rule and the exploration of variations often suffers.  Its just human nature: give an example and someone will offer another.
  • Examples can clarify boundary conditions.  Without examples, you can try to express a rule with precision.  But, there is nothing like stating which date is in range and which is not, which number is under the limit and which is over.

As we explore specific ideas for delightful requirements, you will see this theme over and over:  Examples are your friend!

   

Delightful Requirements: Seeking the sweet spot

in

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.

Delightful Requirements

in

(Note: The series on Extreme Remote will continue as a weekly post next Monday.  At this time, we are launching a second series of posts with the theme:  Delightful Requirements)

Requirements.  You're gonna have 'em.  Whether they are a hallway conversation with the developer, or a ten-pound doorstop of a requirements document.  Somehow, there needs to be an agreement of what software should be developed before the code gets written.

In an agile development process, you should avoid Big Up Front Design; but, you still need requirements.  Ideally, the requirements are drafted some time before a sprint starts.  Then, during sprint planning, they are reviewed, adjusted, approved, and committed.  The form of these requirements may vary.

At Amplified Development, we are enthusiastic proponents of Gherkin requirements (aka Cucumber, SpecFlow, Behave, etc.).  Gherkin is a structured language that is designed to be easily understood by business stakeholders, and to be readily wired up to automated test code.  It has this basic structure:

Scenario: Feature performs desired behavior
  Given some prerequisite state exists
  When I take some action
  Then I can verify the desired behavior occurred

This is the first in a series of posts that describes best practices for writing Gherkin.  Your goal, simply put, is to write requirements that delight those who read them, whether they are business-oriented, developers, or quality assurance experts.  (It may be hard to picture anyone being delighted to read software requirements; but, for those with skin in game, well-written requirements just make every iteration, every day, go more smoothly.  And, who wouldn't be delighted with that?)  Business-oriented stakeholders should sense that you have captured how their business really works and have described a software system that will make their business work better.  Developers should readily form a clear picture of the software they must create.  Quality assurance experts should feel confident that little ambiguity exists and problem cases have been adequately covered.

We will first discuss a few high-level principles that will provide guidance towards high-quality requirements:

  • Seek the sweet-spot between meeting the needs of business stakeholders and those of developers.
  • Examples are your friend
  • Hide distracting details