TestQuality Blog

Gherkin Language: User Stories and Scenarios

2022-10-11 04:33 Unit Tests
Gherkin language is a simple yet effective syntax for describing the specifics of your User Stories. Although Gherkin's Given-When-Then structure has been available for over a decade, many groups still don't make use of it.

Meaning of the Term "User Story"
User stories describe what a user does or needs to accomplish by describing functionality or a subset of functionality in daily or business language.
User stories, as opposed to formal requirement documents and the associated administrative tasks, provide a fast alternative to handle client needs.

Gherkin Makes Automated User Acceptance Testing Possible

The Gherkin language is an example of a domain-specific language that is used to define Acceptance Criteria and Acceptance Test Cases in a style that is accessible to business stakeholders and straightforward for software developers to implement. Technically speaking, "Gherkin User Stories" are just "User Stories" that employ the Gherkin notation for expressing the Scenarios that will be used to verify that the User Story has been implemented successfully.

It is significantly simpler to do automated User Acceptance Testing (UAT) if you write your tests as Gherkin Scenarios. Gherkin Test Cases created in the Given-When-Then syntax are supported by Cucumber, the most popular open-source software testing framework. Comparing Gherkin Vs Selenium: Cucumber does acceptability testing whereas Selenium performs UI testing.




What are UAT Scenarios and Given-When-Then Acceptance Criteria?

The Gherkin language is a means of conveying the goals and requirements of business stakeholders to the IT department. There is a school of thought among developers that User Acceptance Test Scenarios and Gherkin Acceptance Criteria are the true user requirements that IT need.

Although they seem similar, Acceptance Criteria and Acceptance Tests are two distinct concepts. Both terms mean "acceptance," yet they mean different things in different contexts.

  • Before stakeholders can declare a Story complete, it must satisfy certain functional and non-functional criteria, which are laid out in detail in User Acceptance Criteria.
  • The purpose of the User Acceptance Tests (also known as the User Story Tests) is to ensure that the product is fully functional and satisfies all of the Acceptance Criteria.

We are going to outline some of the points how to write Gherkin Scenarios, Gherkin Acceptance Criteria, and User Acceptance Test Cases in Given-When-Then Gherkin format.

Improved Specifications using the "Given-When-Then" Structure of Gherkin

Given-When-Then (GWT) Scenarios are one of the most common types of User Acceptance Test Cases / Scenarios, while there are many more formats that may be used.

The Gherkin syntax is used in GWT Scenarios. They communicate the business rationale in terms that can be understood by everyone in a company.

One of the greatest ways to guarantee an accurate specification is to use the Given-When-Then Gherkin notation, which has a convenient syntax that lets us state explicitly what we need from business needs and what we anticipate as a result.

The Given-When-Then Format Is a Guide to help you Write Tests


The core of Gherkin are the GWT clauses. They allow one to organize a phrase in such a way that the natural course of an event or action may be explained.

Given the free-form nature of each text block, you are free to express yourself in any way you choose. As a result, there is no set framework to adhere to, which can be both liberating and disorienting. The structure may be as simple or complex as the author desires.

Check out the use of each clause separately:

  • GIVEN (setup data such as hardware or data)
Specify any prerequisite conditions for this test to run successfully in the GIVEN clause. These include not just hardware states, but also data, files, or records that must be in a certain state before the test may proceed. Remember that you may use the connector "AND" if there are several prerequisites involved.

For instance, the system has to be connected to the internet, and the file "test-app.txt" must already exist with the contents "Test Passed!" in it. Although it's up to you, try to avoid putting in conditions like "Given your internet connection is running."

  • WHEN (action or event that triggers the Scenario)
The triggers for this scenario are specified in the WHEN clause. It's the connection that a stakeholder makes with the system itself.

When a user "enters value," "checks an option," "fills a field," etc., on a website, the corresponding actions are listed in the WHEN statement. On the other hand, "responds to call" might be the Stakeholder interaction if an API is involved. The critical point is that this clause specifies the event that will initiate the execution of this scenario.

  • THEN (defines the result or consequence)
The THEN clause specifies the circumstances that will be used to evaluate the test's results. The program functions properly if the requirements in this sentence are satisfied; otherwise, it does not. This result might be a numerical value or anything else that can be checked.

How Background Statements Help to Save Time in UAT Test Cases

You could assume that writing Given-When-Then style UAT Test Cases for User Acceptance Testing is a one-and-done deal. You construct the steps, maybe even writing some example data as a guide, and before you know it, you have a polished set of Test Cases.

