Agile software development: Tips for writing testable user stories

Many testers on Agile projects struggle to keep up with the pace the development team sets in terms of story delivery. In time-sensitive environments, it’s critical for the tester to get a leg up on testing by having clarity in what needs to be tested.

In addition, most Agile teams have extensive unit and functional test automation that tell the developer when she’s done with development on a given story. Given both of these situations, you’d think we’d be a bit more rigorous with how we write our stories to make sure it’s clear to both developers and testers what needs to be tested. In this article, we look at some simple techniques for making your stories practically test themselves.

Templates help you remember what’s important

There are a number of methods for writing user stories, and a popular technique for teams getting started is to leverage a template. One such story template that I really like is Dan North and Chris Stevenson’s story framework for behavior driven-development:

As a <role>, I want <feature>, so that <benefit>.

Here are a couple of examples:

• As an unauthenticated user, I want to see the login link in the upper right hand corner of each page, so I don’t need to navigate back to the homepage or some account page to login.
• As a sales associate, I want to be able to pull up my current active leads, deals and tasks on my iPhone, so that I can still follow up with clients and update deals status while traveling.

Those look good right? You get an immediate feel for who cares about this story, what they want, and why they want it. However, when most teams write stories using this template, what typically happens over time is something like this:

• As an unauthenticated user, I want to see the login link in the upper right hand corner of each page.
• As a sales associate, I want to be able to pull up my current active leads, deals and tasks on my iPhone.

It’s exceedingly easy to leave off that last piece of the story. To the person writing the story, it’s obvious why the user would want that feature. However, to the developer and the tester, it’s not.

For example, with the first story, I might conclude that the login link in the upper-right hand corner of each page should take you to a login page. However, when I read the original story, it’s easy for me to see that the benefit is fewer clicks to login -- the user doesn’t want to leave the current page to authenticate. With that knowledge, I can design an Ajaxy solution to keep them on the current page and still authenticate.

Don’t leave the benefit of the story off of the story. Even if you’re not using a template, make sure it’s clear why this feature is important. That gives powerful insight to the developer as they design the solution. It gives valuable insight to both the developer and tester when they assess risk for what should be tested.

Nothing is clearer than an example

Example-driven development isn’t a new idea, but it is a concept people often forget to leverage. When you’re writing complex stories, sometimes the best thing you can do is include a couple of examples. Sometimes a mock up is good enough, other times you might include a reference to a product that does something similar. Getting to a practical and real example someone can look at or interact with is invaluable to clarify scope.

Another great way to get clarity is to specifically list out what will be demonstrated at the end of the iteration. What screens will the team need to show off? What business processes or transactions? What documentation do they need to show? Using what platforms? Listing out a “script” for what you want your demo to look like is an awesomely powerful -- and simple -- way to provide clarity on what your expectations are.

Another way to provide examples -- and one of the most popular Agile techniques -- is to include acceptance tests with the story definition. One popular format for doing this is the Given, When, Then format also developed by Dan North and Chris Stevenson. Similar to the role/feature/benefit story template above, this provides a simple template for generating targeted tests for specific conditions the story author cares about.

Here are a couple of examples:

• Given that I’m a sales associate and I have 30 deals, when I open the App on my iPhone, then I should see the first ten deals, and I should see pagination for the remaining 20 results. 
• Given that I’m a sales associate and I have zero leads, when I open the App on my iPhone, then I should be shown a button to “Add a Deal.”

For many teams, these tests get translated directly into automated acceptance tests. That’s a huge win. However, it adds a benefit past its immediate value to the developer. A tester who sees these tests benefits in two ways:

1. They know the developer has likely already tested these use cases, freeing them up to focus on other use cases the developer or story author may not have thought of.
2. It provides them with more insight into what’s important for the author of the story -- this will inform their ideas around risk and coverage for this story.

Write down what’s not covered by this story

A very powerful technique to making sure the team knows wchat they need to test is to tell them what they don’t need to test. This is incredibly helpful because it allows them to focus more energy on the areas that are in scope. It also has the added benefit of reducing the risk of gold plating from developers and bugs from testers that no one will care about.

Given the iterative nature of Agile development, this also plays to one of the great strengths of the approach. By making it clear what doesn’t need to be covered in this story, you’re basically tasking out possible future separate stories for the backlog at the same time. This will lead to smaller more estimable stories.

Here are some examples of what I’ve seen excluded in the past:

• This story should cover implementing filters and sorting for search, but it does not need to address how those features will be accessed by the end user.
• This story does not need to cover implementing SSL for this feature.
• This story does not need to cover data provided from “vendor X.”

Another way to do this is to list both what is and isn’t expected:

• We should accept Visa, MasterCard and Discover, but not Amex.
• We should allow registered non-premium users and registered premium users to use feature X, but not trial users or unauthenticated users.
• This story should cover error handling for errors returned by the 3^rd party service provider, but does not need to cover handling errors from general connectivity problems -- those will be covered in story X.

List separate deliverables as tasks

A final technique for making sure your stories are testable is to detail out what’s actually getting delivered as part of the story task list. That is, if you’re delivering multiple pieces of code, documents for training or user manuals, or design/marketing artifacts -- all those need to be tested. Sometimes it’s not intuitive what all is included in a story if these items aren’t called out explicitly somewhere.

Try to be specific. If you have multiple documents, task out each one on it’s own. Don’t fall into the trap of just tasking out “documentation.” Instead, list the specific documents or types of documentation you’ll need to update to complete this story. If your code spans multiple interfaces or ends up having logic specific to certain platforms, list those too.  The more detailed the tasks are in terms of showing what’s actually been “touched” to deliver the story, the easier it is to know what you need to test.

Implementing all of these tips all the time would be overkill. If you did, you’d likely produce something reminiscent of the days where we had pages and pages of requirements documents no one read. However, implementing a couple of these tips for each story you write is likely a great way to make sure your team has what it needs to deliver solid, scalable software that impresses users and product owners -- on time. For more on using story templates, check out Dan North’s article on Introducing BDD, available here.

About the Author
Mike Kelly is currently a partner at DeveloperTown, a venture development firm. He regularly writes and speaks about topics in software testing, but spends most of his time working with teams to deliver ridiculously high quality solutions faster than they could without rigorous testing practices. You can learn more about Mike and his other works on his website, http://www.MichaelDKelly.com.