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

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:

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:

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