Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 37 ยท Patterns and Pitfalls

Declarative vs Imperative Scenarios

Learn the difference between imperative, click-by-click Gherkin and declarative scenarios that state behavior, with rewriting recipes, a checklist and a runnable scenario linter.

Two teams write a scenario for the same login feature. The first team's version has eleven lines: open the page, click the user field, type a name, click the password field, type a password, click the button, and so on. The second team's has three: a registered user, valid credentials, and "she sees her dashboard". Both pass today. Six months later, after a redesign, the first team's suite needs a week of repairs, while the second team changes one step definition.

The first style is imperative: it describes how the user operates the interface. The second is declarative: it describes what happens and why it matters. Declarative Gherkin is not a style preference. It is what makes scenarios readable by non-programmers, stable against UI changes, and useful as documentation. This lesson shows how to recognize the difference, how to rewrite, and when imperative detail is actually right.

Same behavior, two styles

Imperative:

GHERKIN
Scenario: Successful login
  Given I open the browser
  And I go to "https://shop.example.test/login"
  When I click on the "Username" field
  And I type "mina" into the "Username" field
  And I click on the "Password" field
  And I type "secret" into the "Password" field
  And I click the "Sign in" button
  Then I should see the text "Welcome, Mina" in the "h1" element

Declarative:

GHERKIN
Scenario: Registered customers can sign in
  Given Mina is a registered customer
  When she signs in with her password
  Then she sees her account home

The declarative scenario tells a product owner what the system promises. It names the actor, the capability and the outcome. The browser, the URL, the fields and the button are implementation, and they move to step definitions and page objects.

Why declarative wins

Concern Imperative Declarative
Readability for business people tiring, full of UI nouns reads like a requirement
Change when the UI changes every scenario changes only glue code changes
Reuse of steps low, since each is a click high, since steps are intentions
Test level stuck at the UI can run at UI, API or service level (levels)
Scenario length long short, one idea
Value as documentation none high (living documentation)

Rewriting recipe

  1. Ask what the user is trying to achieve in business words ("pay", "cancel", "log in") and use that as the step.
  2. Remove locators and UI nouns: fields, buttons, pages, URLs, CSS selectors, "click", "type", "navigate".
  3. Collapse sequences. Five steps that always appear together become one step, with the detail moved into code.
  4. Keep the data that matters and hide the data that does not. If the expected result depends on membership level, say "gold". If the first name does not matter, don't invent one.
  5. State outcomes, not screens: "she sees her account home" or "the order is confirmed", not "the page title equals X".

Rewriting a longer example:

GHERKIN
# Before
Scenario: Order a book
  Given I am on the home page
  When I type "SQL" in the search box
  And I click search
  And I click the first result
  And I click "Add to cart"
  And I click the cart icon
  And I click "Checkout"
  And I enter my address "1 Main St"
  And I choose "Credit card"
  And I click "Pay"
  Then I see "Thank you for your order"

# After
Scenario: Customer orders a book
  Given a customer with a saved address
  And the catalog has the book "Learning SQL"
  When she buys "Learning SQL" with her credit card
  Then her order is confirmed

Notice what remained: the saved address, because shipping depends on it; the book title, because it identifies the product; the payment method, because it is a choice with consequences.

When imperative detail is appropriate

Declarative is the default, not a religion. Keep UI detail where the UI is the behavior:

  • an accessibility scenario about keyboard navigation ("pressing Tab moves focus to the search box");
  • validation messages shown next to a field, if the message and its position matter to the business;
  • a scenario specifically about a widget, such as a date picker.

Even then, describe the user's action and the visible effect, not selectors. Tests of pure layout are usually better handled by visual or component tests than by Gherkin.

A scenario linter

You can catch imperative drift automatically. This stand-in is a toy linter: it flags steps that mention UI words, locator characters or very long scenarios. Real teams do this with custom scripts or the gherkin-lint tool in CI.

Java Flagging imperative steps (Java stand-in)

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.

Lint rules are only hints. A step like "Then the page shows a validation error" would be flagged for the word "page" even though it may be fine. Treat reports as prompts for a conversation.

The "so what?" test

For each step, ask: would the product owner care if this step changed? If the answer is no, because it only exists to get the UI into the right state, the step is probably an implementation detail. Also ask whether a new team member could understand the scenario without ever having seen the application. If yes, you are declarative.

A second check: could the scenario be run through a different interface (API, mobile app, command line) without editing the Gherkin? If so, it states behavior, not mechanics.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which step is the most declarative?

    It states the user's intention. The others describe interface mechanics.
  2. 2. What is the main maintenance benefit of declarative scenarios?

    Because the Gherkin avoids UI details, a redesign touches glue code in one place.
  3. 3. Which detail should stay visible in a shipping scenario?

    Data that determines the expected result must be visible. Incidental details should be hidden.
  4. 4. When is imperative UI detail acceptable?

    If the behavior is about the interface (accessibility, widgets), the scenario may describe user actions, though still not selectors.

Summary

  • Imperative scenarios describe clicks; declarative ones describe behavior and outcomes.
  • Declarative Gherkin is shorter, reusable, readable by the business and robust against UI changes.
  • Rewrite by finding the intention, dropping UI nouns, collapsing sequences and keeping outcome-relevant data.
  • Keep UI detail only where the interface is the behavior, and lint for drift.

Next: Common anti-patterns