• 10 hours
  • Medium

Free online content available in this course.

course.header.alt.is_video

course.header.alt.is_certifying

Got it!

Last updated on 5/19/20

Writing Acceptance Tests

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

Card, Conversation, Confirmation

We mentioned previously 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 (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 our 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 us to make decisions as a team and then we know exactly 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. We 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, it is best to think of a series of examples of how the system should behave. Let's take the following three examples for 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"

Then we 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

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.

Let's look at the first example we had 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:

Writing example 1 in GIVEN-WHEN-THEN format
Writing example 1 in GIVEN-WHEN-THEN format
Using Examples

Note that I began with "User balance = $23".

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

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

Specifying the rule and the example
Specifying the rule and the example

If we 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. Let's add the second example:

One rule that has two acceptance tests
One rule that has two acceptance tests

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

sadf
Daily Limit acceptance tests

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

Two rules (allow withdrawal if sufficient balance & allow if under 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 'takes a long time to read' ;).

Summary

  • Acceptance Tests are our 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.

  • We can include the "rule" and a set of related acceptance tests for additional clarity. Then we can easily see the rule and a set of examples (acceptance tests) that illustrate the rule.

Additional Resources

Example of certificate of achievement
Example of certificate of achievement