The Community Blog for Business Analysts

Alexey Kiselev
Alexey Kiselev

Acceptance Criteria. Bridge from your User Stories to Code and Test Cases

We are writing User Stories to fix the scope and describe - what our application should do when implemented.User Stories are great, because the are:

  • Short,
  • Defining Roles,
  • A great connection of the requirement itself and a business need.

User Story declared as a high level definition of the requirement, but it could be used to specify a details as well, let’s have a look at the example:


US1. As a User, I want to book a parking space, so that will allow me to park my vehicle.


or


US2. As a User, I want to see closest to my current location parking structure, so that will allow me to find nearest parking without  switching to the map view.

User Stories became one of the most popular artifact/tool to describe requirements and I would like to go deep into one of the key problems - User Stories details.



Problem statement

Key problem of the describing the implementation tasks via User Stories is their flexibility: single User Story could be implemented in too many different ways and there is no exact guidelines in terms of details of implementation for a single user Story.


As you can see, second User Story (US2) is a detailed requirement of the US1. Is it detailed enough to be able to implement it? If you got a skilled developer team, or this is a product with a common practices and UI guidelines, than my answer is “Yes”. Otherwise you should specify how this UI or JSON in REST API response should looks like, specify positive cases, negative, etc.


Solutions

Old style

I was a big fan of Use Cases and it could be possible to provide a detailed dialog between User and System to specify this US in details.

I will skip all these preconditions and the rest parts, also please don’t pay attention on my personal preference to keep 1-2 steps alternative flows in a main flow.

Here is a set of Use Cases, which covers my US2 in full:


Step

User

System

UC2.1

Click on the “Distance” column


UC2.2


If the “Distance” column is not sorted:

Sort the column rows 0-9

UC2.2


If “Distance” column is already sorted 0-9:

Sort the column rows 9-0

UC2.3


If the “Distance” column is already sorted 9-0:

Sort the column rows 0-9

And I also prefer to show a mock up just to orient Development Team - where this feature should be applied. As you can see, I’m assuming that it will be a column “Distance” and I could decide - sort it 0-9 or 9-0.


Honestly, because my aim is to find a closest one parking location, there is no sense to apply 9-0 sorting, so, let’s purpose another one set of Use Cases:


Step

User

System

UC2.1

Open a menu “Sort by: <current filter name: “Most popular”, “Distance”, “Price” >


UC2.2


Show options: “Most popular”, “Distance”, “Price

UC2.2

Click on the “Distance” column


UC2.3


Sort the available parking 0-9 by a “Distance” attribute

And this is how it should be implemented (this is a screenshot from the ParkMe web-site):


Nowadays dilemma

There are two main streams how to replace Use Cases with the Acceptance Criteria. Some theory first:

Acceptance Criteria are a set of statements, each with a clear pass/fail result, that specify both functional and non-functional requirements.

So, Acceptance Criteria got almost the same scale comparing to the Test Cases, as a User Story to the Use Case. Please note that Use Cases could be easily converted to the Test Cases, so there are a lot of common things here, but different format.

Anyway, let’s keep our focus on Acceptance Criteria. There are two main ways how to describe them:


Bullet points

This is a simplest way to specify what user should or shouldn’t be able to do:

  • simple and fast,
  • functional and non-functional requirements in one place,
  • non structured as minus.

Our example is a pretty simple one, so, let’s try to find couple acceptance criterias based on the Acceptance Criteria definition.

 

US2. As a User, I want to see closest to my current location parking structure, so that will allow me to find nearest parking without  switching to the map view.


Acceptance Criteria:

AC2.1 System should sort parking structures based on the direction 0-9


AC2.2 User should be able to select sorting option from the list “Most popular”, “Distance”, “Price


AC2.3 System must apply a sorting in a less than 2 second from the user’s click on the “Distance” option


AC2.4 System should not hide sorting options from the list. Example: If current parking structures list sorted based on the Distance, “Distance” option still should be displayed while user selects sorting options (UC2.2)


Still, an attached UI prototype or mockup helps to save some time for your developers and QAs.


Gherkin language

Simple and easy way, which I personally like much more than just a bullet list, because I prefer to keep everything in sequence like a dialog “Do” ->  “Response” or a more complex “Given” -> “When” -> “Then” (aka Gherkin).

 

