---
title: 'Writing Good Gherkin: Declarative Scenarios | TestingBot'
description: 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…
source_url:
  html: https://testingbot.com/resources/courses/cucumber-bdd/writing-good-gherkin
  md: https://testingbot.com/resources/courses/cucumber-bdd/writing-good-gherkin.md
---

Course

[BDD with Cucumber: Gherkin to CI](https://testingbot.com/resources/courses/cucumber-bdd)

Chapter 3 of 12

1. [1 Cucumber BDD Tutorial: From Gherkin to CI](https://testingbot.com/resources/courses/cucumber-bdd)
2. [2 BDD Testing Starts Before the Code: Three Amigos](https://testingbot.com/resources/courses/cucumber-bdd/bdd-collaboration)
3. [3 Writing Good Gherkin: Declarative Scenarios](https://testingbot.com/resources/courses/cucumber-bdd/writing-good-gherkin)
4. [4 Cucumber with Java and Selenium: First Scenario](https://testingbot.com/resources/courses/cucumber-bdd/cucumber-java-selenium)
5. [5 Step Definitions, Cucumber Expressions, Parameter Types](https://testingbot.com/resources/courses/cucumber-bdd/step-definitions)
6. [6 Hooks and Sharing State with PicoContainer](https://testingbot.com/resources/courses/cucumber-bdd/hooks-and-shared-state)
7. [7 Scenario Outlines, Tags and Background](https://testingbot.com/resources/courses/cucumber-bdd/outlines-tags-background)
8. [8 Cucumber-JS with Playwright](https://testingbot.com/resources/courses/cucumber-bdd/cucumber-js-playwright)
9. [9 Parallel Runs, Reports and CI on TestingBot](https://testingbot.com/resources/courses/cucumber-bdd/parallel-reports-ci)
10. [10 Other BDD Frameworks: Behave and Reqnroll](https://testingbot.com/resources/courses/cucumber-bdd/behave-and-reqnroll)
11. [11 BDD Anti-Patterns and How to Fix Them](https://testingbot.com/resources/courses/cucumber-bdd/bdd-anti-patterns)
12. [12 Knowledge check](https://testingbot.com/resources/courses/cucumber-bdd/knowledge-check)

[Exit course](https://testingbot.com/resources/courses)

 Chapter 3 of 12 Intermediate 6 min read 2 quick checks Updated Nov 2026 

# Writing Good Gherkin: Declarative Scenarios
On this page
1. [The keywords](https://testingbot.com#the-keywords)
2. [Declarative, not imperative](https://testingbot.com#declarative-not-imperative)
3. [One behaviour per scenario](https://testingbot.com#one-behaviour-per-scenario)
4. [Write steps in the third person or the first, but be consistent](https://testingbot.com#write-steps-in-the-third-person-or-the-first-but-be-consistent)
5. [Checklist for a feature file](https://testingbot.com#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[#](https://testingbot.com#the-keywords)

A feature file lives in a `.feature` file and has this shape:

```gherkin
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[#](https://testingbot.com#declarative-not-imperative)

Compare two scenarios for the same behaviour.

**Imperative** (describes the clicks):

```gherkin
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):

```gherkin
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?

 Only the imperative one with `I click the "button[type=submit]" button`; the declarative one changes only in its step definition Both, because both scenarios sign in Neither, because Cucumber finds buttons by their text

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[#](https://testingbot.com#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[#](https://testingbot.com#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`?

 `Then I click "Continue"` `Then the test passes` `Then I wait 3 seconds` `Then Tom's order is shown as paid`

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[#](https://testingbot.com#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.

[Previous · Chapter 2 BDD Testing Starts Before the Code: Three Amigos](https://testingbot.com/resources/courses/cucumber-bdd/bdd-collaboration) [Next · Chapter 4 Cucumber with Java and Selenium: First Scenario](https://testingbot.com/resources/courses/cucumber-bdd/cucumber-java-selenium)

On this page

1. [The keywords](https://testingbot.com#the-keywords)
2. [Declarative, not imperative](https://testingbot.com#declarative-not-imperative)
3. [One behaviour per scenario](https://testingbot.com#one-behaviour-per-scenario)
4. [Write steps in the third person or the first, but be consistent](https://testingbot.com#write-steps-in-the-third-person-or-the-first-but-be-consistent)
5. [Checklist for a feature file](https://testingbot.com#checklist-for-a-feature-file)

Certification

Earn the free, resume-worthy TestingBot Cucumber BDD Certification for this course.

[How it works](https://testingbot.com/resources/courses/cucumber-bdd/certification)
