App & Browser Testing Made Easy

Give your users a seamless experience by testing on 3000+ real devices and browsers. Don't compromise with emulators and simulators

Get Started free
Home Guide Cypress Cucumber Preprocessor: Uses & Configuration

Cypress Cucumber Preprocessor: Uses & Configuration

By Pawan Kumar, Community Contributor -

What is Cypress Cucumber Preprocessor?

Cypress Cucumber Preprocessor is a plugin for the Cypress testing framework that allows you to write end-to-end tests using the Cucumber testing framework‘s Gherkin syntax. 

How Cypress Cucumber Preprocessor work?

  • Gherkin Syntax: In feature files, you write your test scenarios using Gherkin syntax. Gherkin is a language that allows you to describe the behavior of your application in a structured, human-readable format. It uses keywords like Given, When, Then, And, and But to define the steps of your test scenarios.
  • Step Definitions: Each step in your Gherkin scenario needs to be mapped to JavaScript functions known as “step definitions.” These step definitions contain the test logic that interacts with your web application using Cypress commands.
  • Test Execution: When you run your Cypress tests with the Cypress Cucumber Preprocessor, it reads the Gherkin feature files, matches the steps to their respective step definitions, and executes the tests in the browser using Cypress.
  • Reporting: Cypress typically generates detailed reports of test execution, and when combined with Cucumber, it provides even more structured and readable reports, making it easier to understand test results.

This approach allows for collaboration between technical and non-technical team members since feature files are written in plain language, making them accessible to stakeholders who may not be familiar with coding. The technical team can then implement the step definitions to make these feature files executable tests.

Uses of Cypress Cucumber Preprocessor

Cypress Cucumber Preprocessor is a powerful tool for writing and executing end-to-end tests using the Cypress testing framework in conjunction with the Cucumber testing framework’s Gherkin syntax. It offers several benefits and use cases:

  • Behavior-Driven Development (BDD): We can implement BDD practices in our testing workflow. BDD encourages collaboration between non-technical stakeholders (e.g., product owners, and business analysts) and developers by writing tests in plain language (Gherkin) that everyone can understand.
  • Structured Test Scenarios: With Gherkin syntax, we can write test scenarios in a structured and readable format, making it easier to document and communicate the expected behavior of our application.
  • Separation of Concerns: It promotes the separation of test scenarios (written in Gherkin) from the actual test code (JavaScript step definitions). This separation makes it easier to maintain and update tests since application behavior changes can be reflected in the Gherkin files without changing the underlying test logic.
  • Test Reusability: We can reuse step definitions across multiple test scenarios, reducing duplication and making our test suite more maintainable.
  • Parallel Test Execution: Cypress parallel test execution, and when combined with Cypress Cucumber Preprocessor, can run multiple Gherkin scenarios in parallel, speeding up the test execution process.
  • Readable Reports: When we run tests using Cypress Cucumber Preprocessor, it generates structured and readable reports that provide clear insights into test results, making it easier to identify issues and failures.
  • Cypress Cross-Browser Testing: Cypress supports multiple browsers. We can use Cypress Cucumber Preprocessor to write cross-browser tests in a BDD format, ensuring our application works consistently across different browsers.
  • Integration with CI/CD: We can integrate Cypress Cucumber Preprocessor into our CI/CD pipeline, allowing us to automatically run tests whenever code changes are pushed to our repository, ensuring that new changes don’t introduce regressions.

How to install and configure Cypress Cucumber Preprocessor?

Steps to install Cypress Cucumber Preprocessor:

1. Prerequisites

  • Ensure you have Node.js and npm (Node Package Manager) installed on your system. You can download and install them from the official website:
  • npm is used for package management, and Cypress plugins are typically distributed as npm packages, making Node.js and npm essential for setup and usage.

2. Create a Cypress Project: You can create one using the following commands:

mkdir my-cypress-project

cd my-cypress-project

npm init -y

3. Install Cypress: Install latest version of Cypress as a dev dependency in your project:

npm install cypress --save-dev

4. Install Cypress Cucumber Preprocessor: Install Cypress Cucumber Preprocessor latest version (4.3.1) as a dev dependency:

npm install cypress-cucumber-preprocessor --save-dev

5. Create a5.  cypress/plugins/index.js File: Create a plugins directory if it doesn’t already exist, and inside that directory, create an index.js file. Add the following code to configure Cypress Cucumber Preprocessor:

const cucumber = require('cypress-cucumber-preprocessor').default;

module.exports = (on, config) => {

  on('file:preprocessor', cucumber());


6. Create Cypress Configuration File: Create a cypress.config.js configuration file in your project root directory:

const { defineConfig } = require('cypress')

module.exports = defineConfig({

  'cypress-cucumber-preprocessor': {

    nonGlobalStepDefinitions: false,

    step_definitions: './cypress/e2e/login/',


  e2e: {

    setupNodeEvents(on, config) {

      return require('./cypress/plugins/index.js')(on, config)


    specPattern: 'cypress/e2e/**/*.feature',




This configuration tells Cypress to use the Cypress Cucumber Preprocessor for feature files (“testFiles”) and specifies the path to the step definitions (“step_definitions“) directory.

7. Create the test case: Create a Gherkin feature file named login.feature in the cypress/e2e directory with the following content:

Feature: Login to a website

  Scenario: Successful login

    Given I open the website

    When I enter my username "myusername" and password "mypassword"

    And I click the login button

    Then I should be logged in

Create a JavaScript file named login.js in the cypress/e2e/login directory with the following content for the step definitions:

import { Given, When, Then, And } from 'cypress-cucumber-preprocessor/steps';

Given('I open the website', () => {

  cy.visit(''); // Replace with your website URL


When('I enter my username {string} and password {string}', (username, password) => {




And('I click the login button', () => {



Then('I should be logged in', () => {

  cy.url().should('eq', ''); // Replace with the expected URL after successful login

  cy.contains('Welcome, User!').should('be.visible'); // Replace with an element or text on the dashboard page


8. Run Cypress Tests: You can now run your Cypress tests with Cypress Cucumber Preprocessor by using the following command:

npx cypress open
Automation Testing Cypress

Featured Articles

How to Run Tests with Cypress and Cucumber

What is Cucumber Framework? (Benefits of Cucumber Testing)

App & Browser Testing Made Easy

Seamlessly test across 20,000+ real devices with BrowserStack