Connecting your Cypress project to Cypress Cloud is an essential step to enhance your testing workflow. Cypress Cloud offers robust features such as test recording, parallelization, and integration with CI/CD pipelines, which can significantly improve the efficiency and visibility of your test results. In this guide, we’ll walk through the steps to set up and connect your Cypress project to Cypress Cloud, ensuring a seamless integration.
Setup Cypress Cloud Account
- First, sign up for a Cypress Cloud account at Cypress Cloud.
- Once registered, create a new project in the Cypress Cloud dashboard. This project will be linked to your local Cypress project.
Add Cypress Project ID To Your Local Project
In your local project, let’s add project id to the or cypress.config.js file. You can find this file in the root of the project.
const { defineConfig } = require('cypress');
module.exports = defineConfig({
projectId: 'your-project-id',
// other configurations
});
Choose Your CI Provider – GitHub
To start recording test runs in a pipeline we have to configure our CL Provider in this case, we’ll be confgure the the GitHub Actions.
-
Record a run - In Terminal run this command
npx cypress run --record --key your-record-key
-
Set
CYPRESS_RECORD_KEY
in the GitHub repo.
Settings Secrets and Variables Actions then createNew repository secret
- Cypress.yml - Create a directory and create new yml file to store the pipeline configurations.
Create Cypress.yml File
To set up your Cypress project for seamless integration with CI/CD pipelines, the first step is to create a directory and a new cypress.yml
file. This file will house all your pipeline configurations, ensuring your testing processes are streamlined and efficient. Navigate to your project directory, and within the Cypress local project, add a new directory at the following location:
.github workflows .
In the Cypress Cloud Setup Guide, you’ll start by copying the generated cypress.yml
file that’s been tailored for your project. To better align this configuration with the specific needs of your project, I’ve made several adjustments to the file.
Cypress YML File Tweaks
- Cypress YML File - New file created.
- Focus On Main Branch Only - Refined the on push step to trigger exclusively when changes are pushed to the main branch.
- Self Hosted - Using local workstation as the runner in GitHub.
- Single Container - Optimized resource usage by reducing the number of containers from two to one.
- Added Build & Start Scripts - Added two essential scripts: 'build' and 'start'. These scripts are designed to efficiently prepare and initialize the project environment.
-
Environment Variable - Mod the environment variable naming convention by updating
GH_TOKEN
to replace the restrictedGITHUB_TOKEN
named variable.
Configure Your Runner & Personal Access Token
Before you commit your yaml file ensure that your that you have your Runner and PAT token are configured. Failure to do so will result in the test not running in the pipeline.
View Cypress Record Results In The Cloud.
Before finalizing the YAML file for our project, let’s take a moment to revisit your Cypress Cloud Account. Here, you should be able to see the previous test run that we initiated through the Terminal. This step is crucial as it ensures that the command we executed earlier has been correctly captured by Cypress Cloud.
Commit Your Cypress YML File
To effectively manage your YAML file execution within the pipeline and seamlessly integrate it with Cypress Cloud, you’ll first need to commit your changes. In my project, I utilize GitLens, a powerful tool for handling Git Pull and Push requests.
Begin by crafting a clear and concise commit message that reflects the changes made. Once your commit message is ready, push your changes directly to your branch. This process will trigger the pipeline, allowing you to observe the YAML file execution in real time.
Monitoring Cyress Cloud Run
After setting up and ensuring that everything is functioning smoothly, it’s time to verify whether Cypress Cloud is actively monitoring and recording your tests. You the commit message and as well as a blue spinning icon that shows that the test is in action!
Monitoring GitHub Pipeline Run
As your Cypress test runs, you’ll notice a yellow icon indicating that the process is ongoing. This yellow icon serves as a real-time status update, letting you know that your tests are actively running within the CI/CD pipeline. Once the job is complete, this icon will turn green, signaling that the tests have finished executing. At this point, the log will automatically display the results of the test run. If all the tests have passed successfully, you’ll be greeted with the message, “All specs passed!”
Reviewing Cypress CI/CD Results
To review your Cypress test results in greater detail, start by navigating to the test results section. First, exit the run details view. Once you’re out of the run details, select the most recent run from the list displayed. This will direct you to a page where you can view the detailed Cypress TestResult. Here, you will also find a convenient link that allows you to access these test results directly in the cloud.
View in Cypress Cloud
link, you’ll be seamlessly redirected to the Cypress Cloud results, offering a comprehensive overview of your test outcomes. It’s a smooth transition that enhances your testing workflow. Based on the configuration in my package.json
file, this script executed all the tests within the e2e
folder, specifically targeting the home-basic.cy.js
and home-advance.cy.js
tests. This setup ensures that your end-to-end testing is thorough and that the results are conveniently accessible through Cypress Cloud, optimizing your testing process and improving overall efficiency.Enabling Video Recording & Screenshots
To enable video capture in your Cypress test runs, you need to configure the appropriate settings in your cypress.config.js
file.
const { defineConfig } = require("cypress");
module.exports = defineConfig({
projectId: "[your-id-here]", // Add your projectId here
e2e: {
defaultCommandTimeout: 10000, // 10 seconds
pageLoadTimeout: 60000, // 60 seconds for page load
baseUrl: 'https://jahmalrichard.github.io/kicks-flutter-web-app/',
video: true, // This ensures video recording is enabled
videoCompression: 32, // This compresses the video to save space
screenshotOnRunFailure: true, // Automatically takes a screenshot when a test fails
screenshotsFolder: 'cypress/screenshots', // Specifies where screenshots are saved in the project
setupNodeEvents(on, config) {
// Add any node event listeners here
},
},
});
-
video
- Begin by setting the video property to true, which activates video recording for all your test executions. -
videoCompression
- To manage the size of the recorded videos, adjust the videoCompression setting to 32. This compression level strikes a balance between video quality and storage. -
screenshotOnRunFailure
- This feature automatically captures a screenshot whenever a test fails, providing a visual snapshot of the problem at the exact moment it occurs. -
screenshotsFolder
- By setting the screenshotsFolder to 'cypress/screenshots', you ensure that all screenshots are organized in a dedicated folder within your project.
Cypress Passed Test With Video PlayBack
Cypress Failed Test With Screenshot
Conclusion
Now that your Cypress project is connected to Cypress Cloud, you’ll immediately experience the powerful features Cypress Cloud offers. These features include parallel testing, seamless CI/CD integration, and automatic screenshots and videos.In the upcoming guide, we’ll dive deeper into Using Advance Assertions In Cypress.