Software quality is like a die with many faces. Delivering value to customers is one of those faces, and we only accomplish it by giving users what they really need.

There is a high risk of not delivering exactly what the client needs because we don’t ask the right questions, we do not inquire enough or concentrate too much on a specific feature forgetting ourselves from the Big Picture. Have you faced a high rate of stories which don’t pass the final approval (from the user)? Have you had to re-work stories after you thought they were ready to go to production?

To achieve a good definition (good design of feature) it is necessary to generate discussions to clarify and confirm with customers what becomes our Acceptance Criteria.

Many times, while refining stories, we often hear “Can you give me an example?“. That’s what example mapping is about, a core practice of Agile Testing: Development guided by examples (ATDD, BDD).


What is example mapping?

It is a requirement definition technique that allows us to explore solutions to a problem using examples of rules and asking questions that will allow us to cover as many rules as possible in order to design a solution.

Each rule can have more than one example.

In the book Agile Testing Condensed we find a complete chapter called “guiding development with examples” in which they define it as one of the main practices of agile testing: “concrete examples of desired and unwanted behaviors help teams to have a collective understanding of each functionality“.


How do examples help teams?

They help us to build the right solutions. If we know what the desired and unwanted behaviors are, we can build functionalities that are less likely to be rejected by users. They become our UACs (User Acceptance Criteria) for each user story or task. Of course, the stories are discussed and refined, divided and so on.

They reduce development time, since they reduce / eliminate uncertainty and that’s one of the goals that we pursue the most in agility: reducing uncertainty (and not only to lower the estimates in the sprint planning, but; that is another story).

They make TDD super easy to implement, as they use the rules defined through the examples to design and code the tests first.

They make BDD super easy to implement, since the rules defined through the examples are written in natural language and are easily converted to Gherkin (Given / When / Then) and help us to establish all our test scenarios.

They give us the opportunity to involve users (or product team) 100% by working on them in natural language. The user doesn’t need any technical knowledge to participate in these sessions. The technical details appear later when we are refining stories as a development team.

How do we work with examples?

It’s basically about generating conversations around the functionality we want to build. We have:

  • Rules, which define what the system / platform should or shouldn’t do. They will be our acceptance criteria.
  • Examples, which describe how and when the rules take place, what they include, what specific events trigger them, how the user interacts with the system / platform through these rules and what their roles are.
  • Questions which help us to identify the correct or incorrect assumptions or explore unidentified scenarios, delve into identified scenarios and discover the “not known”.

We will need some cards, a blank space (blackboard if it’s physical) or a board if it’s online, and we are ready to talk and write.




We write the story (or what we initially think of as the story, this is also in constant refinement) on the yellow card.


We write the user acceptance criteria (or what we initially think they are, based on the conversation with users, this is also in constant refinement). They are represented on the blue cards.


We write all possible examples that meet the user acceptance criteria. They are the green cards and are placed under each rule (the one we consider to be the most accurate according to the example).


Here we record all those questions that no one in the session can answer (yet). They require further investigation or the presence of other users or stakeholders in the project or perhaps, an expert in the solution we want to implement.

That being said, we start the conversation and let questions and answers, discussions of points of view or opinions flow, until we have satisfied everything or our time is up.

Example: expense tracking project

History: As a user I want to record my investment transactions in my personal expense record to be able to get expense reports.

I have an expense tracking application in which I record all my income and expense transactions by categories, I have a record of balances in bank accounts and budget management by categories. In order to track my investment transactions, which are not current expenses, I need to establish another type of “investment account” in which I can track my investments and their yields and be able to see the changes reflected in my net worth.


Example of my initial state


Rule 1:

When I transfer money to my “investment account”, the investment amount will be deducted from my bank accounts but not from my net worth, and, in turn, my “investment account” will be increased.

Example 1

If I invest $1000, this $1000 is transferred from my bank account to my “investment account”, and my net worth remains the same.


Rule 2:

When I withdraw money from my “investment account”, the amount withdrawn should be reflected as income in the bank account but not as an increase in my net worth.

Example 2:

If I withdraw $700, this $700 is transferred from my “investment account” to my bank account, and my net worth remains the same.


Rule 3:

If I sell an asset from my investment account, the amount of difference with respect to the purchase price of the asset is recorded.

Example 3

I sell a stock at $115, which cost me $100, I have a yield of $15. That value increases my “investment account” and my net worth.


Example 4

I sell a stock at $85, which cost me $100, I have a negative yield of $15. That value decreases my “investment account” and my net worth.



  1. What happens if I don’t track the yields when I sell shares?
  2. How do I register the initial balance of my investment account, if you had already invested before and had not registered it?
  3. How do I register a dividend?
  4. What happens if there is a split in the stock?


Click here to see the full image.


As a tester, even if you don’t apply this technique to define requirements, I’m sure it can help you define test scenarios by having the User Acceptance Criteria very well defined and even automating with BDD. Don’t forget to get early feedback.

When I am designing the tests, my first input is the UAC, I look for many possible examples and I can even imagine cases which come out of the examples on which the requirements definition was based.

Writing all these scenarios seems easy but it takes a lot of practice to simplify cases to write tests.

We deliver value to customers, building the right product of the best possible quality.