Write Acceptance Tests
Card, Conversation, Confirmation
We mentioned in the last chapter that:
User stories are simple versions of requirements and short enough to be written on a sticky note or an index card. Since the user story does not contain all of the detailed information necessary to start work on it, the next step is to speak with the team (perhaps during a planning session) to discuss details before implementing a solution. The additional details from these conversations allow you to make decisions as a team and determine which rules (i.e., which tests) represent the desired implementation of this feature. Writing these details down enables confirmation later on when the feature is built and ready to be tested. Specify up front what has to work (what tests it should pass) or this feature to be acceptable. For this reason, these additional scenarios are often called acceptance tests.
A user story written on an index card
The XP framework provides various concepts to consider. The following document highlights these concepts - the : card, conversation, and confirmation were suggested by Ron Jeffries in 2001. The most common way to specify what is required for "confirmation" of your user stories is to create a set of acceptance tests for each user story.
Writing Acceptance Tests
When writing acceptance tests, think of some examples of how the system should behave. Take the following three examples of how an ATM machine might work:
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. If the customer tries to withdraw $20 but her account balance is under $20, then do not allow the withdrawal. If the customer tries to withdraw $300, then do not authorize the withdrawal and show the message: "maximum withdrawal is $200."
Write this set of examples in the Given-When-Then format:
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.
Note the following benefits of 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.
As an exercise, quickly write the three numbered examples above in Given-When-Then format! The best way to write good acceptance tests quickly is to practice.
Look at the first example from above:
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.
Writing that in Given-When-Then format will look like this:
Writing example 1 in Given-When-Then format
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.
Using numerical values as an example increases comprehension because it takes something abstract - a rule - and makes it something concrete - an example!
Sometimes, the rule is also written as part of the acceptance test.
Specifying the rule and the example
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:
One rule that has two acceptance tests
Note the capitalized NOT in the second acceptance test. This draws attention to the fact that there is something different that you might miss if you were reading dozens of acceptance tests. It is just a little added emphasis, but it helps!
Now look at the daily withdrawal limit example and write it in Given-When-Then format:
Daily limit acceptance tests
Notice the ID beside each acceptance test. If you are discussing these tests later (maybe if you find issues when testing the feature once it's built), then it is very helpful to be able to direct team members to the fact that you are talking about Acceptance Test 03 rather than trying to describe it!
Putting it all together, you would end up with something like this:
Two rules (allow withdrawal if sufficient balance & allow if under a specific limit)
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?"
If you give someone a ten-page document describing a function, they will find that understanding "what must be done" requires more concentration than a set of user stories and acceptance tests. If there are lengthy documents to read, assume that your team members will not read them. If the document is long, the team won't remember reading some things even if stated clearly. That's why user stories and acceptance tests are best. They are brief, clear, concise, easy to understand, and easily updated.
Additional Resources Gojko Adzic assists teams with software delivery and business goals. His article provides clear guidance on .
Acceptance tests are a way of confirming that a user story was implemented correctly. Acceptance tests always follow the Given-When-Then format. Think of acceptance tests as scenarios or examples. Include the "rule" and a set of related acceptance tests for additional clarity. Then you can easily see the rule and examples (acceptance tests) that illustrate the rule.
Acceptance tests are super important! In the next chapter, you'll see how to create a definition of "Done".