stack twitter rss linkedin cross

Wilco van Esch

Skip to main content

Search results

    How to write effective Gherkin scenarios

    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.