However, you soon learn that all of your UAT Scenarios need the same "setup" data, and you'll have to begin reproducing it for each Test Case.

It might become boring to type the same thing over and again. The BACKGROUND statement in the Gherkin syntax is a terrific time-saver and easy solution since it enables you to establish setup criteria that will be utilized for a series of Scenarios. These configuration requirements may be specified only once and then reused across several Scenarios.

In a Feature file, the first step for each SCENARIO is to run all the Gherkin statements between the BACKGROUND statement and the first SCENARIO. That implies two things:

  • For each given group of SCENARIOS, there can be only one BACKGROUND statement.
  • All SCENARIO statements used to test a User Story, Feature, etc., must follow the BACKGROUND statement.

TIP: The use of Background statements might help you avoid having to repeatedly set things up. They drastically reduce the time needed to refresh frequently used prerequisites. They help you get things done faster and with fewer mistakes.

Non-functional requirements (NFRs)

for a given scenario and its expected outcome


The majority of your Scenarios should focus on validating the product's or feature's functionality, but non-functional testing is also crucial. Writing Scenarios that test the product's Non-Functional Requirements (NFR) is essential if you want to keep your customers happy.

Remember that NFRs specify parameters like "how many," "how frequently," "how quickly," "how friendly," etc. Constraints, Performance, User Experience, and Volatility are the four most typical categories that need to be tried out. It may be quite time- and resource-consuming to test non-functional requirements. That's why a lot of businesses employ people whose only responsibility is to test things like a website's security, page load speed,and UI friendliness.

If, however, the fulfillment of a Non-functional Requirement is crucial to the overall success of a product or feature, User Acceptance Criteria or UAT Test Cases should be defined to provide assurance that the NFR has been satisfied.

Gherkin Scenario Outline Enhances the Given-When-Then Format

What should you do if you want to run many iterations of a Given-When-Then Scenario with various inputs? Does each new data set need a new Scenario? That's a lot of unnecessary work, thus it's not LEAN.

When testing, this happens all the time. Most of the time, we need to run many tests to ensure that the application responds in the way we want. Using a range of input data values, we must demonstrate that the application behaves as expected under a number of conditions.

It gets difficult and repetitious to rewrite Scenarios with a wide variety of data values. Scenario Outlines and Examples greatly alleviate this burden.

The GWT syntax is also used in a Scenario Outline. However, it replaces constants with variables to let several tests to be run from a single Scenario line.

The values for each variable are listed in an Example Table that follows the Scenario Outline. Each scenario in the Example Table will be run individually.

Briefly summarizing Gherkin syntax,

  • While you have some BACKGROUND information, it's easier to avoid unnecessary repetition when creating SCENARIOS.
  • A SCENARIO has no variables, but constants.
  • An EXAMPLE TABLE populates a Scenario OUTLINE's variables.
  • One SCENARIO will be run for each entry in the example table.
  • A Scenario Outline may include limitless EXAMPLES.

TestQuality and Gherkin

TestQuality's import capabilities also allow you to import requirements, tests, and issues by uploading Gherkin Feature Files easily with an import data option menu even when using a Gherkin based Test results JSON file.

Gherkin feature files can be uploaded via TestQuality REST interface via curl, a popular command line tool.

Once your file has been added, you can optionally choose a Cycle and Milestone that you would like to link to your Test Run result.

Gherkin Feature Files with your tests can be easily imported with TestQuality


TestQuality is designed around a live integration core that allows TQ to communicate directly with GitHub and integrate with Jira in real-time linking issues and requirements with the key tools in your DevOps workflows.
Join now and Try TestQuality for Free!



TestQuality's integration engine also allows you to connect to pull in automated test results from popular CI/CD, Test Automation, and Unit Testing systems. As we have previously described, TestQuality easily imports Gherkin Feature Files and it has all the test management capabilities you need for creating, maintaining, organizing, and running tests, but TestQuality is different from other test management tools in that it is purpose built for GitHub and Jira workflows and designed to be integrated with virtually all test automation and unit testing tools.

As Conclusion

To summarize, Gherkin Given-When-Then is a simple and easy language that enables non-technical individuals to communicate in a manner that is both obvious and succinct what they anticipate receiving from a product or a feature.

It helps translate user requirements into practical business specifications, which in turn drives increased clarity across the whole process of developing software.

The Gherkin language is an excellent choice for defining user acceptance tests as well as user acceptance criteria (UAT). By employing a common language, you will be able to better communicate (and record) with the stakeholders. This will be of tremendous assistance to you.