Part 2 - Hands-On Test Automation Project with Cypress + Cucumber + Docker

This article is a continuation of Part 1 - Basic Structure with Cypress. The implementation of Part 1 can be found in my demo-cypress project tagged as v1.0. You can download this release to use it as a starting point for this part of the article.

Part 2 - Cucumber

Depending on the way we want to structure our project just Cypress should be enough because it already includes a test framework: Mocha. However, we may want to use a BDD testing framework and for that we can use Cucumber. The cypress-cucumber-preprocessor adds support for feature files when testing with Cypress. To configure this library we will follow the steps:

• Install the plugin running on the root of the project the command:

npm install cypress-cucumber-preprocessor

• Add it to Cypress plugins "cypress/plugins/index.js".

const cucumber = require('cypress-cucumber-preprocessor').default
module.exports = (on, config) => {
  on('file:preprocessor', cucumber())
}

• Change the Cypress configuration (on cypress.json) to filter just the ".feature" files instead of "spec.js" files. 

"testFiles": "**/*.feature"

Now we are going to make the changes to our project to convert the "spec.js" file, that uses Mocha style, into Cucumber style. But first, let's understand how the recommended structure of folders work with this plugin. 

The cypress-cucumber-preprocessor plugin recommends that we place the .feature files under the "integration" folder. The .feature file will use step definitions from a directory with the same name as the .feature file. The JavaScript files containing the step definitions can have other names, but they need to be inside of the directory (that has the same name as the .feature file). Easier to show than to describe. 

Assuming our Login test scenario as an example, we would create a feature file in cypress/integration/Login.feature and the plugin will read all the files inside cypress/integration/Login/ (folder with the same name of the .feature) looking for the step definitions. The plugin also provides a way to create reusable step definitions putting them in cypress/integration/common.

The structure of the project would look like the following:

- cypress
  - integration
    - common
      - loginReusable.js
    - login
      - login.js
    - login.feature

From past experience with automation there are cases where we may need to reuse login step definitions in scenarios that are not part of the login feature (i.e., located in a different .feature file). In this recommended structure only login.feature file would be able to use the step definitions that are inside the folder login. The reusable step definitions would need to be placed inside another file in a separate folder (i.e., common). 

I have a personal preference to keep all step definitions of the same context (in this case Login) together. From my point of view, it looks more organized. The plugin supports this approach by creating a "step_definitions" folder inside the "support" folder, making everything global.

Therefore, following my personal preference, let's create the folder "step_definitions" inside the "support" folder, and "features" inside the "integration" folder. We will add all of our step definitions inside the "step_definitions" folder, organizing them in files by feature, and the "features" folder will host the .feature files. The structure will look like the following:

- cypress
  - integration
    - features
      - login.feature
    - pages
      - LoginPage.js
      - SecurePage.js
  - support
    - step_definitions
      - login.js

We need to convert our test scenario written in Mocha to the Gherkin language. Gherkin is a simple text language designed to be easy to learn by non-programmers, but structured enough to allow for a concise description of examples to illustrate business rules. It allows us to describe the behavior of the software without detailing how this behavior is implemented.

When we convert the test in the file login.spec.js to Gherkin, the test scenario would be like the following (ignore the tag @login which will be explained later). Create the file login.feature inside the folder "features" with:

@login
Feature: Login
 Scenario: Login successfully
  Given I open Login Page
  When I fill the username input with "tomsmith"
  And I fill the password input with "SuperSecretPassword!"
  And I click on Login button
  Then I see "You logged into a secure area!" message

Now we need to implement the steps defined on our .feature file. Create a "login.js" file inside the "step_definitions" folder to implement the code that will execute those steps. Import the Gherkin annotations Given, When and Then into the file and import the LoginPage and SecurePage classes that will be needed to interact with the elements on the page. Then create the steps needed on the test scenario.

The login.js file should look like the following:

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

import LoginPage from '../../integration/pages/LoginPage';

import SecurePage from '../../integration/pages/SecurePage';

 

const loginPage = new LoginPage();

const securePage = new SecurePage();

 

Given('I open Login Page', () => {

  loginPage.visitLogin();

});

 

When('I fill the username input with {string}', (username) => {

  loginPage.typeUsername(username);

});

 

When('I fill the password input with {string}', (password) => {

  loginPage.typePassword(password);

});

 

When('I click on Login button', () => {

  loginPage.clickLogin();

});

 

Then('I see {string} message', (expected) => {

  const message = securePage.getMessage();

  message.should((actual) => {

    expect(actual).to.have.string(expected);

  })

});

At this point we can delete the "tests" folder and the file under it. We should be able to execute the test scenario using the command:

./node_modules/.bin/cypress open

We are done with Part 2 of this article. :)

Remember to commit your changes to Git:

git add .
git commit -m "Adding Cucumber"
git push

The implementation of this part can be found in my demo-cypress project tagged as v2.0. You can download this release to check how it looks and/or use it as a starting point for the Part 3 of this article.

Thanks for reading! I hope you found it helpful.

If you enjoyed it, I appreciate your help in spreading it by sharing it with a friend.