Cypress Parallelization with GitLab CI

In the realm of modern software development, testing has evolved into a critical phase that ensures the quality, stability, and reliability of applications. As projects grow in complexity, so does the need for efficient testing processes. Running tests sequentially can lead to prolonged feedback cycles and slower development cycles. This is where Cypress parallelization combined with GitLab CI comes to the rescue. In this article, we'll delve into the world of parallel testing and explore how to harness the power of Cypress and GitLab CI for faster and more effective testing.

Everyone has probably heard of Cypress Cloud, which allows developers to run their e2e tests across multiple virtual machines in CI. Although it's an amazing tool, it can be quite costly for some teams. That's why we'd like to show an open source alternative called Sorry Cypress that your team can host on your own infrastructure.


  1. Install sorry-cypress on your infrastructure: If you need help setting up your infrastructure, don't hesitate to contact our dedicated DevOps team for assistance.
  2. Add cypress to your project and follow the steps from the offical documentation:
  3. Install the dependency npm install cypress-cloud
  4. Create a file currents.config.js next to your package.json
    module.exports = {  
      // Set your project name
      projectId: '',  
      // Sorry Cypress users - set the director service URL.
      cloudServiceUrl: '',  
  5. Extend your cypress.config.json and call the function cloudPlugin which will load your previously created configuration.
        import { defineConfig } from  'cypress'
        import { cloudPlugin } from  'cypress-cloud/plugin'
        export  default  defineConfig({
            e2e: {
                setupNodeEvents(on, config) {
                    return cloudPlugin(on, config)
  6. GitLab CI uses a configuration file named .gitlab-ci.yml to define your pipeline's stages, jobs, and associated settings. To enable Cypress parallel testing, define a job that runs your tests. We assume that you have in your package.json a task called start that starts your web application.
        image: cypress/browsers:node18.12.0-chrome107
        parallel: 3  #Specify how many workers you want to use
            RECORD_KEY: "xxxxxxxx"  # Save this secret in a safe place
            CYPRESS_BASE_URL: "http://localhost:4200"
            # install dependencies
            - npm i
            - npx start-server-and-test start $CYPRESS_BASE_URL 'cypress-cloud --parallel --record --key $RECORD_KEY --ci-build-id ${CI_COMMIT_REF_SLUG}-${CI_COMMIT_SHA}'


    • First we specify how many workers we want to use.
    • We set two variables CYPRESS_BASE_URL and RECORD_KEY .
      Important: The RECORD_KEY is defined by your infrastructure when setting up sorry-cypress. Save the secret in a safe place like Vault by HashiCorp.
    • Install all the dependencies
    • And finally, we use a package called start-server-and-test that runs npm run start to start the web server and waits until $CYPRESS_BASE_URL is reachable. After that, we can call cypress-cloud to start our tests.

    The arguments:

    --key: This is our RECORD_KEY which authorizes us to connect to sorry-cypress.
    --ci-build-id: Use the same value to associate different Cypress agents with the same run.


Cypress parallel testing is a game-changer for modern software development teams aiming to streamline their testing processes. By distributing test cases across multiple instances, you can achieve faster test execution, quicker feedback loops, and improved test coverage. With its scalable architecture and resource optimization, parallel testing with Cypress empowers developers to focus on building high-quality applications without sacrificing time or efficiency. So, if you're looking to supercharge your testing workflow, it's time to embrace the power of parallel testing with Cypress.