Gherkin uses a set of special keywords to give structure and meaning to executable specifications. I’ll skip a Background term below because it is not that popular and will skip headers like Scenario and Features because this is not a Gherkin tutorial.


  1. Given: As mentioned above, given specifies the pre-conditions. It is basically a known state.

  2. When: This is used when some action is to be performed. As in above example we have seen when the user tries to login using username and password, it becomes an action.

  3. Then: The expected outcome or result should be placed here. For Instance: verify the login is successful, successful page navigation.

  4. And: And is used to combine two or more same type of action.


At this point our Acceptance Criteria will have a next look:

US2. As a User, I want to see closest to my current location parking structure, so that will allow me to find nearest parking without  switching to the map view.

 

Given user see the list of parking structures for they current location

When user clicks on the “Sort by” text

Then application shows next options: “Most popular”, “Distance”, “Price”

 

Given user sees next options of sorting available to select: “Most popular”, “Distance”, “Price”

When user clicks on the “Distance” option

Then application sorts parking structures based on the direction 0-9

And it takes no longer than 2 seconds to do the sorting

 

As you saw in my Use Cases example - I’m a big fan of tables, so I could easily convert this list into the table with Given, When, Then columns and ability to add AND statement inside of every cell of my table.

 

Key advantages are:

  • Structured information
  • Fast converting of your requirements to Tests in case if you got a Cucumber (Gherkin language based Test Framework):
    • If you will use the same terms and phrases, you’ll make a QA guys life much more easier. Cucumber is able to understand that 2 equal statements like “And it takes no longer than 2 seconds to do the sorting” will have the same implementation of the test code, so it will help QAs to skip duplicate or similar code creation.
  • You should keep non-functional requirements inside of your scenario, and this messes up your structure even more than with bullet list concept. At this point, it looks like that keeping a separate non-functional requirements list is the best solution.

Conclusion

There are next key points I would like to highlight as a conclusion:

  • Major ways to specify Acceptance Criteria: bullet list and Gherkin Language (or rarely used structured process related terms like “Do” -> “Response”).
  • Bullet list is a more flexible and required less time.
  • Bullet list works better than a Gherkin Language for a low skilled BSA teams. Developers will appreciate something strict and standardized.
  • Gherkin Language is more complicated, but could improve quality of your requirements because of strict set of steps.
  • Gherkin Language significantly speed up QA effort and BSA-QA communication if company uses Cucumber/BDD.

Related articles

https://automationpanda.com/2017/01/30/bdd-101-writing-good-gherkin/

https://akiselev87.wordpress.com/2017/07/24/cucumber-bridge-or-another-one-abyss-between-ba-and-qa/

https://rubygarage.org/blog/clear-acceptance-criteria-and-why-its-important

https://www.yodiz.com/blog/user-stories-acceptance-definition-and-criteria-in-agile-methodologies/


Author

Alexey Kiselev, 

Lead BSA

https://www.linkedin.com/in/akiselev87/ 


This entry was published on Oct 16, 2018 / Alexey Kiselev. Posted in Agile Methods. Bookmark the Permalink or E-mail it to a friend.
Like this article:
  43 members liked this article

Related Articles

COMMENTS

Only registered users may post comments.

Modern Analyst Blog Latests

As we start a new year many of us will take the time to reflect on our accomplishments from 2012 and plan our goals for 2013. We can set small or large goals. goals that will be accomplished quickly or could take several years. For 2013, I think Business Analysts should look to go beyond our traditional boundaries and set audacious goals. Merriam-...
Recently, I was asked by the IIBA to present a talk at one of their chapter meetings. I am reprinting here my response to that invitation in the hope that it will begin a conversation with fellow EEPs and BAs about an area of great concern to the profession. Hi xx …. Regarding the IIBA talk, there is another issue that I am considering. It's p...
Continuing the ABC series for Business Analysts, Howard Podeswa created the next installment titled "BA ABCs: “C” is for Class Diagram" as an article rather than a blog post. You can find the article here: BA ABCs: “C” is for Class Diagram Here are the previous two posts: BA ABCs: “A” is for Activity Diagram BA ABCs: “B” is for BPMN

 



Blog Information

» What is the Community Blog and what are the Benefits of Contributing?

» Review our Blog Posting Guidelines.

» I am looking for the original Modern Analyst blog posts.

 




Copyright 2006-2024 by Modern Analyst Media LLC