Running Cypress Tests on GitLab CI: A Comprehensive Guide

In this article, we’ll walk through how to set up GitLab CI to run Cypress tests on multiple browsers (Chrome and Firefox) in parallel. We’ll use an updated package.json file for our Cypress project and provide suggestions on how to expand and enhance your pipeline with additional features.

1. Project Setup

Updated Package.json

Below is an example of an updated package.json file that includes the necessary scripts and dependencies for running Cypress tests:

{
  "name": "cypress_project",
  "version": "1.0.0",
  "scripts": {
    "chrome-test": "cypress run --browser chrome",
    "firefox-test": "cypress run --browser firefox"
  },
  "dependencies": {
    "cypress": "^14.2.1",
    "typescript": "^5.8.2"
  }
}

Explanation:

Scripts:

• chrome-test: Runs Cypress tests using the Chrome browser.
• firefox-test: Runs Cypress tests using the Firefox browser.

Dependencies:

• cypress: The testing framework.
• typescript: For type-checking and improved developer experience.

Before moving to CI, ensure your tests run correctly locally by executing these commands.

2. Configuring GitLab CI

Creating the .gitlab-ci.yml File

In your project’s root directory, create a file named .gitlab-ci.yml with the following configuration:

stages:
  - test
Environment variables common to jobs
variables:

  BROWSER_IMAGE: "cypress/browsers:latest"
  CHROME_BROWSER: "chrome"
  FIREFOX_BROWSER: "firefox"

ui_tests_chrome:
  stage: test
  image: $BROWSER_IMAGE
  script:
    - npm i
    - npm run chrome-test
  artifacts:
    when: always
    paths:
      - cypress/screenshots

ui_tests_firefox:
  stage: test
  image: $BROWSER_IMAGE
  script:
    - npm i
    - npm run firefox-test
  artifacts:
    when: always
    paths:
      - cypress/screenshots

Key Points:

• Stages:
  Both jobs belong to the test stage, which allows GitLab to execute them in parallel if runners are available.
• Variables:
• BROWSER_IMAGE: The Docker image that includes both Chrome and Firefox.
• CHROME_BROWSER and FIREFOX_BROWSER: These allow you to easily specify the browser for each test script.
• Jobs:
• ui_tests_chrome: Installs dependencies (npm i) and runs the chrome-test script.
• ui_tests_firefox: Installs dependencies and runs the firefox-test script.
• Artifacts:
  Artifacts such as screenshots are stored after each job, which is useful for debugging failures.

3. Running Your Tests in Parallel

Once you push your project to GitLab, the CI/CD pipeline will start automatically. Because both jobs are in the same stage, they run concurrently, reducing overall test execution time. You can view the job logs and artifacts (like screenshots) from the GitLab interface.

Executing the test jobs in parallel will save a lot of time when you have multiple things to run.

Execution result for the Pipeline

4. Expanding Your Pipeline: Additional Options and Features

As your project grows, you might consider adding more options and features to your CI pipeline. Here are some suggestions:

Caching Dependencies

Speed up your pipeline by caching node_modules between jobs:

cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - node_modules/

Integrating Allure Reporting

For richer test reports, integrate Allure by installing the necessary plugins (such as @shelex/cypress-allure-plugin and allure-commandline) and adding a post-test script to generate and publish the Allure report.

Enhanced Parallelization

Split your tests into smaller groups or suites so you can run multiple jobs concurrently. Tools like Cypress Dashboard can help manage parallel test runs and provide detailed analytics.

Environment-Specific Configurations

Use GitLab CI variables or separate configuration files for different environments (e.g., staging, production). This approach allows you to run tests against various environments using dynamic variables.

Pre-Test Linting and Build Steps

Integrate additional stages in your pipeline for:

• Linting: Use ESLint or a similar tool to ensure code quality before running tests.
• Build: Build your application if necessary before running integration or end-to-end tests.

Custom Docker Images

If you need specific versions of Chrome, Firefox, or additional system dependencies, consider creating a custom Docker image tailored to your project’s requirements.

5. Conclusion

By following this guide, you now have a solid foundation for running Cypress tests on GitLab CI with the capability to run tests in parallel on both Chrome and Firefox. The provided package.json and .gitlab-ci.yml files serve as a starting point, and with the additional suggestions, you can expand your pipeline to include caching, enhanced reporting, environment-specific configurations, and more.

This setup not only improves the speed of your test runs through parallel execution but also offers a robust framework that can evolve with your project’s needs.

I have created a project on Gitlab and added the code here. Also I have added the pipeline link to view the results here.

Feel free to hit clap if you like the content. Happy Automation Testing :) Cheers. 👏

If you guys want to support my work, then leave me a good rating for my Chrome plugin here.