Workin’ Gherkin Syntax for your Team

There are a number of fantastic test automation blogs on the Internets® that cover learning proper Gherkin syntax.  We’ll overlap with some of that, but this guide is more specifically for working Gherkin syntax to fit your team and project, and determining when it might make sense to take “poetic license” with the rules.  Let’s level set on a definition before we begin. Gherkin is a business readable language designed to describe use case behavior relating to a system under test.  The purpose of the language is to double as an automated test script and as living process documentation for your testing team.

Sometimes we’ll talk “purist” classic declarative Gherkin:


…and other times we will flagrantly break bad on the Gherkin syntax rules:

Let’s say we have an ecommerce website and one of the test cases in our suite is to verify that returning customers can successfully log back in using the Chrome browser.  We should appropriately name the feature file for this, and adhere to whatever filename conventions were agreed upon by our testing team.  Let’s go with “EcommerceLogin.feature” to keep it simple.

Collaboration is key, so when you get your team together make sure everyone is onboard with how Gherkin will be implemented and where you bend or take “poetic license” with the rules.  A solid squad for our ecommerce login test team would include the business analyst who works with users, the lead developer involved with that portion of the website, the test automation lead, and whomever maintains the login server.  It is of utmost importance that the team adheres to a universal syntax design pattern within the overall system of best practices.  Everyone should be on the same page; you don’t want the business side of your team complaining that the syntax is too “codey” and conversely you don’t want the developer/technical side complaining that everything is too high level and non-specific.

Feature files should be focused on the specific test case, and try to keep scenarios chronological, independent, and limited to one behavior.  I know sometimes it’s hard, but your features read better, are more modular, and easier to maintain this way.  They also look better in your test run reports.  Use backgrounds if it makes sense, for environment configuration, data setup, or anything else that needs to be run prior to your scenarios.  Tags are a must for organizing lengthy feature files with many scenarios, as they allow you to selectively execute scenarios.  Simply add an “@” preceding your “tag word” to a line just before a scenario.  Where I very frequently bend the Gherkin norms is favoring imperative over declarative syntax.  I believe in conciseness and less obfuscation, as long as the syntax is still relatively high level.  Whether or not this works for you of course depends on your testing team and project.


Here is our login example in first-person declarative Gherkin:


“Given” is our initial state, and then onto “When” which is our action, and we close with “Then” which is our verification.  Using this declarative Gherkin, or Gherkin Classic, we would still need to produce the code behind those steps.

 Now let’s test multiple login combinations by using a scenario outline and we shall be controversial and use imperative (and executable via Cycle) Gherkin this time:


We navigate to our login site via Chrome, do a quick check to ensure the correct page has fully loaded, key in one iteration of credentials, click the web element for our login button, and then our ultimate verification is reading the screen to see that the account is successfully logged in and if there was a warning message.  In this case, there is no need to clear the forms before entering the credentials and we’ve determined that the best and least “likely to change” web element for the login button is the XPath.  The team had a lengthy discussion on validation options, and it was determined that an HTML screen read works fine and we don’t need to check log files on the login server.

In the examples section, we have what is essentially a decision table of login credential combinations.  The password fields have been blurred because this is a real test against the login server of a real (demo) ecommerce site login page – my humble apologies to any hackers out there, I can’t just give it to you on a silver platter.

The feature is still very readable, and now we can collaborate more specifically on our scenarios and steps than before with the higher-level syntax.  So, for this test case, I would propose to our team of business analysts, testers, and developers that we use more imperative Gherkin as often as we can.  If there is pushback, then of course you should go with the team consensus and I recommend erroring on the side of the business users as they are less likely to buy-in and collaborate if they can’t understand what is going on in the feature files.  The imperative versus declarative debate isn’t exactly black-and-white, and is more about finding the right place on the spectrum for your team’s needs.

Let’s look at a breakdown of the advantages and disadvantages of breaking the rules with imperative Gherkin:

The case for readable imperative syntax

The case for high-level declarative syntax

Conciseness; no need for both business and execution steps May annoy any non-techy subject matter experts on the team
More specific collaboration Reads less like work instructions
No confusion resulting from abstraction or “hidden” details
Highlights user interface
Developers love it

I didn’t include “brittle UI testing” under disadvantages, because as long as the interface doesn’t drastically change frequently then that concern can be avoided.  Weigh the pros-and-cons and of course, consider my bias - I’m staunchly pro-imperative Gherkin as long as the syntax remains readable - and make a decision that fits best with your team and testing project.

Watch the login feature above being executed in Cycle:

This post was written by:

James Prior
Technical Pre-Sales Consultant

James has been working in software pre-sales and implementation since 2000, and has more recently settled into focusing on technical pre-sales. He takes care of our hands-on demonstrations, and eagerly awaits your request to see our Cycle test automation software in action. Drop him a line at: james.prior[at]tryonsolutions[dot]com.