W3cubDocs

/Cypress

Installing Cypress

What you’ll learn

  • How to install Cypress via npm
  • How to install Cypress via direct download
  • How to version and run Cypress via package.json

System requirements

Cypress is a desktop application that is installed on your computer. The desktop application supports these operating systems:

  • 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

Installing

npm install

Installing Cypress via npm is easy:

cd /your/project/path

npm install cypress --save-dev

This will install Cypress locally as a dev dependency for your project.

Make sure that you have already run npm init or have a node_modules folder or package.json file in the root of your project to ensure cypress is installed in the correct directory.

Notice that the Cypress npm package is a wrapper around the Cypress binary. The version of the npm package determines the version of the binary downloaded.
As of version 3.0, the binary is downloaded to a global cache directory to be used across projects.

Best Practice

The recommended approach is to install Cypress with npm because :

yarn add

Installing Cypress via yarn:

cd /your/project/path

yarn add cypress --dev

Direct download

If you’re not using Node or npm in your project or you just want to try Cypress out quickly, you can always download Cypress directly from our CDN.

The direct download will always grab the latest available version. Your platform will be detected automatically.

Just manually unzip and double click. Cypress will run without needing to install any dependencies.

Continuous integration

Please read our Continuous Integration docs for help installing Cypress in CI. When running in linux you’ll need to install some system dependencies or you can just use our Docker images which have everything you need prebuilt.

Opening Cypress

If you used npm to install, Cypress has now been installed to your ./node_modules directory, with its binary executable accessible from ./node_modules/.bin.

Now you can open Cypress from your project root one of the following ways:

The long way with the full path

./node_modules/.bin/cypress open

Or with the shortcut using npm bin

$(npm bin)/cypress open

Or by using npx

note: npx is included with npm > v5.2 or can be installed separately.

npx cypress open

Or by using yarn

yarn run cypress open

After a moment, the Cypress Test Runner will launch.

Switching browsers

The Cypress Test Runner attempts to find all compatible browsers on the user’s machine. The drop down to select a different browser is in the top right corner of the Test Runner.

Select a different browser

Read Launching Browsers for more information on how Cypress controls a real browser during end-to-end tests.

Adding npm scripts

While there’s nothing wrong with writing out the full path to the Cypress executable each time, it’s much easier and clearer to add Cypress commands to the scripts field in your package.json file.

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

Now you can invoke the command from your project root like so:

npm run cypress:open

…and Cypress will open right up for you.

CLI tools

By installing Cypress through npm you also get access to many other CLI commands.

As of version 0.20.0 Cypress is also a fully baked node_module you can require in your Node scripts.

You can read more about the CLI here.

Advanced

Environment variables

Name Description
CYPRESS_INSTALL_BINARY Destination of Cypress binary that's downloaded and installed
CYPRESS_DOWNLOAD_MIRROR Downloads the Cypress binary though a mirror server
CYPRESS_CACHE_FOLDER Changes the Cypress binary cache location
CYPRESS_RUN_BINARY Location of Cypress binary at run-time
CYPRESS_SKIP_BINARY_INSTALL removed use CYPRESS_INSTALL_BINARY=0 instead
CYPRESS_BINARY_VERSION removed use CYPRESS_INSTALL_BINARY instead

Install binary

Using the CYPRESS_INSTALL_BINARY environment variable, you can control how Cypress is installed. To override what is installed, you set CYPRESS_INSTALL_BINARY alongside the npm install command.

This is helpful if you want to:

  • Install a version different than the default npm package.
    CYPRESS_INSTALL_BINARY=2.0.1 npm install [email protected]
  • Specify an external URL (to bypass a corporate firewall).
    CYPRESS_INSTALL_BINARY=https://company.domain.com/cypress.zip npm install cypress
  • Specify a file to install locally instead of using the internet.
    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.

Skipping installation

You can also force Cypress to skip the installation of the binary application by setting CYPRESS_INSTALL_BINARY=0. This could be useful if you want to prevent Cypress from downloading the Cypress binary at the time of npm install.

CYPRESS_INSTALL_BINARY=0 npm install

Now Cypress will skip its install phase once the npm module is installed.

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. By default, global cache folders are:

  • MacOS: ~/Library/Caches/Cypress
  • Linux: ~/.cache/Cypress
  • Windows: /AppData/Local/Cypress/Cache

To override the default cache folder, set the environment variable CYPRESS_CACHE_FOLDER.

CYPRESS_CACHE_FOLDER=~/Desktop/cypress_cache npm install

CYPRESS_CACHE_FOLDER=~/Desktop/cypress_cache npm run test

See also Continuous Integration - Caching section in the documentation.

CYPRESS_CACHE_FOLDER will need to exist every time cypress is launched. To ensure this, consider exporting this environment variable. For example, in a .bash_profile (MacOS, Linux), or using RegEdit (Windows).

Run binary

Setting the environment variable CYPRESS_RUN_BINARY overrides where the npm module finds the Cypress binary.

CYPRESS_RUN_BINARY should be a path to an already unzipped binary executable. The Cypress commands open, run, and verify will then launch the provided binary.

Mac 

CYPRESS_RUN_BINARY=~/Downloads/Cypress.app/Contents/MacOS/Cypress cypress run

