Best practices in preparing gherkin feature file

Test Driven Development (TDD) is a test development process where the software requirements are broken down into smaller units, and create tests for each unit before developing the software. In the TDD approach, developers first create tests for each functional unit and then develop software to ensure that all the tests are handled in the code.

Behavior Driven Development (BDD) is another test development process derived from TDD. In BDD, testers create tests for the user behaviors. The Gherkin file is used for creating scenarios for end-to-end tests.

TDD vs. BDD Comparison

Parameters TDD BDD
Members involved Developer Developer, QA (or) Customer
The language used for creating tests. Leverage to define tests in plain language (English) Using programming language (E.g., Java, Python, etc.) Using Gherkin / Simple English
Who will create and use tests?

Only developers are able to write and use tests.

Only programmers with programming language knowledge can understand it.

Anyone involved in the project can define tests, and developers and testers can put them into practise.

Everybody working on the project can comprehend.

Used in the phase of Unit Testing Requirement understanding/E2E and Regression testing.
Suitable for Project Suitable for projects that do not have end users. If there is no dedicated QA team for testing. Suitable for projects with large customers. If the project with complex functionalities wanted to document all the user requirements in a readable format, Project with a better user experience.
Tools JUnit, TestNG, Pytest, Rspec, csUnit & NUnit etc. Cucumber, Specflow, Behave, JBehave, Behat & Concordion etc.

What is Gherkin?

Gherkin is a simple structured language that helps to create behavior-based tests using simple English, file can be read and understood by anyone in the software development team.

Gherkin is mostly used to define the tests to cover the end-to-end workflow. Writing scenarios in an independent/standalone way without creating dependency on each other is important.

Each scenario in a Gherkin file will be considered a standalone test.

Gherkin files should be saved with a .feature extension to automate the scenarios.

Many assume that writing feature files in the Gherkin language is easy, but it’s not. Though Gherkin uses simple syntax (Given, When, And, Then…), it has to be used wisely to define meaningful steps. It’s moreover like an art.

Preparing Gherkin is not just documentation work. A person involved in preparing Gherkin files has more responsibility as they are converting system requirements into system behaviors from a user perspective.

Take action now! Improve collaboration, automation, and software quality by implementing best practices in Gherkin feature file preparation. Start today!

Click here

Best practices in preparing gherkin feature files.

Avoid lengthy descriptions.

We must keep the Title & Description short; when the description is long, the readers may skip the lengthy description.

Scenario Background.

The scenario Background adds some context to each scenario. It is like a pre-requisite for scenario execution. Though writing Background is not mandatory like scenarios and steps, they can throw more context on the test and reduce the repetition of steps as they can act as pre-condition.

If there is no Background detail to add to any scenario, we may add some additional detail that are required or help to complete executing the scenario.

For Example:

  • Test Data,
  • Experiment files used for this test,
  • Database connection,
  • Other interface connectivity,
  • Etc.…


Prepare scenarios using clear statements as we document the requirements in user behavior format. Project stakeholders can access these documents for various reasons, such as to read and understand the requirement, to automate the tester to develop a script, and for future reference.

Project members have different levels of application understanding. We must consider this and prepare Gherkin files from lay man’s perspective.

Preparing scenarios at a high level (or) using too many statements is not recommended. Prepare only apt scenarios and steps.

The scenario is high level.

Scenario with too many statements.

Scenario with apt statements.

Pass accurate input parameters.

Always mention the accurate values in the input parameters, sometimes, the results may vary, and our scripts will fail. By passing accurate values, we can save much time, such as failure analysis, script rework, re-execution, etc.

Scenario Outline?

Using “Scenario Outline” is always good, especially when testing with N input parameters of similar workflow.

There are many advantages when we use the syntax “Scenario Outline.

  1. We can pass many parameter values using the same parameter key.
  2. The number of statements in the Gherkin file will reduce.
  3. Readability is good.
  4. Easy to maintain when there is an update or rework.

Using “Scenario” syntax:

Using “Scenario Outline” syntax:

Avoid Technical Terms.

Do not use any technical term (or) coding language in the Gherkin file, as it may not be understood by a non-technical person in the project.

Use the present tense

There is no such rule to prepare a Gherkin file only with the present tense, but I would suggest using the present tense wherever it is possible. It will keep the readers engaged with the application.

Statements with past/future tense.

Statements with the present tense.

Maintain the same naming convention.

We should maintain the same naming convention in all the scenarios inside the Gherkin file. Also, try to maintain all the Gherkin files in the project.

Add more negative scenarios.

This is a common rule applicable to any kind of testing. It is always good to have more negative scenarios in your test scripts. It helps us to validate the application, especially in negative situations. Like how effectively the application is designed, developed, and built to handle unexpected user behaviors.

For instance, does the application show a proper error message to users in unexpected workflow, how quickly can an application recover, any data loss, etc.


We must ensure that all the lines are properly aligned inside a Gherkin file.

Always prepare the Gherkin file perfectly, as this will be the first impression to others about the document and its quality and content. It creates interest in the readers and helps them to complete reading quickly.

Avoid Spelling Mistakes

Not a major mistake, but spelling mistakes should be avoided in the Gherkin file. It will create a bad impression on the readers. Keep the content of the file simple without mistakes.

Make sure we enable the spell-check option while working on Gherkin files.
Sometimes spelling mistakes may not be highlighted in red lines, which means we haven’t installed the spell check extension and must install and enable it.

For Ex: “Code Spell Checker” & “Spell Right” extensions.

Process-related best practices can also be considered in the project.

  • Gherkin file review/approval process.
  • Collect all the Gherkin files and place them in a common repository.
  • The Gherkin file should be updated whenever there is a change.
  • Provide access rights to everyone in the project.
  • Read-only access to the Gherkin folder (except leads/manager) 
  • Maintain proper folder structure.
  • Maintain version controlling.
  • Periodic backup and maintenance.
  • We can involve the functional team in preparing Gherkin files if the automation team fully engages with scripting work.

Enhance collaboration, automate better, and deliver high-quality software. Start implementing best practices in Gherkin feature file preparation today!

Click here


In conclusion, following best practices in preparing Gherkin feature files is crucial for effective and efficient software development. By adhering to guidelines such as writing clear and concise scenarios, using descriptive language, organizing scenarios with proper structure, and involving stakeholders in the process, teams can improve collaboration, facilitate test automation, and ensure the delivery of high-quality software. Implementing these best practices empowers teams to create feature files that are easily understood, maintainable, and valuable assets throughout the software development lifecycle.

Author: Jagan
Experienced Associate Project Manager with over 11 years of dedicated focus on software application testing. Specialising in functional testing, Jagan has consistently elevated the quality of testing approaches throughout his career. In his role as a Test Manager, he actively participates in all project phases, from the meticulous creation of comprehensive test plans to conducting Risk assessments and developing effective Mitigation strategies. Jagan's expertise also extends to Test Environment setup, ensuring seamless testing processes and successful project outcomes. With a proven track record of delivering exceptional results, Jagan is a valuable asset in driving projects to success through meticulous testing and management practices.