Unit Testing with Example Maps

devkevyn profile image devkevyn ・4 min read

One of the hardest things in making unit tests is thinking on what to test for in a piece of code/feature you just wrote. Usually, what we do is think of exhaustive ways to use a piece of code wherein most test cases don't really add value to the project and just wastes our time. The best depiction of this problem is with this picture from devhumor:


So how do we solve this problem? Let me introduce you to Example Maps

Taken from Behaviour Driven Development, Example maps are to put it simple a bunch of test cases that are formulated from a business/product user point of view. What this would mean is we make test cases that adds value to the user more than to the developer.

I know this sounds horrible as a programmer. But, it's not. It actually helps us. How? By helping us prioritize what to test for and help us balance between writing features and writing tests for those features. This doesn't mean the 100% test coverage is going away, (this does not help all the time, but it's a different topic) but rather we go for what matters to our users first with the limited time we have and can do the rest later.

What do we need?

  1. Find collaborators
    To make example maps we preferably want the developer involved in the feature/code, the person who came up with the functionality (ex. UI/UX teammate or business owner), and the QA person (if you have one).

  2. The mapping tool
    This can be pieces of paper on a board or software. In our company, we use a software plugin with our jira board.

  3. The feature to breakdown
    The preferable way to do this is to break down your features into the agile methodology user stories first.

What concepts do we need to know?

The example map has 3 key components:

  1. Rules
    these are a list of possibilities and limitations for the

  2. Examples
    these are the real world examples of the rules we came up with above

  3. Questions
    clarifications about the feature that can't be answered during the example mapping session. Usually, these are converted to rules or a separate user story once answered.

example map

Example maps are done in an example mapping session

These can be timeboxed to a maximum of 30 minutes. We noticed going beyond this length is already counterproductive for the people involved. Example mapping session for a feature can be done multiple times. Oftentimes, we would do 1-2 sessions for a feature. Doing more than this would mean the feature wasn't broken down properly.

Can we see an example of how this goes?

For example our company is in charge of a dating app. We have broken down the features to user stories and have decided for this example mapping session we will use the "As a user, I am able to choose my dates by gesture swiping them"

The collaborators then start the timebox and ask each other to come up with rules.

Developer: "I think users can only swipe left and right. Left being rejected, right being I'm interested."
UI/UX person: "Yeah, that's a good way to choose."
QA: "agreed."

Developer then writes down the rule:
"Can only swipe left and right"

Then writes down the examples:

  • "User likes the guy/girl, swipes right"
  • "User doesn't like guy/girl, swipes left"

Sometimes rules don't have examples if it makes sense.

UI/UX person: "The user should see be able to change his online status and see it."

UI/UX writes:
"can choose to stay offline"

QA: "I don't think this need examples. The rule is an example already. But, we can write a separate rule for the status icon"

QA writes:
"see notification when changing online status"

Then QA writes down the examples:

  • "User sees red icon when going offline"
  • "User sees green icon when going online"

Then this process goes on. Sometimes, questions happen.

QA: "What if the user really likes this guy? Can they make the other person know?"
Developer: "I'm not sure business wise. But, it can be implemented."
UI/UX: "That is a good suggestion, I'll ask the business owners later. Let's write this down as a question first."

Then writes down the question:

  • "Do we want a special like feature?"

Once timeboxed is reached the session ends.

Developer: "Ok, I think that was a productive session. In total, we have 5 rules and 1 question only."
QA: "Let's do this session again same time tomorrow. I think we just need this question be answered and we're done with this."
UI/UX: "Ok. I'll forward this question later."

What do we do with the example map?

Once all questions are answered the example map can now be used by the developer to write unit tests. The usual way is to convert these example maps into Gherkin to be used with Behaviour Driven style unit testing or you can just go vanilla unit testing. The best thing is now we have unit tests that bases itself on actual use cases by the software user which we can prioritize. Later, once you have enough time you can go back and add the more technical testing needs of the code. Not only are you more productive, but you can keep the business happy also.

What if there was a bug later on or missing rules and we didn't have an example map for it?

Simply plan another mapping session and add more things you missed. Software projects are iterative and so do our example maps.

Hope this helps!

Posted on by:

devkevyn profile



A non dev trying to love development


Editor guide