Writing Good Gherkin: Declarative Scenarios
On this page
Gherkin has very little syntax, which makes it easy to learn and easy to misuse. This chapter covers the keywords you need, then the two habits that separate maintainable feature files from brittle ones: writing declarative steps, and keeping one behaviour per scenario.
The keywords#
A feature file lives in a .feature file and has this shape:
Feature: Signing in to the secure area
Members sign in with a username and password to reach the secure area.
Wrong credentials are rejected with a message that says which part was wrong.
Rule: Correct credentials open the secure area
Scenario: Tom signs in with his own password
Given Tom has an account
When Tom signs in with his password
Then he is in the secure area
Rule: Wrong credentials are rejected
Scenario: Tom mistypes his password
Given Tom has an account
When someone signs in as "tomsmith" with password "not-his-password"
Then the sign-in is rejected because the password is invalid
-
Featurenames the capability. The free text below it is a description: use it for the "why", it is not executed. -
Rule(optional, since Gherkin 6) groups scenarios under the business rule they illustrate, straight from the blue cards of an example map. -
Scenario(or its synonymExample) is one concrete example. -
Givenputs the system in a known state: the context. -
Whenis the action or event whose outcome you care about. Ideally there is one. -
Thenis the observable outcome. -
AndandButcontinue the previous kind of step, soThen ... And ...is two outcomes. You can also use*for any step. - Lines starting with
#are comments. Tags (@smoke) andBackground,Scenario OutlineandExamplesare covered in chapter 6.
Cucumber does not treat Given, When and Then differently when it runs a step: they exist for the reader. That is exactly why they deserve care. A Then that clicks a button, or a Given that asserts something, compiles and runs fine and confuses everyone who reads it later.
Gherkin is also available in over 70 spoken languages. A # language: de comment at the top of a file switches the keywords to German (Funktionalität, Szenario, Angenommen, Wenn, Dann), which helps when the business does not work in English.
Declarative, not imperative#
Compare two scenarios for the same behaviour.
Imperative (describes the clicks):
Scenario: Successful login
Given I open "https://the-internet.herokuapp.com/login"
When I type "tomsmith" into the "#username" field
And I type "SuperSecretPassword!" into the "#password" field
And I click the "button[type=submit]" button
Then I should see "You logged into a secure area!" in the "#flash" element
And the "h2" element should contain "Secure Area"
Declarative (describes the behaviour):
Scenario: Tom signs in with his own password
Given Tom has an account
When Tom signs in with his password
Then he is in the secure area
The imperative version looks reusable ("I type ... into ..." works for any field) and that is its trap:
- It breaks when the UI changes, not when the behaviour changes. Rename a CSS class or replace the submit button with a link and the scenario fails, although signing in still works.
- It hides the rule. A reader has to reconstruct "what is this about?" from six mechanical steps. The product owner stops reading.
- It ties the scenario to the UI. The declarative scenario could be run against an API or a mobile app by swapping the step definitions. The imperative one can only ever drive this one web page.
The test for a step: would it still be true if the feature were delivered through a different interface? "Tom signs in with his password" would; "I click the submit button" would not. The how belongs in step definitions and page objects, which is where chapter 3 puts it.
A designer replaces the "Login" button with a "Sign in" link. Which scenario needs editing?
The declarative scenario describes behaviour, which did not change; the locator lives in one place in the code. The imperative scenario hard-codes the mechanics, so every scenario that logs in this way has to be edited.
One behaviour per scenario#
A scenario should illustrate one rule, with one When. Long journeys that sign in, update a profile, check out and sign out are tempting because they "cover a lot", but:
- when step 14 fails, steps 15 to 30 are never checked, so one bug hides others;
- the scenario title cannot say what it is about, so the failure report does not either;
- every scenario that needs a signed-in user repeats the same steps through the UI, which is slow.
If you find yourself writing When ... Then ... When ... Then, split it. The context that the second half needs ("Tom is signed in") becomes a Given, and its step definition can set that state up the fastest way available, for example through an API or a session cookie rather than by filling in the form again.
Write steps in the third person or the first, but be consistent#
Both "I sign in" and "Tom signs in" work. Named personas tend to age better: "Tom" can have properties ("Tom has an expired card") that "I" cannot, and scenarios with two users ("Tom invites Ana") read naturally. Whatever you choose, use the same voice across a project so that steps can be reused.
Which step is the best Then?
A Then states an observable outcome in business terms. Clicking is an action (a When), waiting is a mechanic that belongs in code, and "the test passes" says nothing about the behaviour.
Checklist for a feature file#
- The feature description says why the feature exists.
- Each scenario title states the rule or the outcome ("Wrong credentials are rejected"), not the steps.
- Each scenario has one
When. - No CSS selectors, XPath, URLs of internal pages, element IDs, waits or test data that the reader does not need. If a value matters to the rule (an amount, a date, a role), keep it; if it does not, hide it in the step definition.
- Three to six steps per scenario is typical. Fifteen is a script.
- A product owner can read it and say whether it is right.