Write a Gherkin test case as a short example of one behavior: establish the starting context with Given, describe the triggering event with When, and state an observable outcome with Then. Gherkin gives the example structure; it becomes an automated test only when a Cucumber runner matches its steps to working step definitions.
Gherkin and Cucumber: what each does
Gherkin is a language for describing software behavior in structured plain text. Teams commonly save examples in .feature files alongside the software. Cucumber reads those files and connects each step to code called a step definition; a runner executes the resulting checks. A feature file can also serve as shared documentation, but plain text alone does not perform a test. See the Cucumber introduction and Gherkin reference (both displayed an update date of September 29, 2026).
As an Amazon Associate I earn from qualifying purchases.
Writing useful examples is a collaborative activity: product and business stakeholders help clarify expected behavior, while the team agrees on language and connects it to automation. Cucumber describes this as part of its BDD approach, not merely a formatting convention.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Start with Given, When, Then
A basic scenario has a known starting state, a meaningful event, and an expected result. For example:
Feature: Account withdrawals
Scenario: Withdraw within the available balance
Given an account has a balance of $100
When the customer withdraws $25
Then the account balance is $75This is an illustrative example, not a claim about a tested application. Feature names the subject and groups related scenarios; a short free-form description may follow it. A Gherkin file contains one Feature.
Given: establish context
Use Given for a well-defined state that exists before the behavior under test begins: for example, an account with a known balance or a user with an active subscription. Avoid using it to narrate interaction steps. Cucumber’s reference explains that Given steps put the system in a known state before the user or external system starts interacting in the When steps.
When: name the trigger
Use When for the event or action that causes the behavior: a customer requests a withdrawal, a payment provider sends a notification, or a scheduled job runs. Prefer one meaningful trigger over a list of unrelated actions.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteThen: assert an observable result
Use Then for the expected outcome, such as a displayed confirmation, a generated report, or the resulting account balance. The matching step definition should compare actual and expected outcomes with an assertion. Prefer results visible at a meaningful system boundary to hidden implementation details that could change without altering user-facing behavior.
Make scenarios readable and maintainable
Describe behavior, not a click script
Declarative wording says what the application does in domain language. For example, “When the customer logs in with valid credentials” expresses the behavior without binding the example to a particular screen design. An imperative version might list opening a page, entering text in specific fields, and clicking a button. That detail can be appropriate when the interface mechanics themselves are the subject of the test, but otherwise it couples the scenario to implementation and can make UI changes require needless edits. Cucumber’s guidance on writing better Gherkin recommends describing behavior rather than implementation details.
Keep one scenario focused
Give each scenario one behavior and a result a reader can identify. Split a step that combines distinct actions or facts when separating them would make the example clearer. Cucumber offers three to five steps as a useful readability guide, not a syntax limit. Keep the same wording for the same domain meaning, and review new language with the people who understand the product. Its collaboration guidance discusses shared scenario writing and active product or business review.
Declarative versus imperative wording
| Style | What it emphasizes | Trade-off |
|---|---|---|
| Declarative | Business behavior and outcome | Usually remains readable when screens or implementation change; requires the team to agree on meaningful domain language. |
| Imperative | Detailed mechanics, such as fields and buttons | Useful when those mechanics are what is being tested, but UI changes can force edits to otherwise unchanged behavior examples. |
Use the rest of Gherkin when it adds clarity
And and But
Use And or But to continue the preceding kind of step without repeating its keyword. These words improve reading flow; Cucumber does not use the keyword to distinguish otherwise identical step text during step-definition matching. Identical step wording under different keywords can still collide.
Rule and Background
Rule groups scenarios that illustrate one business rule; it has been part of Gherkin since version 6. Background describes context shared by scenarios in a feature. Use shared context only when it helps a reader understand the scenarios; important setup should not disappear into a long block that readers must mentally prepend to every example.
Scenario Outline and Examples
A Scenario Outline is a template, not a single direct run. It requires one or more Examples sections, and each data row after the header produces a run. Angle-bracket placeholders refer to column headers:
Rank #4
- Used Book in Good Condition
Feature: Account withdrawals
Scenario Outline: Withdraw an amount from an account
Given an account has a balance of $<balance>
When the customer withdraws $<amount>
Then the account balance is $<remaining>
Examples:
| balance | amount | remaining |
| 100 | 25 | 75 |
| 80 | 30 | 50 |Use an outline when examples exercise the same behavior and differ mainly in data. Separate scenarios may be easier to review when cases express meaningfully different behaviors; there is no universal threshold, so choose the form that makes the behavior and variation clearest.
Data tables and doc strings
A data table passes structured input to a step. A doc string passes a larger text value, such as a message body or document. Doc strings can use triple double-quotes or triple backticks; editor support for backticks may vary. These are step arguments, and the step definition must be written to accept and interpret them.
Feature-file conventions and execution
- Use
Featureas the first primary keyword in the file, and keep one feature per.featurefile. - Two-space indentation is the recommended convention in the Gherkin reference.
- Without a language header, the default spoken language is English (
en), unless the Cucumber implementation configuration sets another default. To set one in the file, put a header such as# language: fron the first line. - Steps run in written order. The runner matches step text to step definitions; the keyword itself does not make two identical step phrases distinct.
Syntax and editor or runner support can depend on the Cucumber implementation and version in use. Check the reference for the version your project uses when relying on less common syntax.
A practical review checklist
- Does the scenario describe one behavior rather than several unrelated cases?
- Does each Given establish a known starting state?
- Does the When identify the meaningful trigger?
- Does the Then state an outcome a person or system boundary can observe?
- Would the wording remain accurate if the UI or implementation changed?
- Can the team understand each phrase consistently, and does each step have a matching, maintainable definition?
- Would an outline make repeated data cases easier to review, or would separate scenarios clarify genuinely different behaviors?
Or skip the browser setup
Gherkin describes behavior; it does not itself capture a page screenshot. If you need a screenshot as part of a test or review workflow, ScreenshotNeo is a website screenshot API and MCP server. Its one-request API can return a screenshot or PDF. For example:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. Before capture, it can accept consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents and MCP clients. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for 1,000 free screenshots a month—no card required.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
