Martin Roest

Example mapping

Martin Roest Programming, Technology

In this article I want to talk about the use of behavior driven development (BDD) frameworks. BDD Frameworks let you create executable specifications which you can use for automated testing and documentation. Popular frameworks include Cucumber, Behat, Behave, etc. They all implement Gherkin as a specification language.

If you have never heard of BDD or you have never played with BDD frameworks before then please go read the Cucumber documentation website and learn how it can help you in developing software.

At Ibuildings we do not practice BDD a lot. But we do use Behat in most projects. We do believe that projects benefit from BDD, but the required collaboration with the customer is often difficult to achieve. Tom talked about this challenge in his article about Gherkin.

Creating Gherkin scenarios

In our case the Gherkin scenarios are usually created by developers. They extract the acceptance criteria from the user story and define a number of scenarios that test the business rules. We discuss the scenarios with other developers on the team to check we’ve covered the important parts. That is of course not ideal and not how it should work. But we still benefit from having a test that verifies the correct behavior of the story. As a side effect Gherkin scenarios often end up being way too technical and abstract to be useful for our customers.

Only until recently I had some practical experience with Example Mapping. I found it an approachable way of working. With example mapping you work on extracting the acceptance criteria by examples. The acceptance criteria will eventually be written as Gherkin scenarios. It's a simple technique that does not require a technical, BDD or any other kind of background. Anyone on the team can participate and have valuable input.

Example Mapping in practice

So, how does example mapping work? It uses a pack of 4 coloured index cards to capture the output. You start by with writing the story on a yellow index card and put it somewhere on top of the board or table. Let’s say we have the story:

“Register user account”

Now, let the product owner describe the story. While talking about the story look for the (business) rules. In this case the product owner explains that when you register for an account an email with additional info on the account is sent as a confirmation message. You get a blue index card and capture the rule:

“Valid email address required”

When the story is described and you have captured the rules you’re going to illustrate these rules by examples. You capture examples on green index cards and put them below the rule. Come up with as many examples you need to fully cover the rule. Keep in mind to be as explicit as you can. Give people or users names and try to use real life examples. To help create the examples you can use the “Friends episode naming convention”. So, in this case you should have examples of:

The one where John registers with a valid email address

The one where John registers without an email address

The one where John registers with an invalid email address

An example:

John registers for an account with the email address and gets an email confirmation message.

A question could be “What is a valid email address?” If nobody can answer that question you capture it on a red index card and put it on the board. This will eventually give you a good insight in the things you don’t know and have to be addressed later.

When you’re done creating examples, the cards on the table will tell you something about the story. If you have many red cards on the table maybe this story is not ready for development yet. If you have many blue cards on the table maybe this story is too big and you should break it up. If you have many green cards for a specific rule, the rule is maybe too complex.

The examples can easily be written as Gherkin scenarios in the Given, When Then syntax. I think it is best to do that with a developer and tester after the example mapping session.


Example Mapping provides a very useful tool to work together with the customer when capturing the desired functionality and behaviour of the application you are building.

If you want to learn more about example mapping go and read the Introducing Example Mapping post from Matt Wynne. If you have experience, questions or feedback please share and leave a comment below.