Give your tests a story

One thing that I remember distinctly from my college classes was how purely academic our assignments and lectures were. Why couldn’t we get “real world” examples? This was a real problem for me because I struggled to connect the dots about the topic when all the principal points were only abstract theory. There were no concrete, tangible things in my life with which to associate the knowledge. In fact, programming didn’t really click for me until my first (college) job when I had to write code to solve – you guessed it – real world problems.

So, what does this have to do with tests?

Much the same as those theoretical situations in my college classes, the unit, integration, and functional tests that we write tend to be generic & ambiguous. When we come back to them after some time has passed, it's often not clear what we were testing. Even worse, when we're writing the tests we can miss crucial pieces because the code is so abstract. 

So, let's take that learning from above and apply it here. When setting up a test situation, you have the opportunity to be an author. You can create a storyline about the user who is using your product and trying to get value from it. Not only will this make your test more memorable, it will make it more comprehensible.

An example

Perhaps you’re writing code for marketing software and testing a new Push Notification action. To do this, you need to create a marketing campaign, configure a campaign action, and create some dynamic content (we’ll use Jinja in this example).

The naive way to approach testing your new Push Notification action would be something along the lines of “test_action = …” and “assert test_action …”. However, that name doesn't give us much context to work with; nor does that assertion have a real world expectation. So, how can we make this more memorable and furthermore how can we make it easier for future readers to understand?

The answer is that we can give our tests a story.

Marcia is a marketer who works at Acme, Inc. She uses your product to help increase the LTV of their shoe purchasing customers. Marcia is planning a big event for the launch of a new shoe design. The Push Notification action you just built is going to be critical for Marcia to engage with the younger crowd that Acme is targeting for the launch.

The test variables and values might look like the following:

  • Campaign Name: Acme Shoe Launch, testing Push Action

  • Campaign Action: Your Push action

  • Push subject: 👟Get excited for your next shoe!

  • Push body: Is it time to replace your {{ customer.acme_most_recent_shoe_name }}?

Wow, that was fun! You got to use a realistic contact property in your jinja and it’s obvious to anyone who encounters this test what you were doing. Most importantly, if you need to dig this up in a few months, it’s going to be a lot easier for you to (a) remember it and (b) distinguish it from your other test campaigns.


  1. Consider the ability for others (and even your future self) to understand what you’re trying to test based on the scenario and names you choose.
  2. Consider the likelihood that you’ll spot problems or edge cases by choosing a scenario and set of names that more closely reflect the reality of an actual user.
  3. Consider the ease with which you’ll be able to dig up an old test case or functional test object later down the road when you need to refresh or remind yourself of something.


Recent posts