Gherkin Reference (Cucumber)

What Gherkin is

Gherkin is a plain-text language for describing how software should behave through concrete examples. It is used by Cucumber and many other behaviour-driven development tools, and by analysts and testers who write acceptance criteria as scenarios. Files use the .feature extension, and Cucumber's docs note that Gherkin has been translated into more than 70 spoken languages, so scenarios can be written in the language the business uses.

What the reference covers

• Feature: a short description of the capability being specified.
• Rule: a business rule the feature implements, grouping related scenarios.
• Scenario (or Example): one concrete example of behaviour.
• Given, When, Then: the starting context, the event and the expected outcome. And and But continue a list of steps.
• Background: steps repeated at the start of every scenario in a feature.
• Scenario Outline and Examples: one scenario template run with several rows of data.
• Secondary syntax: doc strings with """, data tables with |, tags with @ and comments with #.

Why a business analyst should read it

Acceptance criteria written as Given/When/Then scenarios are clear to business users, developers and testers at the same time. When they follow the real syntax, a test automation team can often turn them into automated tests with little rewriting. Knowing the reference also stops common mistakes, such as putting several actions in one When step or writing Then steps that describe user interface details instead of outcomes.

A small example:

Scenario: Refund under the approval limit
  Given an order paid 3 days ago
  And the refund is below the agent limit
  When the agent approves the refund
  Then the customer is refunded without a manager step

How to practise

1. Take one user story you wrote and write three scenarios: the main case, an error case and a boundary case.
2. Use a Scenario Outline for rules that vary only by data, such as approval limits.
3. Ask a tester or developer to read them and tell you what is ambiguous.

Free or paid?

The reference is free on the Cucumber documentation site. Cucumber's open source tools are free as well.

Common questions

Do I need to code to use Gherkin? No. Writing scenarios needs no code; automating them does, and that is usually the engineers' part.

Is Given/When/Then required for acceptance criteria? No. Many teams use simple checklists. Gherkin is most useful when behaviour depends on rules and data.

Best for: business analysts, product owners and testers writing acceptance criteria that everyone can read and test.