• 15 hours
  • Easy

Free online content available in this course.

course.header.alt.is_video

course.header.alt.is_certifying

Got it!

Last updated on 10/15/19

Write Acceptance Tests

Log in or subscribe for free to enjoy all this course has to offer!

Card, Conversation, Confirmation

We mentioned in the last chapter that:

  1. User stories are deliberately simplified versions of requirements and short enough to be written on a post-it note or an index card.

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

  3. The additional details that come out of these conversations enable 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) in order for this feature to be acceptable. For this reason, these additional scenarios are often called acceptance tests.

A user story written on an index card
A user story written on an index card

Writing Acceptance Tests

When writing acceptance tests, think of a series of examples as to how the system should behave. Take the following three examples of how an ATM machine 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."

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 as well as easy to test.

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
Writing example 1 in GIVEN-WHEN-THEN format

Using 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.

Specifying the rule and the example
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
One rule that has two acceptance tests

Now look at the daily withdrawal limit example and write it in GIVEN-WHEN-THEN format:

Daily Limit acceptance tests
Daily limit acceptance tests

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)
Two rules (allow withdrawal if sufficient balance & allow if under a specific limit)

Now imagine for a moment that you are a new developer on the team. You missed the planning session which happened 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 both 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?"

Summary

  • Acceptance tests are a way of being able to confirm that a user story was implemented correctly.

  • Acceptance tests always follow the GIVEN-WHEN-THEN format.

  • Acceptance tests can be thought of 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.
     

Additional Resources

Gojko Adzic on using examples to define tests.
 

Example of certificate of achievement
Example of certificate of achievement