How to Install Cypress for End-to-End Testing: A Complete Setup Guide

You can install Cypress by running npm install cypress --save-dev, which automatically downloads the Electron binary via a post-install script, then verify with npx cypress verify.

Cypress is distributed as a single npm package that bundles both the CLI tooling and the pre-built Electron binary required to run tests. According to the cypress-io/cypress source code, the installation process relies on a post-install hook that detects your operating system and caches the appropriate binary. This guide walks through the exact commands and verification steps documented in the repository's README.md and cli/ workspace.

Installing Cypress via Package Managers

Cypress requires Node.js but no additional system dependencies. The package is published to the npm registry as cypress and includes the full test runner.

Install the package using your preferred package manager:

# npm

npm install cypress --save-dev

# Yarn 1 (used throughout the Cypress monorepo)

yarn add cypress --dev

# pnpm

pnpm add cypress --save-dev

The installation triggers a post-install script defined in the cli/ workspace. This script invokes the binary download logic located in packages/electron/install.ts, which fetches the Electron binary specific to your OS or reuses a cached version if available.

Verifying the Binary Installation

After the npm installation completes, verify that the Electron binary was downloaded correctly and is executable. Run the verification command:

npx cypress verify

This checks that the @packages/electron sub-package successfully placed the binary in the expected location. As documented in the repository's top-level README.md, this step ensures the Cypress Test Runner can launch without binary path errors.

Launching the Interactive Test Runner

Once verified, open the interactive Test Runner to begin writing tests:

npx cypress open

This command launches the Electron-based GUI where you can select browsers, view specs, and debug tests interactively. The CLI module handles browser detection and launching through the packages/launcher workspace.

Running Tests Headlessly

For continuous integration environments, run tests directly in the terminal without the GUI:

# Run all specs

npx cypress run

# Run a specific spec file

npx cypress run --spec "cypress/e2e/login.cy.ts"

# Record results to Cypress Cloud

npx cypress run --record --key <your-project-key>

The cypress run command executes tests in headless mode by default, making it suitable for CI/CD pipelines.

Summary

• Single package installation: Run npm install cypress --save-dev to add both the CLI and Electron binary to your project.
• Automatic binary download: The post-install script in packages/electron/install.ts handles OS-specific binary retrieval via the @packages/electron sub-package.
• Verification required: Use npx cypress verify to confirm the binary is present and executable before running tests.
• Two execution modes: Use npx cypress open for interactive development and npx cypress run for CI automation.

Frequently Asked Questions

How long does Cypress installation take?

Installation typically takes 30-60 seconds depending on your network speed, as the post-install script must download the Electron binary (approximately 150-200MB) after the npm package resolves. If you have previously installed Cypress, the script reuses the cached binary and completes in seconds.

Can I install Cypress without npm?

No, the primary distribution method for Cypress is through npm, yarn, or pnpm. The cypress package on the npm registry contains the CLI tools and triggers the binary download via the post-install hook. Direct binary downloads are not officially supported.

Where is the Cypress binary stored?

The Electron binary is cached in your system’s local cache directory after initial download. The packages/electron sub-package manages this location, typically storing it in ~/Library/Caches/Cypress on macOS, %APPDATA%\Cypress\Cache on Windows, or ~/.cache/Cypress on Linux, allowing reuse across projects.

What Node.js version is required for Cypress?

Cypress supports Node.js 18.x and above, though the specific version requirements are defined in the package.json of the cli/ workspace. The Electron binary itself does not depend on your system’s Node version, as it bundles its own runtime.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}