The BDD guide
What behaviour-driven development is, how to run a discovery session, every Gherkin keyword, and which frameworks run the result.
# User guide
How to use Gherkinizer
Paste a requirement in plain English, get a parser-checked feature file back, and take it into your project. This covers every control, the input that produces good scenarios, and what each plan allows.
The first generation needs no account — 40 characters of requirement is enough to try it.
# Start here
Generate your first feature file
No account needed for the first one. Describe a behaviour in at least 40 characters, press Generate Gherkin, and download the result.
Describe the behaviour in plain English
Natural Language InputWrite what the system should do, not the clicks that get you there. A short paragraph is enough — the example below is three lines.
Generate
Generate GherkinThe result is parsed with the official Cucumber grammar before it reaches you. A badge above the output says whether it parsed and lists anything the lint layer flagged.
Take the file
ExportDownload the
.featurefile on its own, take the whole project as a.zip, or copy the scenarios as Jira wiki markup for a ticket.
What that looks like
Three lines of requirement:
what you type
Registered customers can apply one promotion code per order at
checkout. A valid code takes its percentage off the order total.
An expired code is refused with a message naming the code.And what comes back — one scenario per behaviour, with concrete values rather than "the correct total":
applying-a-promotion-code-at-checkout.feature
Feature: Applying a promotion code at checkout
Background:
Given the customer is signed in
Scenario: A valid code reduces the order total
Given a cart worth £100.00
When the customer applies the code "SPRING25"
Then the order total should be £75.00
Scenario: An expired code is refused
Given a cart worth £100.00
When the customer applies the code "WINTER10"
Then they should see "WINTER10 has expired"
And the order total should be £100.00# Reference
The full workflow, control by control
Everything the generator does, in the order the buttons appear. Writing a requirement and generating from it work without an account; the document upload and everything from step 5 need one.
Write the requirement
Natural Language InputOne capability per generation. If your paragraph contains the word "and also", it is probably two features and will produce a better file as two generations.
Length limits are per tier and shown in the plan table below. The box stops accepting input at the ceiling rather than truncating silently.
Attach a document, optionally
＋ → Upload a documentA PDF or
.txtup to 10 MB — a requirements doc, a user story export, a spec. It is read for that one generation and is not stored by us. Needs an account.Set the Gherkin options
Gherkin OptionsBehind the gear icon in the corner of the input card. Two switches:
Use 'Background:'pulls setup steps that every scenario shares into one block, andUse 'Scenario Outline:'parameterises a scenario across a table of values.Both are off by default and neither is required. There is guidance on which to reach for below.
Generate the feature file
Generate GherkinOutput appears in the Gherkin Output panel with a validation badge. Counts as one generation.
Add edge cases
Find Edge CasesAnalyses the file you just generated and proposes the failure paths and boundaries it does not cover. Review them, then Accept & Append to merge them into the file or Discard.
Counts as a generation, and on a free account the allowance of 2 is a lifetime total rather than a monthly one.
Generate step definitions
Generate Step DefinitionsPick a framework and a language first — the language list is filtered to what that framework supports. Free accounts can generate Java; the other four languages are part of Pro. Counts as a generation.
Save it to your account
Save FeatureSaved files appear on your Dashboard, where you can reopen or download them. Deleting one frees a slot.
Saving needs a confirmed email address, which only affects accounts created with a password — a Google account is confirmed already. Two files cannot share a
Feature:name, so re-saving the same requirement is refused rather than silently duplicated.Export
ExportThree options, covered in getting the output into your project.
# Getting good output
Writing input that produces scenarios worth keeping
The single biggest lever on output quality, and it takes about twenty extra seconds.
Describe behaviour, not the sequence of clicks that exercises it. A scenario written from the interface breaks the next time the interface moves, and it tells a product owner reading it nothing about what the system is supposed to do.
A recorded session
“Open the login page, type the email, type the password, click Sign in, check the dashboard loads.”
Every noun here is a control. Nothing states what should be true afterwards, so the generated scenario can only restate the clicks.
A statement about the system
“Registered customers sign in with their email and password. After signing in they land on their dashboard, showing only their own orders.”
Names who is acting, what they do, and what should then be true. That is a Given, a When and a Then already.
Three more that reliably improve the result
Say who is acting
"Registered customers", "guest visitors", "an administrator". A requirement with no actor produces scenarios that start "Given a user", which is the least useful noun available.
Give real values
"An order over £50 ships free" produces a better scenario than "large orders ship free", because the boundary is the thing being specified and £50 is where it sits.
State the failure, not just the success
Mention what happens when the code is expired, the file is too big, the field is blank. You can also generate these afterwards with Find Edge Cases, but naming the ones you already know about costs nothing.
The same rule is the reason most Cucumber suites become unmaintainable, and it is worth twenty minutes if you are new to it: declarative versus imperative scenarios, with a before and after.
# Getting good output
Reading the output panel
Two things sit above the generated file that are easy to miss.
The validation badge
Every generation is put through the official Cucumber grammar — the same parser Cucumber itself uses — before it is shown to you. The badge reports the result, and expands to list anything the lint layer flagged: a scenario with no Then, a Scenario Outline whose Examples table is missing a column, steps that would fail at runtime.
Read the claim precisely, because it is deliberately narrow. The badge says the file parsed. It does not say the scenarios describe what you meant. A model can produce perfectly valid Gherkin about the wrong behaviour, and no parser catches that — you do, by reading it.
The step reuse hint
If steps in the new file are re-phrasings of steps already in your saved features, a hint appears saying so and offering the existing wording to copy.
This matters more than it looks. Across the feature files saved in this product, roughly a third of all steps are re-writes of a step that already existed — Given the user is logged in against Given a user is logged in against Given the user logs into the system. Each one needs its own binding and drifts independently, and that is the usual reason a Cucumber suite becomes unmaintainable.
The hint compares against your own saved features, so an account with one saved file will not see it. Why step text is a global namespace explains what it is protecting you from.
# Reference
Getting the output into your project
Three options behind the Export button, for three different next steps.
The .feature file
Just the file, named after the feature rather than "scenario.feature". Drop it into your repository. This is the one export that works without an account.
Project .zip
The feature file, the step definitions if you generated them, and a README naming the install line, the run command, and where each file belongs in a project of that language.
Copy for Jira
The scenarios as Jira wiki markup, ready to paste into a ticket description. Needs a file that parsed, since it is built from the parse rather than from the raw text.
Where the files belong
The .zip is laid out flat, because an archive has to make sense before it is unpacked. Its README tells you where the two directories go in a real project — this is the same table, read from the same module the exporter uses.
| Language | Feature files | Step definitions | Step file named |
|---|---|---|---|
| Java | src/test/resources/features | src/test/java/steps | UserAuthenticationSteps.java |
| JavaScript/TypeScript | features | features/step_definitions | user-authentication.steps.js |
| Python | features | features/steps | user_authentication_steps.py |
| C# | Features | StepDefinitions | UserAuthenticationSteps.cs |
| Ruby | features | features/step_definitions | user_authentication_steps.rb |
Each framework has its own glue mechanism on top of that, and getting it wrong tends to fail quietly. The per-framework guides cover the configuration each runner needs.
# Reference
Background and Scenario Outline: which to switch on
Both are off by default, and both are easy to reach for too early.
Turn on Background when
- every scenario in the file starts from the same state
- that state is context — signed in, catalogue populated — not an action
- you would otherwise repeat the same two or three Given steps everywhere
Not for the action under test. A Background that signs a user in, fills a basket and opens checkout runs before every scenario and hides the setup that actually mattered to any one of them.
Turn on Scenario Outline when
- one behaviour needs illustrating at several boundaries
- the rows differ in values, not in what the system does
- three or four rows would say it — not thirty
Thirty rows of the same path is a data-driven unit test in a costume: slow to run and unreadable as a specification.
Every Gherkin keyword, with the traps marked, is in the anatomy of a feature file.
# Reference
What each plan includes
Read from the same configuration the app enforces, so this table cannot drift from what actually happens.
| No account | Free | Pro | |
|---|---|---|---|
| Feature file generations | 1 per day | 5 per month | 500 per month |
| Requirement length | 40–1,500 characters | Up to 2,000 characters | Up to 25,000 characters |
| Edge cases and failure scenarios | No | 2 in total, not per month | Unlimited |
| Step definitions | No | Java only | All five languages |
| Saved feature files | No | 3 | 30 |
| Document upload | No | Yes | Yes |
| Download the feature file | Yes | Yes | Yes |
The generation allowance resets a month after it last reset, on your account's own date rather than on the first of the month. The free edge-case allowance does not reset at all — it is a lifetime total, deliberately, so it is worth spending on a file you intend to keep. Prices and the full comparison are on the pricing page.
Frameworks and languages
Feature-file generation is free in every language — the language choice only affects step definitions.
Selenium WebDriver5 languagesPlaywright4 languagesCypress1 languageREST Assured1 languageAppium5 languagesSpecFlow1 language
The full matrix lists which languages each framework supports and the command that runs the result.
# When it goes wrong
Troubleshooting
The problems people actually hit, and what to do about each.
The output describes clicks instead of behaviour
Your input did too. Rewrite it as what should be true rather than what to press — the before and after above is the shortest version of this. It is the single change that most improves output.
The scenarios are vague — "the correct total", "a valid response"
Put real values in the requirement. The generator can only be as specific as its input, and "an order over £50 ships free" gives it a boundary to write a scenario around.
One generation produced a sprawling file covering five things
The requirement described five things. Split it and generate once per capability. A feature file is a specification someone reads, so past roughly ten scenarios it has usually stopped being one.
The validation badge is showing warnings
Expand it — each warning names what it found and where. Warnings mean the file parsed but something in it is likely to misbehave, most often a scenario with no Then or an Examples table missing a column. Fix it in the text and re-check.
The language I want is locked in the dropdown
Step definitions in Java are free; the other four languages are part of Pro. Generating the feature file itself is free in every language, so you can still take the file and write the bindings yourself.
Find Edge Cases is disabled
Either you are not signed in, you have already generated edge cases for this file, or a free account has used its 2 lifetime edge-case generations.
I hit the monthly generation limit
The allowance resets a month after it last reset, on your account’s own date. Note that edge cases and step definitions each count as a generation, so the counter moves faster than "one per feature file" suggests.
Save Feature says I need to verify my email
Saving needs a confirmed email address. Use the resend link at the top of the page, then try again. Only accounts created with a password see this — a Google account is confirmed already, and generating never requires it.
Save Feature says I have already saved this feature
Two saved files cannot share a Feature: name, and regenerating from the same requirement usually produces the same one. Rename the Feature: line in the output before saving, or delete the earlier file.
My upload was refused
PDF and .txt only, up to 10 MB, and you need to be signed in. Anything else is refused before it reaches the model.
# Elsewhere
Where to go next
How your data is handled
What is stored, what is logged, what is sent to the model, and what is not. Written for whoever has to sign off on using this at work.
Ask us
If the output is not what you expected and rephrasing has not helped, tell us what you put in and what you got back.
That is the whole tool.
Everything above takes about a minute the first time. Paste a paragraph, read what comes back, and keep it if it is right.