Guide
Write Gherkin steps your team can reuse
By Miftode Vasilica, maker of Gherkin Studio ·
A step is reusable when two people who never spoke would write it the same way. That takes a handful of habits: one wording per action, values kept out of the wording, and no detail about buttons and screens. Each reused step is a piece of test code nobody has to write again. This page lists the habits, and shows how step suggestions in Gherkin Studio keep a team on the same wording.
Seven ways to sign in
A team looks through its scenarios after a year and finds these:
Given I am logged in
Given I'm logged in
Given the user is logged in
Given a logged-in user
Given I am signed in
Given I have signed in
Given that I am authenticated
Seven sentences, one meaning. Behind them: seven step definitions that do the same thing, or one with a pattern nobody dares to touch.
Nobody did anything wrong. Each author wrote a clear sentence. They just could not see what the others had written.
Six habits
1. One wording per action. Pick "signed in" or "logged in", once, as a team. Which one does not matter. That there is only one does.
2. One voice. "I" or "the user", not both. Mixed voices double the number of steps without adding a single check.
3. Values out of the wording. Write the value in quotes or as a number:
Given I am signed in as "Ana"
Given I requested a reset link 61 minutes ago
One step definition with a parameter then serves every name and every number. Given Ana is signed in needs a new one for Dan.
4. The keyword is not part of the step. Cucumber ignores the keyword when it looks for a step definition. Given I am signed in and When I am signed in are the same step. So do not write two wordings because one "sounds like a Given".
5. No buttons. When I click the blue Submit button breaks the day the button turns green. When I submit the form survives a redesign, and can be reused on a page that has no button at all.
6. State, action, result. Given describes how things are. When is the one thing the user does. Then is something you can see afterwards. A step that follows this is easy to guess, and a step people can guess is a step they reuse.
How Gherkin Studio keeps wording together
The seven sign-ins happened because nobody could see the others. The editor fixes that part.
Type a step keyword and the project's steps appear. After Given, When, Then, And, But or *, with the cursor at the end of the line, you get up to eight steps already used in this Jira project. Keep typing and the list narrows.
The order is predictable. First the steps that start with what you typed. Then the ones where a word starts with it. Then the ones that contain it anywhere. Among equals, the most used comes first.
Each suggestion shows a count. ×12 means the step is written twelve times in the project. When two wordings compete, the count tells you which one the team actually uses.
Tab takes the first one. Or move with the arrow keys and press Enter, or click. Escape closes the list.
Some details that matter in practice:
- Capitals and extra spaces are ignored when matching.
i am signedfindsI am signed in. - The keyword is left out. A step first written under
Givenis offered underWhenandAndtoo, for the reason in habit 4. - Background and Scenario Outline steps are included. Outline steps are offered with their
<placeholders>. - The list belongs to the Jira project. Another project has its own.
- It updates on every save, and also when scenarios arrive through import or Git sync.
- Scenarios in other languages work the same way. With
# language: frat the top, suggestions open afterSoit,QuandandAlors.
And the limits, so nothing surprises you:
- Steps longer than 300 characters are not suggested.
- The list holds up to 2,000 steps per project. When it is full, the least used are dropped first.
- Steps from a story whose text has a syntax error are not counted until the error is fixed.
- The suggestions come from what is written in Jira, not from your test code. The editor does not know which steps have a step definition behind them.
Finding the duplicates you already have
You can use the suggestions as a search.
- Open any story and start a new line with
Given. - Type one word from the middle of the step, for example
signed. - Read the list. The wordings that contain the word are there, up to eight of them, each with its count.
If I am signed in ×41 sits above I have signed in ×3, you know which one to keep and how many places to fix. Do one word a week. signed, logged, open, see.
Short answers
Does it matter whether I write And or Given?
Not to Cucumber. And takes the meaning of the keyword above it, and the keyword is not part of the match anyway.
Can I use * instead of a keyword?
Yes. Gherkin accepts * in place of any step keyword, which reads well for a list of things.
Should a step be reused across projects?
If the same people automate both, yes. The suggestions will not help there: they are per Jira project.
Is a long step a bad step?
Usually it is two steps. If you need "and" inside the sentence, split it.
Where Gherkin Studio fits
Gherkin Studio is a BDD app for Jira Cloud, built on Atlassian Forge. It is on the Atlassian Marketplace, with a 30-day free trial. The editor on this site's home page is a simplified copy of the one in Jira. See how to write scenarios in a Jira story and Scenario Outline and Examples tables.