What Are Examples
Examples are concrete descriptions of the expected behavior of an aspect of a solution using real-life data. Examples are useful for describing a solution and providing guidance on ways to validate it. The use of examples to describe a solution is also known as specification by example, behavior-driven development (BDD), or acceptance test driven development (ATDD).
There are two common forms used to convey examples. Both forms arose around the needs of automated testing frameworks.
Framework for Integrated Test (Fit)
The first format was created to support Fit, the Framework for Integrated Test. The intent was to enable stakeholders to provide examples in tools familiar to them (such as a word processor), which developers could then hook up to “fixtures” to produce automated tests. The examples are formatted into tables (which resemble decision tables) in HTML files.
Note: Fit was used before the letters were assigned the meaning of Framework for Integrated Test. So while Fit is an acronym, it should not be capitalized.
Gherkin
The second format is often referred to as Gherkin, which is a business-readable, domain-specific language created to support the automated testing tool Cucumber. Gherkin is written as a set of statements, each one starting with a keyword.
Feature: A brief description of what is to be accomplished. Often refers to a user story.
Scenario:
Given And And When
And
Then
AndScenario:
An Example
This example contains a set of examples from the conference submission system, specifically the ability for a reviewer to provide a review of a session proposal.
As Reed The Reviewer
I want to review a session
So That I can provide feedback to a submitter.
Examples for Conference Submission System In Fit
Examples for Conference Submission System In Gherkin:
Feature: Add Review As a track reviewer I want to add reviews
Background:
Given I am logged in as “Reed”Scenario: Review a session
Given a session exists on my review track
When I add a review to that session
Then the review should be addedScenario: Able to review draft sessions
Given a draft session exists on my review track
When I add a review to that session
Then the review should be addedScenario: Unable to review for other tracks
Given “Sam” has created a session on another track
When I try to add a review to that session
Then I should not be allowedScenario: Unable to review my own session
Given I have created a session on my track
When I try to add a review to that session
Then I should not be allowedScenario: Unable to review sessions I’m a co-presenter on
Given a session exists on my review track
And I am the co-presenter on that session
When I try to add a review to that session
Then I should not be allowedScenario: May only review a session once and must respond to existing review
Given a session exists on my review track
And I have already reviewed that session
When I try to add a review to that session
Then I should be taken to the “Existing Review” page
When to Use Examples
Examples are most frequently used to describe specific aspects of the solution, often as a way of providing further detail about the behavior of the solution in relation to a specific user story. Examples are very helpful when the team is automating their acceptance tests, but they can provide value even if the team is not automating their tests because it drives conversations around the solution’s behavior in specific situations.
The different example formats tend to be better suited for different situations as well. The Fit format works best for business rules that have several inputs and/or outputs. Fit provides a way to lay out all the possible combinations of input variables and gives the team a chance to discuss what would happen in each case and, equally important, strike scenarios that won’t happen in real life. The Gherkin format is better suited to situations where someone is interacting with the solution. Examples in this form tend to describe the initial state of the solution followed by some action and the resulting state.
If your team is using a specific automated testing tool, that tool may dictate the example format you use. But if your team is using scenarios to help build a shared understanding of specific details, feel free to use both formats in whatever way seems most appropriate.
Examples are often used as ongoing documentation, providing a fairly accurate—and ideally easy-to-understand—reference of what rules the system enforces and expected interaction behavior that the solution exhibits. We make great use of acceptance criteria in the conference submission system as a starting point when someone reports a defect, or has a question about what the submis- sion system does or should do. The examples represent the actual scenarios we accounted for because we associate automated acceptance tests with all of the code we write. When someone asks a question about the submission system, I first check the examples we have and find that when something doesn’t seem to be working right, nine times out of ten it’s because we didn’t account for that particular situation.
Why Use Examples
Examples are helpful as a way of structuring the conversation about how a solution should behave in specific situations, remembering that discussion for future reference (i.e., documentation), and providing a way for the team to agree upon how to validate that whatever the team builds is working properly. It’s very helpful to create examples as a group so that you can discuss and agree upon how the system should behave when certain scenarios are encountered. This may include discussing what type of messages the solution provides when a particular rule is violated, or actions that the solution does and does not allow.
How to Use Examples
- Meet with your “three amigos“: the stakeholder(s) interested in the particular user story, someone with a development perspective, and someone with a testing perspective. Meet near a whiteboard or flip chart paper. You may find that you discuss examples at the same time you are clarifying acceptance criteria.
- Discuss the user story to determine what the stakeholder is hoping to accomplish.
- If you created a mind map of your acceptance criteria, it may be helpful to refer to that when discussing examples.
- For each particular interaction, or rule, talk about the various scenarios that could occur. These scenarios may include
- Happy path
- Negative path(s)
- Alternative path(s)
- Edge case(s)
- For each scenario you identify, discuss whether that scenario will really occur. If it will not, disregard it. If it will, discuss the specifics, either the input and output values, or the precondition, action, and result, depending on which format you use.
- Once you have identified all the scenarios that come to mind, discuss if the number of examples indicates the need to split the user story.
- Note the examples in your repository of choice.
Caveats and Considerations
Acceptance criteria can provide the starting point for identifying examples. However, keep in mind that you do not need to create an example for all acceptance criteria. Examples are helpful for identifying clear ways to explain the acceptance criteria and conveniently lead to tests, but they are not essential for every specific item. Acceptance criteria, not examples, provide some clearer definition of the scope of a given user story, such as “How far does it go?” Examples provide deeper understanding of some aspects of that.
Create examples with real data you would expect to find in your solution.
Wait to figure the examples out until you are getting close to automating them. Examples may get into some specific implementation details and as a matter of course will tend to get identified closer to the delivery time frame, perhaps most effectively during three amigos discussions shortly prior to delivery.
Additional Resources
Bridging the Communication Gap: Specification by Example and Agile Acceptance Testing. By Gojko Adzic, Neuri Limited, 2009.
Specification by Example: How Successful Teams Deliver the Right Software. By Gojko Adzic, Manning Publications, 2011.
Gherkin description in Cucumber Wiki
Collection of BDD-related links from Liz Keogh
Behaviour-Driven Development: Using Examples in Conversation to Illustrate Behavior—A Work in Progress by Liz Keogh. LeanPub
Want to know more?
If you learn better with video rather than reading, you may want to check out Analysis Techniques for Product Owners Live Lessons, a set of video training sessions that show you how to apply analysis techniques to product ownership. Lesson 5.5 focuses on examples.
Analysis Techniques for Product Owners is available on Safari – O’Reilly’s online learning platform. Sign up for a 10-day free trial to view the video lessons.