Parallel Test Runs in Gitlab with Cypress

My motivation is simple yet righteous: I want to spare you the struggle I faced. One main issue with open-source software is that it may not always be as open as expected. For instance, many Udemy courses provide helpful information, but they often include username and password in their config files, which is unrealistic in a real-world scenario. Finding straightforward answers to such issues can be challenging, as they are not always readily available. Additionally, with Cypress, it can be tough to find solutions on platforms like Stack Overflow, the Cypress Discord channel, or their Gitter channel. This could be due to a decline in the tool’s popularity in the QA world, but I’m not sure.

source: Dall-e (blame it :) )

cypress-parallel vs cypress-split

I want to clarify the difference between various Cypress parallelization packages. The one that helped me run tests in parallel locally is cypress-parallel, which is also the most downloaded package. However, the documentation mentions that it cannot be used with CI/CD, and I have not seen anyone successfully implement it in CI/CD. If you have seen an example, please direct me to it.

Add the following scripts to your project’s package.json after downloading the package:

"scripts":{ 
  "cy:dev": "cypress run --config-file cypress-dev-config.js",
  "cy:qa": "cypress run --config-file cypress-qa-config.js",
  "cy:parallel:spec:local:dev": "cypress-parallel -s cy:dev -t 5 -d cypress/e2e/** -r cypress-multi-reporters",
  "cy:parallel:spec:local:qa": "cypress-parallel -s cy:qa -t 5 -d cypress/e2e/** -r cypress-multi-reporters"
}

And add the following to your config files:

reporter: "cypress-multi-reporters",
reporterOptions: {
  reporterEnabled: "mochawesome",
  mochawesomeReporterOptions: {
    reportDir: "cypress/reports/html/.jsons",
    quite: true,
    overwrite: false,
    html: false,
    json: true,
  }
},

The reporter part can be confusing. If you prefer using mochawesome-reporter, be aware that earlier versions were not compatible, but the latest version should work. To be safe, use cypress-multi-reporters.

For CI/CD implementation, I found the cypress-split package to be the best option. Created by Cypress expert Gleb Bahmutov, it has courses on various Cypress topics. However, the documentation for this package is poorly organized. Although Gleb has provided examples for different CI tools, including GitLab CI, I found them difficult to implement. Here's how you can make it work:

After downloading the package, add this to your package.json:

"cy:gitlab:dev": "cypress run --config-file cypress-dev-config.js --env grepTags=@parallel,split=true --spec \"$(npx cypress-split --ci --build-id $CI_PIPELINE_ID --total $SPLIT_INDEX)\"",
"cy:gitlab:qa": "cypress run --config-file cypress-qa-config.js --env grepTags=@parallel,split=true --spec \"$(npx cypress-split --ci --build-id $CI_PIPELINE_ID --total $SPLIT_INDEX)\""

in your config file;

import cypressSplit from 'cypress-split'

setupNodeEvents(on,config){
cypressSplit(on,config);

}

In your gitlab-ci.yml file:

parallel: <number of parallel jobs>

script:
  - cd frontend
  - yarn install
  - echo "SPLIT:$SPLIT"
  - echo "SPLIT_INDEX1:$SPLIT_INDEX1"
  - echo "CI_PIPELINE_ID:$CI_PIPELINE_ID"
  - SPLIT_INDEX1=$CI_NODE_INDEX yarn run cy:gitlab:dev

For debugging, add this script to :

DEBUG=cypress-split,find-cypress-specs yarn $SPLIT

I hope you found the article informative and helpful for your investigations or decision-making process. Please feel free to provide feedback, as some of these insights are new to me as well.