Why do we use Gherkin?

Easier and less error-prone translation of business needs into functional behaviour, easier and less error-prone understanding of functional behaviour by the development team, and easier and quicker conversion of functional behaviour into (manual and automated) acceptance tests.

When is a scenario good enough?

If you're worried you're spending too much time crafting the perfect user story, stop when each scenario in your user story:

• Covers a single behaviour
• Contains Precondition -> Action -> Result
• Avoids implementation details
• Uses Specification By Example in case of many permutations
• Contains succinct and accurate language

Quick help

Here's one of the most common pitfalls for teams who just started using Gherkin:

Mistake: merely reformatting plain text acceptance criteria into Given/When/Then format.

Solution: writing acceptance criteria from scratch as things a user would see and do.

Merely rewriting acceptance criteria in Gherkin format leads to scenarios which are ambiguous and hide requirements.

Example 1

Scenario 1

GIVEN the item list
WHEN wanting to add a new item
THEN I find a button below the item list to add new items

What works less well?

• This scenario describes the presence of an element, not behaviour.
• The scenario implies that if I do not want to add a item then the button should not be there.
• We want to allow adding of items, let the team decide if it should be a button below the list.
• What kind of items are these? Would every stakeholder interpret correctly what items these are?
• Is the precondition correct? Do I just need to view a list or do I need to be logged in as a certain user?

How could it be improved?

• If the scenario really is about validating the presence of elements, it could be a design document instead
• The scenario could be rewritten to cover the intended behaviour:

Scenario 1

GIVEN I am logged in as a delivery driver
WHEN I view the list of deliveries
AND I choose to add a delivery
THEN I see a list of available parcels

• There is no definite correct scenario. Multiple people could come up with different scenarios that are useful.
• This would be one of several scenarios defining a flow for the imaginary process of adding a delivery.

Example 2

Scenario 1

GIVEN our application
WHEN attempting to click on the In Progress button after the previous screen
THEN it is enabled only when delivery is planned for today

What works less well

• The supposed precondition tells us nothing.
• The actual precondition is at the end. Once I get to the end, I have to go back to re-interpret the scenario.
• Don't refer to other scenarios ("previous screen") within the scenario, set up a precondition if needed.

Example 3

Scenario 1

GIVEN the Open button on the delivery details
WHEN I change the dropdown to In Progress
THEN I get a pop-up window with 3 options (Skip, Cancel, OK)

Scenario 2

GIVEN the displayed pop-up after I have clicked In Progress
WHEN selecting Skip
THEN the pop-up is dismissed
AND I get navigated to a screen where the first button is Arrived

Scenario 3

GIVEN the displayed pop-up after I have clicked In Progress
WHEN selecting Cancel
THEN the pop-up is dismissed
AND I go back to the original screen

Scenario 4

GIVEN the displayed pop-up after I have clicked In Progress
WHEN selecting OK
THEN the pop-up is dismissed
AND the delivery is marked as In Progress

What works less well?

• Difficult to identify gaps or issues in the user flow without a full view of interaction options.
• Inconsistent wording for the same result ("delivery is marked as" and "screen where the first button is").
• In Scenario 2, "the first button" is ambiguous, as the previous one (not the first in the UI) is meant.
• In Scenario 3, "I go back to the original screen" is extraneous and may be misinterpreted as a navigation.
• Similar scenarios with a few variables are more clearly expressed using Scenario Outlines.
• Specific text labels such as "In Progress" are clearer when in quotation marks.

How could it be improved?

Background: I am logged in as a delivery driver

Scenario Outline 1

GIVEN I view the details of a delivery
AND the delivery status is <current status>
WHEN I change the status to <desired status>
AND I select <dialog option>
THEN the new status is <new status>

Examples:

current status	desired status	dialog option	new status
open	in progress	Skip	arrived
open	in progress	Cancel	open
open	in progress	OK	in progress
in progress	arrived	Cancel	in progress
in progress	arrived	OK	arrived

Example 3

Scenario 1

GIVEN an additional notes section
WHEN I want to edit an existing note
OR add new information
THEN I can remove or add new text of up to 250 characters or photos (no other types of attachment)
AND save my changes

What works less well?

• The use of an OR (or of multiple ANDs) is a sign a scenario may be overloaded.
• There are a number of implicit behaviours which could use their own scenario(s).
• There are a number of implicit constraints which should be made explicit.
• There are missing preconditions.

How could it be improved?

Background: I view a work log as a logged in administrator

Scenario 1

WHEN I edit text in the "Additional Notes" section
THEN I can use a rich text WYSIWYG editor

Note: It's best not to force a Given when you don't need more preconditions than the Background provides.

Scenario 2

WHEN I add text to the "Additional Notes" section
AND I save the section
THEN I am given feedback that the changes were saved

Note: We should abstract away the actual text we add. We could also use property-based testing behind the scenes.

Scenario 3

WHEN I type more text than 250 characters
THEN I cannot add any more characters

Scenario 4

WHEN I paste text of more than 250 characters
THEN only the first 250 characters are pasted

Scenario 5 Outline

WHEN I upload <photo or video> to the "Additional Notes" section
THEN I am given feedback that <something happened>

Examples

photo or video	something happened
a PNG with dimensions 1920x1080 and size 1MB	Photo was saved. Preview is shown.
a PNG with dimensions 10000x10000 and size 10MB	Message “Unable to upload file. You can upload valid photo, video, and PDF/XLSX files below 25MB.”
a PDF	PDF was saved. Preview is shown.
an XLS(X)	XLS(X) was saved. Preview is shown.
a DOC(X)	Message “Unable to upload file. You can upload valid photo, video, and PDF/XLSX files below 25MB.”
an MP4 with size 10MB	Video was saved. Preview is shown.
an MP4 with size 50MB	Message “Unable to upload file. You can upload valid photo, video, and PDF/XLSX files below 25MB.”

Note: actual permitted extensions, dimensions, and sizes may be different than this example.
Note: in reality you'd likely want to use examples that account for boundary values and permutations.