Learning Objectives
By the end of this lesson you will be able to:
- Define declarative and imperative Gherkin steps precisely
- Rewrite an imperative step as its declarative equivalent
- Apply the "would this still be true after a redesign?" test to any step
Two Ways to Describe the Same Behavior
Every Gherkin step can be written in one of two styles:
- Imperative describes how — the literal mechanics of operating a UI: clicks, keystrokes, field ids, page URLs.
- Declarative describes what and why — the business state and intent, independent of any particular interface.
Take the login scenario from the previous lesson and put both styles side by side:
# Imperative
Given the user opens the browser and navigates to /login
When they type "alice@example.com" into the field with id "email-input"
And they click the blue button labeled "Submit"
Then the text "Welcome, Alice" appears in the top-right corner
# Declarative
Given a guest is on the login page
When they submit valid credentials
Then they are redirected to their dashboard
The declarative version says exactly as much as the business cares about, and not one word more.
More Examples, Different Domains
Checkout
# Imperative
When the user clicks the "Apply Coupon" link and types "SAVE10" into the promo box
# Declarative
When they apply a valid discount code
Search
# Imperative
Given the user types "laptop" into the search bar with id "site-search" and presses Enter
# Declarative
Given a shopper searches for "laptop"
Account settings
# Imperative
When the user toggles the switch next to "Email Notifications" to the off position
# Declarative
When they disable email notifications
Notice the pattern: the declarative version keeps the noun (what the user cares about — a discount code, a search term, a notification setting) and drops the verb-level mechanics of how it's operated on screen.
The Redesign Test
Whenever you're unsure whether a step is declarative enough, ask one question: would this step still be true, word for word, after the UI is completely redesigned?
"They click the blue button labeled Submit" fails instantly — change the button's color or label and the step is now false. "They submit valid credentials" survives any redesign, because it was never about the button in the first place. If a step would need editing after a purely visual change, it's imperative. If it wouldn't, it's declarative.
Pro Tip: When rewriting a step, try deleting every word that names a UI element — a button, a field, a link, a color, a position. What's left is usually your declarative step, almost verbatim.
Key Takeaways
- Imperative steps describe how a user operates a UI; declarative steps describe what is true and why it matters to the business
- The same business rule can always be expressed in either style — declarative is a rewrite, not a different rule
- The redesign test — "would this still be true after a visual redesign?" — reliably separates the two styles
- Declarative steps keep the business noun (a discount code, a search term, a setting) and drop the UI mechanics