Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 37 ยท BDD Concepts and Gherkin

Declarative Scenarios: Say What, Not How

Learn the difference between imperative and declarative Gherkin, why UI details make scenarios brittle, and how to rewrite them in the language of the business.

The most important skill in writing Gherkin is deciding how much detail to put in. Beginners tend to describe every click: "Given I open the browser, When I type maria into the username field, And I click the login button...". These scenarios are accurate and useless. They break whenever the page layout changes and hide the one fact the reader cares about: what the system is supposed to do.

The alternative is the declarative style: describe the behavior in the vocabulary of the business and let the step definitions worry about buttons and fields.

Imperative versus declarative

An imperative scenario spells out the user-interface procedure:

GHERKIN
Scenario: Premium member sees a discount
  Given I open "http://shop.example/login"
  And I type "maria" into the field "username"
  And I type "secret1" into the field "password"
  And I click the button "Log in"
  And I click the link "Books"
  And I click the button "Add to cart" for "Learning Java"
  When I click the link "Cart"
  Then I should see the text "Discount: 10%"

A declarative scenario states the situation and the outcome:

GHERKIN
Scenario: Premium members get a 10 percent discount
  Given Maria is a premium member
  When she adds a 40 dollar book to her cart
  Then her cart total is 36 dollars

The second version has several advantages:

Imperative Declarative
Reads like A test script A business rule
Fails when The page layout changes The behavior changes
Length 8+ steps 3 steps
Reusable steps Few Many
Works for UI, API and unit level No Yes
Shows the rule (10 percent) Hidden in a screenshot Visible in the numbers

Two ways to write one scenario

Imperative Clicks and fields
Declarative Behavior and outcome

Declarative scenarios survive UI redesigns.

1 / 2

The detail does not disappear. It moves into the step definitions (and, for UI tests, into page objects, a later chapter), where it is written once and reused by every scenario.

A rule of thumb

Ask of every step: "Would the business person say this out loud?" "Maria is a premium member" passes. "I type maria into the username field" does not. If a step contains words like click, field, button, URL, select, page or database, check whether it describes behavior or mechanism.

Exceptions exist: if you are specifically testing that the login page works, the user's interaction is the behavior. A good compromise is one or two scenarios on the login flow itself, and every other scenario that needs a logged-in user uses a single step, "Given Maria is signed in".

Measuring the smell

It is possible to measure imperativeness crudely, by counting UI words. The stand-in below scores scenarios by the proportion of steps containing mechanism words and flags any score above a threshold. Real linters use similar heuristics. Paste your own scenarios and see which ones fail.

Java Stand-in: a UI-detail detector

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

One definition, several drivers

A strong reason to prefer declarative steps is that the same sentence can drive different layers of the application. "Maria is a premium member" can be set up through the database in one project, through an API call in another, and through the UI only in a handful of end-to-end scenarios. The scenario never changes.

The stand-in below shows this with an interface. The scenario steps call a Shop abstraction; one implementation uses a fast in-memory service, another pretends to drive a slow UI and records the clicks it would make. The scenario output is identical; only the cost differs.

Java Stand-in: one scenario, two drivers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The scenario text is identical and so are the results. This is the payoff of the declarative style: you can run most scenarios beneath the UI, quickly and reliably, and keep the slow browser scenarios for the few flows where the UI is the thing being tested.

Rewriting imperative scenarios

When you inherit an imperative scenario, follow these steps:

  1. State the goal in one sentence: "A premium member gets 10 percent off."
  2. Identify the facts the outcome depends on (membership, book price) and which details do not matter (the URL, the field ids).
  3. Write Given steps for the facts, When for the single action, Then for the outcome, in business language.
  4. Move mechanics down: fold click sequences into the step definitions or page objects.
  5. Keep the numbers in the scenario so the rule is visible.

A frequent mistake in the opposite direction is making scenarios too vague: "Given a valid customer; When they order; Then it works". A declarative scenario still shows the specific data that matters ("a 40 dollar book", "36 dollars"). Vague scenarios hide the rule just as imperative ones do.

Style checklist

  • Use the domain's verbs: "orders", "cancels", "approves".
  • Express intent, not interaction.
  • Keep each scenario to about three to seven steps.
  • Show the data that explains the outcome; hide the rest.
  • Avoid technical identifiers (ids, CSS selectors, SQL) in sentences.

Chapter 3 begins with how a sentence reaches code: step definition basics.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which scenario step is declarative?

    It states the behavior in business words; the clicks are an implementation detail.
  2. 2. Why do imperative scenarios become brittle?

    They encode UI mechanics, so layout or label changes break them.
  3. 3. Where does the UI detail go in a declarative suite?

    The detail is written once in glue code and reused by many scenarios.
  4. 4. What is the risk of making a scenario too vague?

    Scenarios must still show the facts that explain the outcome, such as the price and the discount.

Summary

  • Imperative scenarios describe UI procedure; declarative scenarios describe business behavior.
  • Declarative steps survive UI redesigns, read as rules and can drive any layer of the system.
  • Ask "would the business person say this?" about every step.
  • Keep the data that explains the outcome in the scenario; move mechanics into glue code.
  • Avoid both extremes: click-by-click scripts and vague "it works" scenarios.

Next: Step Definition Basics