Creating your first Ci/Cd pipeline with Gitlab — A Beginners Guide.

Running your Cypress E2E tests with Gitlab Ci/Cd

Published in

Technogise

5 min readMar 19, 2024

In the world of technology, Cypress is a helpful tool used to test your applications. It checks if they’re working properly by creating tests for both the user interface (UI) and application programming interface (API). GitLab on the other hand is a platform for developers, helping them manage and automate their work, especially with version control. This guide aims to show you how to use Cypress and GitLab together easily to create a smooth system for building and testing your software.

Assuming that you are already familiar with the basics of the Cypress framework, we will begin with our project setup.

Basic project setup with Cypress

We will use a demo site called SwagLabs provided by Sauce Labs to automate our test scenario, As we gear up to automate our initial test scenario, I encourage you to join in and follow the upcoming steps.

First, let's add cypress to our project

npm install cypress --save-dev

If you notice so far the only project files impacted are package.json and package-lock.json.

Now we will open Cypress by running the following command in the terminal:

npx cypress open

This will open the Cypress Launchpad. We will select E2E Testing to configure it.

We will choose Chrome as the preferred browser for E2E testing.

Next, we’ll create a new spec (test), by clicking on ‘Create new spec’

Please provide your preferred path to create a new spec(test), for now, I will use the default path and file name that Cypress suggests.

If you look into the project folder structure, notice the following files have been created:

cypress.config.js
cypress/e2e/spec.cy.js

We’ll ignore the rest of the files and directories as they are not relevant for now.

Let’s modify the Cypress configuration file (cypress.config.js) and configure the baseUrl by adding the following property under e2e:

baseUrl: 'https://www.saucedemo.com/v1/'

Now the cypress.config.js looks as follows:

const { defineConfig } = require("cypress");
module.exports = defineConfig({
  e2e: {
    baseUrl: 'https://www.saucedemo.com/v1/',
    setupNodeEvents(on, config) {
      // implement node event listeners here
      this.screenshotOnRunFailure = true;
    },
  },
});

We will edit the specification (cypress/e2e/spec.cy.js) and replace its content with our simple test scenario:

describe("Homepage test", () => {
  it("Visit swag labs", () => {
    cy.visit("/");
    cy.get("input[type='submit']").should("have.value", "LOGIN");
  });
});

Change the package.json scripts and add the following command to run our test.

  "scripts": {
    "test": "npx cypress run"
  },

Run the Cypress tests locally

Now that we have a project structure set up, let’s run the Cypress E2E tests.

npm run test

The tests should be executed without any errors:

Adding Cypress to the GitLab CI pipeline

In Gitlab our CI journey begins with the concept of “stages.” We can think of them as different chapters in our CI story, dictating the order of tasks. In our case, we have one stage named “UI tests run,” where the spotlight is on our automated tests.

stages:
  - UI tests run

“automated_tests.” This job defines how our CI runner will perform UI tests. The image line specifies the environment where we will be running our tests in headless mode.

automated_tests:
  image: cypress/base
  stage: UI tests run

Now, we will be defining the actions to be performed in the script section. In simple terms, we're installing our project dependencies (npm ci) and running our Cypress tests (npm test).

script:
    - npm ci
    - npm test

Lastly, our CI pipeline wouldn’t be complete without preserving some important artifacts such as test failure screenshots or maybe HTML reports, The artifacts section ensures these key insights are saved for later review.

artifacts:
    when: always
    paths:
      - cypress/screenshots
      - cypress/reports/html

For reference here is the complete gitlab-ci.yml file will look like.

stages:
  - UI tests run

automated_tests:
  image: cypress/base
  stage: UI tests run

script:
    - npm ci
    - npm test

artifacts:
    when: always
    paths:
      - cypress/screenshots
      - cypress/reports/html

Want to use Chrome or Firefox to run the Cypress tests in GitLab CI?

When we push our code to GitLab and run the pipeline and if you are closely inspecting the job execution logs, you may notice that the Cypress tests have been executed with Electron 114.

What is Electron? it is a special type of web browser that’s built on the Electron framework. Unlike traditional browsers, it’s designed not just for viewing websites but also for running applications, it is typically used for building desktop apps using HTML and JavaScript.

Anyway, while Electron probably does the job of rendering our web app, we probably want to test it in a real browser that regular users might use, such as Chrome or Firefox.

So it’s time to make some changes, we need to tell Cypress that we want to run our tests on the Chrome browser for that we need to tweak scripts in the package.json file a little.

"scripts": {
    "test": "npx cypress run --browser chrome"
  },

we also need another thing to get the job done, have you guessed it already?

We’ll need a docker image that runs our tests on the browser Chrome but which one to use from the huge list of tags available? we’ll be using cypress/browsers:node18.12.0-chrome107

Please explore the available tags on DockerHub to find what you are looking for.

So just to recap, our gitlab-ci.yml file currently looks like this:

stages:
  - UI tests run

automated_tests:
  image: cypress/browsers:node18.12.0-chrome107
  stage: UI tests run

script:
    - npm ci
    - npm test

artifacts:
    when: always
    paths:
      - cypress/screenshots
      - cypress/reports/html

Now when you run the pipeline again you’ll notice that your tests are now running on the browser Chrome