JavaScript testing #8. Integrating Cypress with Cucumber and Gherkin

JavaScript Testing

This entry is part 8 of 18 in the JavaScript testing tutorial

Cypress has proven to be an appropriate tool for writing E2E tests. In the previous parts of this series, we’ve gone through its basics. That’s a proper moment to take a look at a useful addition: the Gherkin syntax. In this article, we look into its principles and how to make a Cypress Cucumber integration.

When testing our application, it is very beneficial to simulate the behavior of our users. A proper approach is to define scenarios that describe the system from the customer’s point of view. Doing so is incredibly useful. Such scenarios are helpful when working with team members having less technical knowledge, stakeholders, and product owners.

Making a Cypress Cucumber integration

A reliable way of doing the above is to write in the Gherkin syntax. It comes from the Cucumber tool and is designed to be easily readable even for non-technical people. It promotes Behaviour-driven development in its core. Most importantly, it formalizes an understanding of how the flow of the application should look like.

Let’s start by installing a preprocessor that we need to use the Gherkin syntax:

As noted in one of the previous parts of this series, the plugins directory contains files that aim to extend and modify the behavior of Cypress. Therefore, it is a proper place to include  .


The second thing to do is to modify the   file:

The above is caused by the fact that we use Gherkin syntax in files with the   extension.

To avoid making our step definitions global, we also add this configuration to our  :

This above is going to become the default option in upcoming versions of cypress-cucumber-preprocessor

There seem to bee some performance issues on Windows. If that’s a concern for you, check out this issue.

The principles of the Gherkin syntax

Gherkin is a language operating using a set of keywords. With them, we structure our   files. This is an example of such file:

Cypress Cucumber search functionality

Let’s look into various keywords and their meanings.


The Feature keyword provides a short description of a tested feature. It has to be the first keyword used in a  file. We can follow it with an additional description below, but we don’t have to.


A scenario is an example that represents a business rule. That is to say, it serves as a specification of the application. A scenario consists of multiple steps.

Use meaningful names for scenarios and features to increase readability. Moreover, use additional descriptions if one line is not enough


The first type of step is called a Given. Its purpose is to define the context of a scenario and therefore put the system into a specific state.


The When step describes an action. Therefore, it is a fitting place to represent actions taken by the users of our application.


Then keyword represents a step verifying an outcome of the actions. By using it, we can observe changes in the interface and verify if they are correct.

And & But

We often find ourselves in need of writing multiple steps of the same type in a row. Instead of doing so, we can use keywords And & But.


One feature can have multiple scenarios. If every one of them is in the same context and repeats the same Given steps, we can put them in the Background statement.

Using Gherkin with Cypress

Since we are familiar with the Gherkin syntax, we can now start using it with Cypress. Aside from using   files, we need to describe every step using JavaScript.

The recommended way of structuring files is having one directory per a feature file.

The directory needs to have the same name as the feature file. You can name the files in the directory in any way you like.

After importing the desired step from  , we can use it to describe actions.

Thanks to doing the above, we associate a piece of JavaScript code with a particular Gherkin command.


We can also pass arguments to our Gherkin expressions. To do that, we use curly brackets with the type of the argument.

Aside from using just a regular string type, we can define custom types and use them in our feature files.

Sharing context

Even though every step definition is a separate function, we can share some context between them. To do so, we can use the “as” command.

Common steps

There are often steps that we would like to reuse across all of our tests. A proper place to define them is in the common directory.



Aside from defining the background, we can also use Cucumber Before and After hooks.


Our hooks run before and after each of the defined scenarios.

We can also use tagged hooks. They run conditionally if we prepend a scenario with the desired tag.


In this article, we’ve gone through both the Gherkin syntax and how to make the Cypress Cucumber integration. It proves to build a bridge between the Quality Assurance team, developers, and less tech-oriented parts of the team. Thanks to approaching testing in such a way, we can keep them well organized and readable.

Series Navigation<< JavaScript testing #7. Diving deeper into commands and selectors in CypressJavaScript testing #9. Replacing Enzyme with React Testing Library >>
Notify of
Inline Feedbacks
View all comments