A Gherkin scenario should let a product owner, developer, and tester agree on one observable behavior. The familiar Given, When, Then structure helps, but keywords alone cannot rescue an unclear example. A useful scenario names the starting situation, the event, and the result precisely enough that the team can recognize a pass or a failure.
Here are three examples to follow and six to avoid. The examples use familiar login, shopping, search, registration, checkout, and logout flows. Treat the product names and rules as sample test data: in a real feature, the team must agree on them before automating the steps.
What makes a scenario useful?
Given establishes relevant context, When describes the action or event, and Then states an outcome a user or another system can observe. The scenario should explain a business rule rather than narrate every click. Step definitions can handle the interface and setup details. A short scenario is easier to review, but brevity is not a reason to omit the data that makes its result testable.
Three Gherkin scenarios to follow
1. A member can sign in with valid credentials
Feature: Member access
Scenario: An active member signs in
Given Ava has an active member account
When Ava signs in with valid credentials
Then Ava can view her private ordersWhy it works: The starting account state matters, the action is one meaningful event, and the outcome is visible to the member. The scenario does not depend on a particular button, page layout, or authentication implementation. A separate scenario should cover an invalid password or a suspended account because each has a different expected result.
2. Adding an available product changes the cart
Feature: Shopping cart
Scenario: Add one available product to an empty cart
Given the shopper's cart is empty
And a Blue Mug is available for $12
When the shopper adds one Blue Mug to the cart
Then the cart shows one Blue Mug at $12Why it works: The example identifies a product, quantity, price, and observable cart result. If the business also needs to define tax, discounts, or out-of-stock handling, write separate examples for those rules instead of making this scenario do everything.
3. Search returns the agreed match
Feature: Product search
Scenario: Search by a product's full name
Given the catalog contains a Blue Mug and a Green Bowl
When the shopper searches for "Blue Mug"
Then the results include the Blue Mug
But the results do not include the Green BowlWhy it works: The scenario gives the test a known catalog, a specific search term, and both a positive and a negative outcome. This example assumes that the product’s full name is searchable and that an unrelated product should not match. Confirm those search rules with the product owner before using it as an acceptance test.
Six Gherkin scenarios to avoid
These are deliberately weak examples. Each shows a different failure mode and a practical repair. Some are valid Gherkin syntax; the problem is the behavior they fail to specify.
1. A tautology that cannot explain success
Feature: Member access
Scenario: Login
Given I am on the site
When I log in
Then I am logged inWhy to avoid it: The account state, credential condition, and visible proof of access are missing. Replace the generic actor with a meaningful member state and assert a private capability, as in the first good example. A step definition should not hide an undefined business rule behind the words “logged in.”
2. A click script disguised as a business rule
Feature: Shopping cart
Scenario: Add a product
Given I open the home page
And I click the menu icon
And I click the second product card
When I click the add button
Then the cart icon turns blueWhy to avoid it: The scenario is coupled to navigation and styling, yet never states which product or quantity is in the cart. Those interface details may belong in a UI test. For an acceptance scenario, name the product, perform the cart action, and assert the cart contents.
3. Search results with no known expectation
Feature: Product search
Scenario: Search
Given there are products
When I search
Then I get resultsWhy to avoid it: Almost any result could pass. Specify the catalog data and query, then say which products should or should not appear. If ranking or partial matching matters, state that as a separate agreed rule.
4. Registration with an undefined outcome
Feature: Registration
Scenario: Registration
Given I want an account
When I register
Then I am registeredWhy to avoid it: The example skips the condition that determines success and offers no observable result. A better case might start with an unused email address, submit a valid registration, and expect an account confirmation message. If email verification is required, a second scenario should state when the account becomes active. Agree on that rule rather than assuming registration is complete immediately.
5. Checkout that hides the decision point
Feature: Checkout
Scenario: Place an order
Given I have items in my cart
When I place an order
Then I have placed an orderWhy to avoid it: The scenario does not say whether payment was accepted, what order was placed, or what confirmation the shopper receives. Choose one rule: for example, given a cart with one available Blue Mug and an accepted payment, when the shopper confirms checkout, then an order confirmation lists one Blue Mug. Rejected payment belongs in a separate scenario with a different expected outcome.
6. Logout checked only by a vague status
Feature: Member access
Scenario: Logout
Given I am logged in
When I log out
Then I am logged outWhy to avoid it: The final step simply repeats the action. Specify the protected behavior: after Ava signs out, she can no longer view her private orders without signing in again. That is an outcome the user can observe and the test can check. Keep session storage and token details in lower-level tests unless they are the business rule under discussion.
Review a feature before automating it
Read each scenario aloud with the people who own the rule. Ask whether the Given steps contain only necessary context, whether the When is the event under discussion, and whether the Then would fail for the wrong behavior. If an example needs many unrelated events, split it. If several examples differ only by input values, a Scenario Outline and its Examples table can make that variation clearer. Use a short Background only for context that truly applies to every scenario in the feature.
Gherkin is most valuable as a shared specification. The conversation establishes the rule; the scenario records a concrete example; step definitions may then connect it to automation. Good syntax is the beginning, but a precise observable result is what makes an example useful.
If you want to learn more about the subject, here are two courses I have authored on Pluralsight.
Published by Pinal Dave on SQLAuthority. More of my work at pinaldave.com.
