Specification and Example (SaE)

In order to achieve a shared common understanding of what "it" is that should be built and try to build "it" right the first time, you can use Specification and Example mapping approaches (note that we use "Specification and Example" as an overarching term for multiple approaches).

A Specification and Example approach is a collaborative approach to define requirements and business-oriented functional tests for software products, based on capturing and illustrating requirements using realistic examples instead of abstract statements. You will find many discussions on the internet about the differences – if any – between these approaches, but in the end they all support trying to achieve the above-mentioned result.

Some commonly used approaches are:

  • Specification by Example (SbE)
  • Example-driven development (EDD)
  • Executable requirements
  • Acceptance test-driven development (ATDD)
  • Behavior-driven development (BDD)
  • Agile acceptance testing
  • Test-driven requirements (TDR)

DevOps SaE collaboration approaches

For a SaE session, you need input from the stakeholders, preferably from all stakeholders, known as the whole-team approach. To perform this properly, there are a few preconditions:

  • Stakeholders must be available.
  • Stakeholders are preferably co-located.

Advantages are:

  • Common understanding of the story / feature
  • Exploring ideas

The downside is:

  • Time consuming (although this is an investment that is earned back later).
SaE collaboration approaches

The figure above shows the collaboration approaches and the influence the preconditions, advantages and downsides have on their use. The horizontal axis shows which approaches can be applied with a co-located team and which with a distributed team. The vertical axis shows which approach is less or more influenced by stakeholder availability, and/or time consumption, and/or common understanding, and/or exploring ideas.

In a Scrum context, the three amigos approach is often used, whereas in a DevOps context preference is given to the four amigos approach.

The two most popular approaches, three and four amigos, are explained in the following section.

Three amigos

When using one of the SaE approaches, people with different perspectives are needed. A popular approach hereby is the "Three amigos" [Dinwiddie 2009] approach which refers to the primary perspectives to examine an increment of work before, during, and after development. The "Three amigos" represent:

  • Business
    What problem are we trying to solve?
  • Development
    How could we build a solution to solve that problem?
  • Testing
    What about this, what could possibly happen?
Four amigos

In DevOps you could add a representative from the operations perspective to the team and call it the "Four amigos" approach:

  • Operations
    How could we run and maintain the solution?

Depending on the situation, do the stakeholders work co-located or not, are they available or not and how much time is available? It is important to choose a suitable collaboration approach.

The Four amigos.


Specification by Example technique

When applying one of the Specification by Example (SbE) [Fowler 2004] mapping approaches (such as ATDD and BDD) a pack of 4-coloured index cards is often used to capture the different types of information as the conversation unfolds. The information is captured on index cards and arranged in a map.

  • As a start, the feature or story under discussion is written on a blue card and placed at the top of the map.
  • Next, each of the acceptance criteria, or rules that are already known, are written on a yellow card and placed across the map beneath the blue story card.
  • For each rule, one or more examples are needed to illustrate the rule. These are written on a green card and placed under the relevant rule. (Note that some test design techniques may be helpful in illustrating rules.)
  • As these examples are being discussed, questions may be uncovered that none of the participants are able to answer. These questions are captured on a red card and the participants move on with the conversation.
Example mapping.


For a complete example, see figure above. In the figure only "true" examples are given, you can expand these with "false" examples and expected results.

A SbE session is timeboxed. A SbE session becomes less effective if it lasts longer than 30-45 minutes. Because after that, the attention span decreases and creativity and engagement drop. In general, you could say that if you need (much) more time, the user story is most likely too long and should be broken down into smaller user stories.

Example SbE mapping – Determine shelf life.


Although SbE does not have any formal requirements for how the user stories should be written, the Gherkin syntax is often used. Gherkin is a commercial, readable domain specific language (DSL) created specifically for behavior descriptions. Writing the Gherkin scenarios during the session could be time-consuming. For this reason, some – more experienced – teams leave the actual writing of the Gherkin scenarios until after the session.

Gherkin scenarios are input for all DevOps activities; as such they are also the basis for test design using coverage-based or experience-based approaches.

The Gherkin keywords are [Gherkin 2020]:

  • Feature
  • Rule
  • Example (or scenario)
  • Given, When, Then, And, But (steps)
  • Background
  • Scenario outline (or scenario template)
  • Examples
  • """ (Doc strings)
  • | (Data tables)
  • @ (Tags)
  • # (Comments)


A simple example using a few of the Gherkin keywords:

Feature: Stock
     As a web shop owner,
     I want to keep track of the amount of sold products,
     so that I know how many products are left in stock.

Scenario: Selling
     Given there are products
     When I sell products
     Then I should have products

       |    start    |    sell    |    left    |
       |    50    |     5    |    45  |
       |    50    |    10   |   40   |
       |    30    |     5    |    25   |

If you wish to know more about how to use Gherkin keywords, we refer to https://cucumber.io/docs/gherkin/reference/#keywords.

Popular Gherkin compatible automation tools are: HipTest, Cucumber, Easy B, JDave, Concordion, JBehave, FitNesse, TestLeft, BeanSpec, SpecFlow, Robot, Watir and Twist.