Learn Cypress Cucumber: Part 1 - Intro and adding to an existing project

Introduction

This tutorial series is a companion to the video series I released as a playlist on YouTube.

In this post you will learn "What is Cypress Cucumber", "why you might use it" and "how to add it to an existing project".

You can also watch this tutorial on YouTube.

What is Cypress?

Cypress is an end-to-end testing utility that allows you to write your tests in JavaScript (or TypeScript).
The Cypress website is located at https://www.cypress.io/

What is Cypress Cucumber?

It is what I call using Cypress and a plugin for Cypress called Cypress-Cucumber-Preprocessor.

Cypress-Cucumber-Preprocessor allows you to write your tests in a language called Gherkin which is widely adopted in the testing industry for writing Behaviour Driven Development (BDD) tests.
Cypress-Cucumber-Preprocessor is available on GitHub: https://github.com/TheBrainFamily/cypress-cucumber-preprocessor

Why would you use Cypress?

In my opinion Cypress is really easy to setup and use, has a great interactive test runner, can record videos and screenshots of your tests, has great adoption in the industry and a great community behind it.

Why would you use Cypress-Cucumber-Preprocessor?

Your team has adopted BDD, your team has adopted the Gherkin language or it is just your preference to write tests in this way.

Initial repository

We are going to take TodoMVC a pre-built application written in many frameworks and we're going to add Cypress Cucumber tests so that we can verify that it works in the way that we expect.

I've created a repository on GitHub called learn-cypress-cucumber and I've got the base "todomvc-typescript-react" application checked out into it.

If you want to follow along start at this commit

In a terminal in the repository at the commit above...

cd todomvc-typescript-react
npm install
npm start

You will see that the TodoMVC application is serving on http://localhost:4200

Open the above URL in your browser and you will see the TodoMVC application.

Explore around and see that you can:

Add one or more todos

Complete a todo

Delete a todo

Filter by active

Filter by completed

Clear all completed todos

Adding Cypress and Cypress-Cucumber-Preprocessor

Run the following command to install both tools as development dependencies because we will not need them when running this application in a production environment.

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

Next let's edit the package.json file and we are going to add a script after the "start" script. We're going to call it "cy:open" and it will script when executed will open cypress in interactive test runner mode.

// package.json
...
"scripts": {
...
    "cy:open": "cypress open"
  },
...

Let's test it by executing the script

npm run cy:open

The first time we open cypress, it will verify that our system can run cypress correctly and if so, cypress will open.

The main cypress window will open and by default cypress will add some examples to our test folder.

Let's close the cypress window since we have confirmed it opens successfully.

Configure Cypress

Let's edit the cypress.json file, it gets created for us with an empty object {} inside.

Let's tell cypress that our base URL is the URL where TodoMVC runs and that our test files are any files that have an extension of "feature" or "features".

// cypress.json
{
  "baseUrl": "http://localhost:4200/",
  "testFiles": "**/*.{feature,features}"
}

Configure Cypress-Cucumber-Preprocessor

Now let's edit the cypress/plugins/index.js to include the plugin.

Import the plugin:

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

Tell cypress to run the cucumber plugin when preprocessing the test files:

module.exports = (on, config) => {
  on("file:preprocessor", cucumber());
};

Next we configure cypress-cucumber-preprocessor in the package.json file.

Add the following to the bottom of the package.json file:

"cypress-cucumber-preprocessor": {
    "nonGlobalStepDefinitions": true
  }

Adding our first feature file

Create a file called cypress/integration/home-page.feature and let's write a simple test to verify that we can see the home page and that cypress and cypress-cucumber-preprocessor are working correctly.

Feature: Home page
  Scenario: See the home page
    Given I navigate to the home page
    When the home page has loaded
    Then I see the home page

Now we have our feature file we need to create a javascript file that will contain the step definitions for each of the instructions in the feature file.

Create a file called cypress/integration/home-page/steps.js

Navigating to the home page means we are visiting the root URL of our application.
The home page has loaded when the element with class="todoapp" is visible on the page.
Seeing the home page means that the element with class="header" is visible on the page along with the element with class="info".

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

Given("I navigate to the home page", () => {
  cy.visit("/");
});

When("the home page has loaded", () => {
  cy.get(".todoapp").should("be.visible");
});

Then("I see the home page", () => {
  cy.get(".header").should("be.visible");
  cy.get(".info").should("be.visible");
});

Running our test

Ensure that the TodoMVC application is running:

npm start

Open the cypress interactive test runner:

npm run cy:open

Run the home-page.feature test by clicking on it in the list.

You should see that the test passes successfully.

Done

That is an existing application up and running using Cypress and Cypress-Cucumber-Preprocessor.

Be sure to check out the next parts in this tutorial series to see how we will test all the features of the TodoMVC application as well as how we can setup Visual Studio Code for Cypress Cucumber development.