Turn a user story and acceptance criteria into a valid .feature file.
The generator output is meant to be pasted into a ticket, pull request, or design review. It should name the owner, decision, evidence, and follow-up work before implementation starts.
Feature: Refund retry protection Scenario: duplicate refund request Given a refund is pending provider confirmation When support submits the same refund again Then the existing refund_id is returned And no second provider call is made
Treat the generated Gherkin feature file as a starting artifact. Replace example values, attach evidence, assign reviewers, and remove sections your team will not maintain.
Gherkin is a plain-language syntax for describing software behavior. Feature states what you're testing, Scenario describes a concrete case, and Given / When / Then structures the precondition, action, and expected result. Cucumber, Behat, SpecFlow and similar frameworks parse .feature files directly.
Related: Acceptance Criteria Examples, Given/When/Then Template.
A good scenario says what state exists, what the actor does, and what result must be true. Avoid brittle steps such as "click the blue button in the upper right" unless the UI itself is the behavior under test.
Every scenario should be understandable on its own. If one scenario needs another scenario to run first, move that shared state into Background or split the feature file.
"Invalid login fails" is vague. "Wrong password returns a visible error and does not create a session" is testable. Use concrete data when it clarifies the expected behavior.
Each generated scenario should trace to a requirement in your spec. If a scenario does not protect a real user, API, or business rule, it may be noise.
Scenario: Reset passwordGiven I am on the pageWhen I submit the formThen it works
This scenario does not say which user state exists, what input is submitted, or what result proves the reset flow worked.
Scenario: User requests a reset linkGiven a verified user exists for [email protected]When she requests a password resetThen a single-use reset email is queued
This version describes state, action, and observable output. It is specific enough for QA, automation, and implementation review.
Algorithm complexity, cache strategy, database index selection, and internal service topology are often clearer as unit tests, performance tests, migration checks, or design notes.
If the team has not agreed on user behavior and business outcome, write a normal spec or decision note first. Gherkin too early can make unresolved questions look test-ready.
If the scenario mostly says where to click, scroll, or type, maintenance cost will be high. Move the step up to user intent and observable result unless UI choreography is the feature.
Take the generated scenarios to product, engineering, and QA first. Confirm the actors, states, and outcomes use the same business language before connecting them to a test runner.
Not every generated scenario belongs in end-to-end automation. Prioritize the core workflow, permission boundaries, expensive failures, and cases that have caused regressions before.
Before wiring scenarios to automation, ask QA whether each step can be verified without private implementation knowledge. If a step requires reading logs or database internals, rewrite the expected result as observable behavior.
Generated Gherkin is easier to maintain when the required user state, seed data, permissions, and feature flags are documented near the feature file instead of hidden in a shared test setup.
When product behavior changes, update or remove scenarios in the same pull request. Old feature files that describe retired behavior create false confidence and make future refactors slower.
Each scenario should protect a real user outcome, permission boundary, API contract, or regression risk. If it only describes clicking through the interface, it may be a brittle script rather than a useful specification.
A reviewer should be able to point to the UI state, response body, emitted event, database-visible state, or audit record that proves the Then step passed.
Read the exported scenarios as a shared behavior document before turning them into automated tests. If QA cannot identify the fixture, action, and expected assertion from a scenario, improve the wording before implementation depends on it.
Use the same domain terms in the feature file, spec, UI copy, and support documentation. Gherkin loses value when each team invents a slightly different name for the same state or role.
Not always. Use Gherkin for behavior that benefits from executable examples or shared product language. Some technical constraints are clearer as unit tests, API contract tests, or migration checks.
Enough to cover the meaningful behavior: happy path, important failure path, permission boundary, and one or two edge cases. If the file becomes hard to scan, split it by workflow.
The form pushes scenarios toward clear state, action, and observable result. It is designed to avoid vague acceptance criteria that read well in a ticket but cannot become a useful test.
Generated scenarios are judged by whether product, QA, and engineering can read the same feature file and agree on fixture setup, user action, expected result, and business wording.
Author and editor: Daniel Marsh. Review process: Editorial Policy. Corrections and tool issues: Contact. Last reviewed: April 28, 2026.