How to install Cypress: A Complete Guide

In this tutorial we will show you how to install Cypress via npm, yarn. We will also show you how to install Cypress via direct download and how to version and run Cypress via package.json.

System requirements

To use Cypress, you will have install the desktop application on your computer. Here is a list of operating systems that Cypress supports.

• macOS 10.9 and above (64-bit only)
• Linux Ubuntu 12.04 and above, Fedora 21 and Debian 8 (64-bit only)
• Windows 7 and above

If you are using npm to install Cypress, Cypress supports

• Node.js 8 and above

Installing

Option A

Installing via npm

You can install Cypress via npm,to do this you have to cd into your project directory and run

npm install cypress -save-dev

when you run this, it will install Cypress as a dev dependency for your project.

Ensure that you either have a package.json file or a node_modules folder in your project directory. This ensures that Cypress is installed in the correct directory.

The Cypress docs recommends that you install Cypress with npm because:

• Cypress is versioned just like any other dependency.
• Using npm simplified the process of running Cypress in continuous Integration.

Installing via yarn

You can also install Cypress using yarn, to do this, you have to cd into your project directory, then you run the command shown below:

yarn add cypress --dev

Option B

Direct download

Option A of this guide is only applicable if you are using Node or npm in your project, if you are not, you can always download the zipped file to try Cypress out (https://download.cypress.io/desktop). However, you will not be able to record the Dashboard, this file is only useful when you want to try Cypress out.

The direct download always uses the latest available version and it will detect your platform automatically. Once you download the zipped file the first step is to unzip, then double click on it. Cypress runs without having to install any dependencies.

Opening Cypress

If you installed Cypress using npm, Cypress is installed to your ./node_modules directory, and the binary executable is accessible from ./node_modules/.bin.

You can now open Cypress from your project root in either of the following ways:

• By going through the long way using the full path, that is by running the following command from your terminal ./node_modules/.bin/cypress open
• With the aid of a shortcut using npm bin. This is done by running $(npm bin)/cypress open
• With the use of npx, to do this you have to run npx cypress open.
• Finally, you can open Cypress using yarn by running yarn run cypress open

Switching browsers

The Cypress Test Runner will attempt to find all the compatible browsers on your machine. You will find the drop down to select a different browser is in the top right corner of the Test Runner.

Adding npm scripts

Although there is nothing wrong with writing out the full path to the Cypress executable each time, it is much easier and clearer for you to add Cypress commands to the scripts field of your package.json file.

{
  "scripts": {
    "cypress:open": "cypress open"
  }
}

Once this is done, you can open cypress from your project by running the following command:

npm run cypress:open

CLI tools

When you install Cypress using npm you also get access to many other CLI commands.

As of Cypress version 0.20.0, there is a node_module that you can require in your Node scripts.

Advanced

Environment variables

CYPRESS_INSTALL_BINARY, CYPRESS_DOWNLOAD_MIRROR, CYPRESS_CACHE_FOLDER,

CYPRESS_RUN_BINARY, CYPRESS_SKIP_BINARY_INSTALL, CYPRESS_BINARY_VERSION

Install binary

You can use the CYPRESS_INSTALL_BINARY environment variable to control how Cypress is installed. If you want to override what is installed, you have to set CPRESS_INSTALL_BINARY alongside the npm install command.

This is helpful when you want to:

• Install a version of Cypress that is different from the default npm package.

'''CYPRESS_INSTALL_BINARY=2.0.1 npm install [email protected]'''

• Specify an external URL (in order to bypass a corporate firewall)

'''CYPRESS_INSTALL_BINARY=https://company.domain.com/cypress.zip npm install cypress'''

• Specify a file that you want to install locally, rather than using the internet.

'''CYPRESS_INSTALL_BINARY=/local/path/to/cypress.zip npm install cypress'''

Skipping Installation

You can force Cypress to skip the installation of the binary application, all you need to do is to set CYPRESS_INSTALL_BINARY=0.

CYPRESS_INSTALL_BINARY=0 npm install

When you run the above command from the command line, Cypress skips its install phase once the npm module is installed.

Download URLs

To download a particular version for a given platform (operating system), you can get it from the CND.  The base download server URL is https://download.cypress.io

Here is a list of the available URLs:

• Windows 64-bit (?platform=win32&arch=x64)
• Windows 32-bit (?platform=win32&arch=ia32, available since Cypress 3.3.0)
• Linux 64-bit (?platform=linux)
• macOS 64-bit (?platform=darwin)

Mirroring

You can specify CYPRESS_DOWNLOAD_MIRROR if you chose to mirror the entore Cypress download site, this will set the download server URL form https://download.cypress.io to your own mirror.

For example:

'''CYPRESS_DOWNLOAD_MIRROR="https://www.example.com" cypress install'''

Install pre-release version

There are rare cases where you want to install a pre-release version of Cypress to verify a fix from the develop branch, which has not yet been published.