Exit course
Chapter 3 of 12 Intermediate 6 min read 2 quick checks Updated

Writing Good Gherkin: Declarative Scenarios

On this page
  1. The keywords
  2. Declarative, not imperative
  3. One behaviour per scenario
  4. Write steps in the third person or the first, but be consistent
  5. Checklist for a feature file

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
  • Feature names 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 synonym Example) is one concrete example.
  • Given puts the system in a known state: the context.
  • When is the action or event whose outcome you care about. Ideally there is one.
  • Then is the observable outcome.
  • And and But continue the previous kind of step, so Then ... And ... is two outcomes. You can also use * for any step.
  • Lines starting with # are comments. Tags (@smoke) and Background, Scenario Outline and Examples are 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.