How to install Cypress on any system
Ensuring the robustness of your applications through efficient testing is essential in the dynamic field of web development. Cypress is a popular end-to-end testing framework for developers looking to improve and streamline their testing procedures. In this blog, we’ll examine several methods for installing Cypress.
Table of Contents
- Prerequisites for Installing Cypress
- Minimum system requirements
- Installing Cypress using Node.js
- Installing Cypress using yarn, pnpm, or direct download
- Advanced Installation
- Best Practices
- Common installation issues and troubleshooting
- Final thoughts on the Cypress installation
Prerequisites for Installing Cypress
Make sure your development environment satisfies the following requirements before installing Cypress.
Node.js
Node.js is a cross-platform, open-source JavaScript runtime environment that can run on Windows, Linux, Unix, macOS, and more. Cypress is built on top of Node.js, so you need to have Node.js installed.
A package manager
A package manager, also known as a package-management system, is a group of software tools that systematically automates the steps involved in installing, updating, configuring, and uninstalling computer programs. The most popular package managers are npm (node package manager), yarn, and pnpm (performant npm). Make sure one of them is installed.
A Code Editor
Choose a code editor of your preference, such as Visual Studio Code, Atom, or Sublime Text. This is where you’ll write and manage your Cypress tests.
Web Browser
Cypress supports multiple browsers, but it uses Electron, a browser built into the Cypress installation by default. However, you can also run tests in other browsers like Chrome or Firefox. Make sure your preferred browser is installed on your system.
Operating System
Cypress supports Windows, macOS, and Linux. Ensure that your operating system is compatible. Refer to the Minimum System Requirements section for more details.
Minimum system requirements
Operating System
- macOS 10.9 and above (Intel or Apple Silicon 64-bit (x64 or arm64))
- Windows 10 and above (64-bit only)
- Linux Ubuntu 20.04 and above, Fedora 21 and Debian 8 (x86_64 or Arm 64-bit (x64 or arm64))
Hardware
Cypress should function smoothly when used locally on any computer that is capable of modern web development. When running Cypress in CI, we recommend that you have the following hardware requirements.
Central processing unit (CPU)
- 2 CPUs minimum to run Cypress
- 1 additional CPU if video recording is enabled
- 1 additional CPU per process you run outside of Cypress, such as:
- App server (frontend)
- App server (backend)
- App database
- Any additional infrastructure (Redis, Kafka, etc..)
Memory
- 4GB minimum, 8GB+ for longer test runs
Installing Cypress using Node.js
Node.js is an open-source, cross-platform JavaScript runtime environment. Let’s follow the below steps to install Cypress using Node.js.
Installation of Node.js
To install Node.js, you can follow these general steps. Keep in mind that the specific steps might vary slightly depending on your operating system.
Mac
Using Homebrew (Recommended)
- Open Terminal.
- Install Homebrew if you don’t have it already: Homebrew.
- Run the following commands to install Node.js and npm.
brew update
brew install node
Using Official Installer
- Visit the official Node.js website: Node.js Downloads.
- Download the LTS (Long-Term Support) version.
- Run the installer package and follow the on-screen instructions.
Windows
Using Official Installer
- Visit the official Node.js website: Node.js Downloads.
- Download the LTS (Long Term Support) version recommended for most users.
- Once the download is complete, run the installer executable.
- Follow the installation wizard, accepting the default settings if you’re unsure.
Linux
Using Package Manager (e.g., apt, yum, dnf)
- Open a terminal.
- Use your distribution’s package manager to install Node.js and npm. For example, on Ubuntu, you can run the below code.
sudo apt update
sudo apt install nodejs npm
Using NodeSource
- You can use NodeSource repositories for more up-to-date versions of Node.js. Follow the instructions on the NodeSource website: NodeSource Installation Instructions.
Setting Up a New Project
Before installing Cypress, let’s set up a new project to organize our testing environment. Follow these steps to create a new project:
Creating a Project Directory:
Choose or create a directory on your machine where you want to store your Cypress project. Open a terminal or command prompt and navigate to the chosen directory:
mkdir my-cypress-project
cd my-cypress-project
Initializing a New Node.js Project:
Run the following command to initialize a new Node.js project:
npm init -y
This command creates a package.json file with default settings for your project. Now that your project is set up let’s proceed to install Cypress.
Installing Cypress
Cypress can be installed either globally or locally within your project. Both approaches have their advantages.
Local Installation
Follow these steps to install Cypress locally in your project. Installing Cypress locally is often recommended as it allows you to have project-specific versions of Cypress and manage dependencies more effectively.
- Open a terminal or command prompt.
- Navigate to your project’s root directory using the
cd
command:
cd path/to/your/project
- Run the following command to initialize a new npm project if you haven’t already:
npm init -y
- Run the following command to install Cypress as a development dependency:
npm install --save-dev cypress
This installs Cypress locally in the node_modules
directory of your project and adds it to the devDependencies
section of your package.json
file. System proxy properties http_proxy
, https_proxy
, and no_proxy
are respected for downloading the Cypress binary.
- Once the installation is complete, you can verify that Cypress is installed locally by running:
npx cypress -v
The npx
command ensures that you’re using the locally installed version of Cypress.
By installing Cypress locally, you ensure that your project has the version of Cypress it needs, and other developers working on the project can easily use the same version by running npm install
. It also allows for better version control and avoids conflicts between projects using different Cypress versions.
Global Installation
To install Cypress globally, you can install npm (Node Package Manager) as a global package. The global installation allows you to run Cypress commands from any project directory on your machine. Here are the steps:
- Open a terminal or command prompt.
- Run the following command to install Cypress globally:
npm install -g cypress
The -g
flag stands for global, and it ensures that Cypress is installed globally on your machine.
- Once the installation is complete, you can verify that Cypress is installed globally by running:
cypress -v
This command should display the installed Cypress version.
Keep in mind that global installations might require elevated privileges on some systems (e.g., using sudo
on Linux or macOS). If you encounter permission issues, consider using sudo
or installing Cypress locally in your project directory.
Note: While global installation is convenient for running Cypress commands from any project, it’s also common to install Cypress locally in a project (as a development dependency) using npm install --save-dev cypress
. This approach ensures that your project has its own version of Cypress, and different projects can use different versions if needed.
Installing Cypress using yarn, pnpm, or direct download
Cypress can be installed in various ways, including using package managers like yarn or pnpm, or by direct download. Here are instructions for each method:
yarn
If you prefer using yarn as your package manager, follow these steps:
- Open a terminal in your project’s root directory.
- Run the following command to add Cypress as a development dependency using yarn:
yarn add --dev cypress
System proxy properties http_proxy
, https_proxy
and no_proxy
are respected for downloading the Cypress binary.
- Once the installation is complete, you can verify that Cypress is installed locally by running:
npx cypress -v
The npx
command ensures that you’re using the locally installed version of Cypress.
pnpm
If you are using pnpm, you can install Cypress as follows:
- Open a terminal in your project’s root directory.
- Run the following command to add Cypress as a development dependency using pnpm:
pnpm add cypress -D
You need to make sure that you have the pnpm environment installed locally. If not, you need to install it: npm install pnpm@latest -g
Direct download
If you prefer not to use a package manager, you can also download Cypress directly and manually install it:
- Visit the official Cypress website: Cypress Download.
- Download the Cypress.zip file
- Extract the file and double-click on the Cypress app.
Note: The direct download makes recording runs to Cypress Cloud impossible. This download is only intended as a quick way to try out Cypress. To record tests in Cypress Cloud, you’ll need to install Cypress as a npm
dependency.
Advanced Installation
Cypress provides advanced installation options for specific use cases or requirements. The advanced installation options include downloading specific versions and customizing the installation. Here are some advanced installation scenarios:
You can modify how Cypress is installed using the CYPRESS_INSTALL_BINARY environment variable. You use the npm install
command along with CYPRESS_INSTALL_BINARY to override the installed version. This is beneficial if you choose to:
Install binary
- Install a version different than the default npm package.
shell CYPRESS_INSTALL_BINARY=2.0.1 npm install cypress@2.0.3
- Specify an external URL (to bypass a corporate firewall).
shell CYPRESS_INSTALL_BINARY=https://company.domain.com/cypress.zip npm install cypress
- Specify a file to install locally instead of using the internet.
shell CYPRESS_INSTALL_BINARY=/local/path/to/cypress.zip npm install cypress
In all cases, the fact that the binary was installed from a custom location is not saved in your package.json
file. Every repeated installation needs to use the same environment variable to install the same binary.
By configuring CYPRESS_INSTALL_BINARY=0, you can also make Cypress skip installing the binary application. This might be helpful if you want to stop Cypress from downloading the Cypress binary during the npm install.
Binary cache
As of version 3.0
, Cypress downloads the matching Cypress binary to the global system cache so that the binary can be shared between projects. You can reduce install time by several minutes by making sure that this cache is maintained between builds and avoiding a huge binary download. By default, global cache folders are:
- MacOS:
~/Library/Caches/Cypress
- Linux:
~/.cache/Cypress
- Windows:
/AppData/Local/Cypress/Cache
Set the environment variable CYPRESS_CACHE_FOLDER
to override the default cache folder.
CYPRESS_CACHE_FOLDER=~/Desktop/cypress_cache npm install
Code language: JavaScript (javascript)
Please refer to the Cypress official documentation for more details.
Run binary
You can set up the environment variable CYPRESS_RUN_BINARY overrides where the npm
module finds the Cypress binary. A path to an executable binary that has already been unzipped should be provided by CYPRESS_RUN_BINARY. The Cypress commands open
, run
, and verify
will then launch the provided binary. Please refer to the Cypress official documentation for more details.
Download URLs
You can obtain a specific Cypress version from our CDN if you’d like to download it for a particular platform (Operating System).
Here are the available download URLs:
See the latest available CDN destinations for all available platforms.
Method | URL | Description |
---|---|---|
GET | /desktop | Download the latest Cypress version (platform auto-detected) |
GET | /desktop.json | Returns JSON containing latest available CDN destinations |
GET | /desktop?platform=p&arch=a | Download Cypress for a specific platform and/or architecture |
GET | /desktop/:version | Download Cypress with a specified version |
GET | /desktop/:version?platform=p&arch=a | Download Cypress with a specified version and platform and/or architecture |
- Windows 64-bit (
?platform=win32&arch=x64
) - Linux 64-bit (
?platform=linux
) - macOS 64-bit (
?platform=darwin
)
Example of downloading Cypress 10.0.0 for Windows 64-bit:
https://download.cypress.io/desktop/10.0.0?platform=win32&arch=x64
Code language: JavaScript (javascript)
Mirroring
You can set the download server URL from https://download.cypress.io
to your own mirror by specifying CYPRESS_DOWNLOAD_MIRROR
if you would like to mirror the entire Cypress download site.
Once you set up CYPRESS_DOWNLOAD_MIRROR
as follows:
CYPRESS_DOWNLOAD_MIRROR="https://www.mycypress.com" cypress install
Code language: JavaScript (javascript)
Then, Cypress will try to download a binary in this format: https://www.mycypress.com/desktop/:version?platform=p
Download the path template
Starting with Cypress 9.3.0, you can use the CYPRESS_DOWNLOAD_PATH_TEMPLATE environment variable to download the Cypress binary from a custom URL generated based on an endpoint, version, platform, and architecture. Please refer to the Cypress official documentation for more details.
Using a custom certificate authority (CA)
Cypress can be set up to download the Cypress binary using the ca
and cafile
options from your npm
config file.
For instance, add the following to your .npmrc
in order to use the CA at /home/person/certs/ca.crt
when downloading Cypress:
cafile=/home/person/certs/ca.crt
Code language: JavaScript (javascript)
When Cypress downloads the binary, it looks for the corresponding certificate(s) as an extension for the trusted certificate authority in the system environment variable NODE_EXTRA_CA_CERTS
if neither cafile
nor ca
are set. Please refer to the Cypress official documentation for more details.
Install the pre-release version
Here’s how to install a pre-release version of Cypress so you can try out features that haven’t been officially released:
- Open up the list of commits to
develop
on the Cypress repo. - Find the commit that you would like to install the pre-release version of. Click the comment icon.
- You should see several comments from the
cypress-bot
user with instructions for installing Cypress pre-releases. Pick the one that corresponds to your operating system and CPU architecture, and follow the instructions there to install the pre-release.
Cypress pre-releases are only available for 60 days after they are built. Do not rely on these being available beyond 60 days. Please refer to the Cypress official documentation for more details.
How to install a specific version of Cypress
To install a specific version of Cypress, you can use npm (Node Package Manager) or yarn by specifying the version number you want to install. Here’s how.
Using npm
Open your terminal or command prompt and run the following command, replacing x.x.x
with the specific version number you want to install:
npm install cypress@x.x.x
Code language: CSS (css)
For example, if you want to install version 8.5.0 of Cypress, you would run:
npm install cypress@8.5.0
Code language: CSS (css)
This will download and install the specified version of Cypress in your project’s node_modules
directory.
Using yarn
yarn add cypress@x.x.x
Code language: CSS (css)
After installing the specific version of Cypress, you can use it in your project as usual. Keep in mind that Cypress versions might have dependencies or compatibility requirements with specific Node.js versions, so ensure that the version you install is compatible with your project’s setup.
Additionally, if you’re using Cypress as a global dependency (installed globally on your system), you can also specify the version when installing globally:
npm install -g cypress@x.x.x
Code language: CSS (css)
or
yarn global add cypress@x.x.x
Code language: CSS (css)
This will install the specified version of Cypress globally on your system, which you can then use in any Cypress project.
Best Practices
Here are some best practices for installing Cypress:
- Use a Package Manager.
- Use npm or yarn to install Cypress. This ensures that Cypress and its dependencies are appropriately managed.
- Install Locally.
- Install Cypress locally within your project rather than globally. This helps to ensure that your project uses the Cypress version it requires.
- Define Scripts in package.json.
- Add npm scripts for running Cypress commands in your project’s
package.json
file. This makes it easier for team members to run tests consistently.
- Add npm scripts for running Cypress commands in your project’s
Common installation issues and troubleshooting
Even though cypress installation is pretty straightforward, you may encounter some common installation issues. Here are some troubleshooting steps for addressing these problems:
- Node.js and npm Versions: Ensure you use a compatible version of Node.js and npm. Cypress maintains a compatibility chart on its documentation.
- Firewall and Proxy Issues: If you’re behind a firewall or using a proxy, ensure that Cypress can access the necessary resources. Cypress provides guidance on configuring proxy settings.
- Dependency Conflicts: Check for any conflicting dependencies in your project that might interfere with Cypress. Run
npm ls
to analyze your project’s dependency tree. - Clearing Cache: If you encounter unexpected behavior, consider clearing the Cypress cache using the
npx cypress cache clear
command.
Final thoughts on the Cypress installation
Mastering Cypress installation is crucial to building reliable and efficient web applications. By following the detailed steps and insights provided in this guide, you are well-equipped to set up Cypress for your projects seamlessly. Embrace the power of automated testing and elevate the quality of your web development workflow.
This comprehensive blog aims to empower developers at all levels to navigate the Cypress installation process effortlessly, unlocking the full potential of this versatile testing framework. Happy testing!
Related articles
Follow our blog
Be the first to know when we publish new content.
Cypress Installation Guide
- Introduction to Cypress - December 18, 2023
- Cypress Installation Step By Step - December 6, 2023
- Serenity BDD and Cucumber Testing - November 20, 2023