Linux 

CYPRESS_RUN_BINARY=~/Downloads/Cypress/Cypress cypress run

Windows 

CYPRESS_RUN_BINARY=~/Downloads/Cypress/Cypress.exe cypress run

We recommend not exporting the CYPRESS_RUN_BINARY environment variable, since it will affect every cypress module installed on your file system.

Download URLs

If you want to download a specific Cypress version for a given platform (Operating System), you can get it from our CDN.

The download server URL is https://download.cypress.io.

We currently have the following downloads available:

  • 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)

Here are the available download URLs:

See https://download.cypress.io/desktop.json for all available platforms.

Method URL Description
GET /desktop Download Cypress at latest 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

Example of downloading Cypress 3.0.0 for Windows 64-bit:

https://download.cypress.io/desktop/3.0.0?platform=win32&arch=x64

Mirroring

If you choose to mirror the entire Cypress download site, you can specify CYPRESS_DOWNLOAD_MIRROR to set the download server URL from https://download.cypress.io to your own mirror.

For example:

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

Cypress will then attempt to download a binary with this format: https://www.example.com/desktop/:version?platform=p

Opt out of sending exception data to Cypress

When an exception is thrown regarding Cypress, we send along the exception data to https://api.cypress.io. We solely use this information to help develop a better product.

If you would like to opt out of sending any exception data to Cypress, you can do so by setting CYPRESS_CRASH_REPORTS=0 in your system environment variables.

Opt out on Linux or macOS

To opt out of sending exception data on Linux or macOS, run the following command in a terminal before installing Cypress:

export CYPRESS_CRASH_REPORTS=0

To make these changes permanent, you can add this command to your shell’s ~/.profile (~/.zsh_profile, ~/.bash_profile, etc.) to run them on every login.

Opt out on Windows

To opt out of sending exception data on Windows, run the following command in the Command Prompt before installing Cypress:

set CYPRESS_CRASH_REPORTS=0

To accomplish the same thing in Powershell:

$env:CYPRESS_CRASH_REPORTS = "0"

To save the CYPRESS_CRASH_REPORTS variable for use in all new shells, use setx:

setx CYPRESS_CRASH_REPORTS 0

Install pre-release version

In very rare cases you might want to install the pre-release version of Cypress to verify a fix from the develop branch, that has not been published yet.

You can preview all issues addressed from a pre-release version here.

We build every commit in the develop branch for each platform and test it against downstream projects. For example, in the image below the last commit has the short SHA e5106d9.

Last commit on develop branch

The simplest way to find the pre-release version of the Test Runner matching this commit is to look at the commits made on our projects under test at cypress-test-example-repos. You will see individual commits for each built platform and architecture: darwin (Mac), linux, win 32bit and win 64bit. The built commit SHA e5106d9 is in the subject line of the test commit:

Test commit per platform

These pre-release builds are platform-specific. Choose the platform that matches your platform; for example if you are on a Mac, click on the commit “Testing new darwin x64 …”. This commit has a custom message that shows a special temporary URL of the built binary for Mac OS and the matching npm cypress package.

Beta binary information

To install this pre-release binary on Mac, you need to set the CYPRESS_INSTALL_BINARY environment variable to the shown https://cdn.cypress.io/beta/binary/.../cypress.zip value and run npm install https://cdn.cypress.io/beta/npm/3.3.2/.../cypress.tgz. The command in the terminal will be:

export CYPRESS_INSTALL_BINARY=https://cdn.cypress.io/beta/binary/3.3.2/darwin-x64/circle-develop-e5106d95f51eec477b8e66609939979fb87aab56-126014/cypress.zip

npm install https://cdn.cypress.io/beta/npm/3.3.2/circle-develop-e5106d95f51eec477b8e66609939979fb87aab56-126013/cypress.tgz

If my machine is Windows 64bit, I will click on the “Testing new win32 x64 …” commit and run the command below.

set CYPRESS_INSTALL_BINARY=https://cdn.cypress.io/beta/binary/3.3.2/win32-x64/appveyor-develop-e5106d95f51eec477b8e66609939979fb87aab56-25451270/cypress.zip

npm install https://cdn.cypress.io/beta/npm/3.3.2/appveyor-develop-e5106d95f51eec477b8e66609939979fb87aab56-25451270/cypress.tgz

On Linux CI you should install the binary from the “Testing new linux x64 …” commit.

export CYPRESS_INSTALL_BINARY=https://cdn.cypress.io/beta/binary/3.3.2/linux-x64/circle-develop-e5106d95f51eec477b8e66609939979fb87aab56-125973/cypress.zip

npm install https://cdn.cypress.io/beta/npm/3.3.2/circle-develop-e5106d95f51eec477b8e66609939979fb87aab56-125992/cypress.tgz

Pre-release binary URL format

The above CYPRESS_INSTALL_BINARY urls are temporary - they are purged after 30 days. The format of the url is as follows:

https://cdn.cypress.io/beta/binary/<version>/<platform>-<arch>/
<ci name>-<branch name>-<full commit SHA>-<CI build number>/cypress.zip

© 2017 Cypress.io
Licensed under the MIT License.
https://docs.cypress.io/guides/getting-started/installing-cypress.html