Write Agile Documentation: User Stories & Acceptance Tests

Use the 3 Cs approach: Card, Conversation, Confirmation

We mentioned previously that:

1. User stories are deliberately simplified versions of requirements and short enough to be written on a sticky note or an index card (like the image below).

2. Since the user story does not contain all the detailed information required to start work on it, the next step is to have a conversation with your entire team (perhaps during a planning session) to discuss all the details before implementing a solution.

3. The additional details that come out of these conversations enable you to decide as a team which rules (i.e., which tests) represent how best to execute this feature. Writing these details down allows confirmation later on when you are ready to build and test the feature. Define upfront what has to work (what tests it should pass) for this feature to be acceptable. For this reason, these additional scenarios are often called acceptance tests.

Create examples Using the Given - When - Then Format

When writing acceptance tests, it is best to consider examples of how the system should behave. For instance, take the following three criteria for how an ATM might work:

1. If the customer tries to withdraw $20 and her account balance is over $20, then allow the withdrawal and reduce the account balance by $20.

2. If the customer tries to withdraw $20, but her account balance is under $20, then do not allow the withdrawal.

3. If the customer tries to withdraw $300, then do not authorize the withdrawal and show the message: "maximum withdrawal is $200."

Then write this set of examples in the Given-When-Then format where:

• Given: A set of initial circumstances (e.g., bank balance).

• When: Some event happens (e.g., customer attempts a withdrawal).

• Then: The expected result as per the defined behavior of the system.

There are benefits to using the Given-When-Then format:

• It is easy to see the set of initial conditions, the event, and the outcome. 

• This makes it easy to understand and easy to test.

Let's look at the first example from above:

If the customer tries to withdraw $20 but her account balance is under $20, then do not allow the withdrawal.

Writing that in Given-When-Then format will look like this:

Review Some Given - When - Then Examples

Note that the "User balance = $23."

You might be asking yourself, "Why did he pick $23 and not $24?" The answer: it doesn't matter. The acceptance test would have been just as good using other numerical examples.

Sometimes, the rule is also written as part of the acceptance test.

RULE: Only allow withdrawals when there is a sufficient balance.

If you think about it, the two examples of withdrawing $20 (one with a $23 balance and one with an $18 balance) are part of the same rule. Look at the second example:

Rule: Only allow withdrawals when there is sufficient balance.

Now look at the daily withdrawal limit example and write it in Given-When-Then format:

Rule: Only allow withdrawals up to the $200 limit

Putting it all together, you would end up with something like this:

Rule: Only allow withdrawals when there is sufficient balance

Now imagine that you are a new developer on the team, and you missed the planning session last week. But someone shares these acceptance tests with you. Ask yourself the following questions:

• Are these acceptance tests easy to understand?

• Did they take a long time to read?

• Does having the example and the rule help?

• Do you think you would know what to build?

Most people would answer "yes" to all these questions - with the exception of "Did they take a long time to read?"  ;)

Let’s Recap

• Acceptance tests help confirm that you have achieved your user story goals. They provide clarity to those who read them.

• Given - When - Then is a good format to consider for expressing acceptance tests in a business readable format.

• The act of writing a user story (or other Product Backlog Item) can be summarized by card, conversation, and confirmation.  

 Great job! Let’s take a look at specification workshops in the following chapter. 

 Additional Resources

• Gojko Adzic on using examples to define tests.