diff --git a/docs/app/get-started/install-cypress.mdx b/docs/app/get-started/install-cypress.mdx index d2634e5587..7957bb1cd6 100644 --- a/docs/app/get-started/install-cypress.mdx +++ b/docs/app/get-started/install-cypress.mdx @@ -1,101 +1,37 @@ --- title: 'Install using npm, Yarn, or pnpm | Cypress Documentation' -description: 'A step-by-step guide on how to install Cypress. Learn the requirements, installation process, and get started with Cypress for end-to-end and component testing' +description: 'The fastest way to get Cypress running. Check requirements, install it in your project, and start testing today.' sidebar_label: Install Cypress sidebar_position: 30 --- -# Install Cypress +# Installation :::info ##### What you'll learn - How to install Cypress using npm, Yarn, or pnpm -- System requirements for Cypress -- How to install Cypress using direct download +- What you need before installing - Advanced installation options ::: -# Installing Cypress +## Install & Run -First, make sure you meet the [system requirements](#System-requirements) including -[operating system](#Operating-System), -installation of [Node.js](#Nodejs) and -a supported [package manager](#Package-Manager). - -## Install - -Install Cypress via your preferred [package manager](#Package-Manager). -This will install Cypress locally as a dev dependency for your project. +1. **Check Requirements:** make sure you meet the [system requirements](#System-requirements) including + operating system, installation of Node.js and a supported package manager. +2. **Run in your project root:** This will install Cypress locally as a dev dependency for your project. -Before installing Cypress, ensure you have a `package.json` file in the root of your project. -If you need to create the file, -you can run the `init` command for your [package manager](#Package-Manager). - -System [proxy properties](/app/references/proxy-configuration) `http_proxy`, `https_proxy` and `no_proxy` are respected -for the download of the Cypress binary. -You can also use the npm properties -`npm_config_proxy` and `npm_config_https_proxy`. -Those have lower priority, so -they will only be used if the system properties are being resolved to not use a proxy. - -### Direct download - -The recommended approach is to install Cypress with `npm` because: - -- Cypress is versioned like any other dependency. -- It simplifies running Cypress in - [Continuous Integration](/app/continuous-integration/overview). - -If you're not using Node or a package manager in your project or you want to just try Cypress out -quickly, you can always -[download Cypress directly from our CDN](https://download.cypress.io/desktop). - -:::caution - -Recording runs to Cypress Cloud is not possible from the direct download. This -download is only intended as a quick way to try out Cypress. To record tests to -Cypress Cloud, you'll need to install Cypress as an package dependency. - -::: - -The direct download will always grab the latest available version. Your platform -will be detected automatically. - -Then you can manually unzip and double click. Cypress will run without needing -to install any dependencies. - -:::info - -Direct downloading for old versions - -It is possible to download an old version from our CDN by suffixing the URL with -the desired version (ex. -[https://download.cypress.io/desktop/12.17.4](https://download.cypress.io/desktop/12.17.4)). - -::: +3. **Open Cypress:** This launches the Cypress App so you can choose end-to-end (E2E) or component testing (CT) and start writing tests. -### Advanced Installation + -If you have more complex requirements, want to level-up your Cypress workflow or -just need help with troubleshooting, check out our -[Advanced Installation](/app/references/advanced-installation) reference. -You can also find instructions to [uninstall Cypress](/app/references/advanced-installation#Uninstall-Cypress) in this reference documentation. - -### Continuous integration - -Please read our -[Continuous Integration](/app/continuous-integration/overview) docs for -help installing Cypress in CI. When running in Linux you may need to install some -[system dependencies](#Linux-Prerequisites) -or you can use our [Docker images](#Docker-Prerequisites) which have everything you -need prebuilt. +4. **Write your first test:** Start with [E2E](/app/end-to-end-testing/writing-your-first-end-to-end-test) or [Component Testing](/app/component-testing/get-started). ## System requirements @@ -103,62 +39,47 @@ need prebuilt. Cypress supports running under these operating systems: -- **macOS** 11 and above _(Intel or Apple Silicon 64-bit (x64 or arm64))_ +- **macOS** >=11 _(Intel or Apple Silicon 64-bit (x64 or arm64))_ - **Linux** _(x64 or arm64)_ see also [Linux Prerequisites](#Linux-Prerequisites) down below - - Ubuntu 20.04 and above - - Debian 11 and above - - Fedora 41 and above -- **Windows** 10 and 11 _(x64)_ + - Ubuntu >=20.04 + - Debian >=11 + - Fedora >=41 +- **Windows** 10 & 11 _(x64)_ - **Windows** 11 24H2 _(arm64, runs in [x64 emulation](https://learn.microsoft.com/en-us/windows/arm/apps-on-arm-x86-emulation) mode, minimum Cypress [14.5.0](/app/references/changelog#14-5-0) required)_ - preview status - **Windows Server** 2019, 2022 and 2025 _(x64)_ ### Node.js -Cypress requires [Node.js](https://nodejs.org/) in order to install. We support the versions listed below: - -- **Node.js** 20.x, 22.x, 24.x and above - -Cypress generally aligns with -[Node's release schedule](https://github.com/nodejs/Release). - -#### Installing Node.js +- **Node.js** 20.x, 22.x, >=24.x Follow the instructions on [Download Node.js](https://nodejs.org/en/download/) to download and install [Node.js](https://nodejs.org/). -:::tip - -Best Practice - -Use a Node.js version manager as suggested on [Download Node.js](https://nodejs.org/en/download/) to install Node.js, -or use an alternate Node.js version manager of your choice. -This allows you to switch between different versions of Node.js easily. +:::caution Note that the [Node.js Snap for Linux](https://github.com/nodejs/snap) version manager is not recommended for use with Cypress. Attempting to use it as a non-root user may result in permissions errors. ::: -If you are using a [Cypress Docker image](../continuous-integration/overview#Cypress-Docker-variants), -you will find a fixed version of Node.js is pre-installed in the image. -You select the Node.js version using the Docker image tag. +If you're using a [Cypress Docker image](../continuous-integration/overview#Cypress-Docker-variants), you'll find a fixed version of Node.js is pre-installed in the image. You select the Node.js version using the Docker image tag. ### Package Manager -Cypress is [installed](#Install) using one of the following supported package managers: +Cypress is installed using one of the following supported package managers: -| Package Manager | Version | Installation instructions | -| ------------------------------------------------ | ------------------- | --------------------------------------------------------------------------------------------------------------- | -| [npm](https://docs.npmjs.com/) | `10.1.0` and above | [Downloading and installing Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) | -| [Yarn 1 (Classic)](https://classic.yarnpkg.com/) | `1.22.22` and above | [Yarn 1 (Classic) Installation](https://classic.yarnpkg.com/en/docs/install) | -| [Yarn (Modern aka berry)](https://yarnpkg.com/) | `4.x` and above | [Yarn Installation](https://yarnpkg.com/getting-started/install) | -| [pnpm](https://pnpm.io/) | `8.x` and above | [pnpm Installation](https://pnpm.io/installation) | +| Manager | Version | Docs | +| ------------------------------------------------ | --------- | -------------------------------------------------------------------------------- | +| [npm](https://docs.npmjs.com/) | >=10.1.0 | [Install npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) | +| [Yarn 1 (Classic)](https://classic.yarnpkg.com/) | >=1.22.22 | [Install Yarn Classic](https://classic.yarnpkg.com/en/docs/install) | +| [Yarn (Modern aka berry)](https://yarnpkg.com/) | >=4.x | [Install Yarn Modern](https://yarnpkg.com/getting-started/install) | +| [pnpm](https://pnpm.io/) | >=8.x | [Install pnpm](https://pnpm.io/installation) | -#### Yarn Configuration +#### Yarn users [Yarn (Modern)](https://yarnpkg.com/) configuration using [nodeLinker: "node-modules"](https://yarnpkg.com/configuration/yarnrc#nodeLinker) is preferred. Cypress [Component Testing](/app/core-concepts/testing-types#What-is-Component-Testing) is not currently compatible with the default setting [nodeLinker: "pnp"](https://yarnpkg.com/configuration/yarnrc#nodeLinker) which uses [Yarn Plug'n'Play](https://yarnpkg.com/features/pnp). -#### pnpm Configuration +#### pnpm configuration The following configuration options enable Cypress to execute its `postinstall` script so it can install the Cypress binary into the [binary cache](/app/references/advanced-installation#Binary-cache). If these configuration options are not set, then Cypress may skip the `postinstall` script execution and Cypress will not run. @@ -186,51 +107,23 @@ The latest 3 major versions of the following browsers are also supported: - [Google Chrome](/app/references/launching-browsers#Chrome-Browsers) - [Microsoft Edge](/app/references/launching-browsers#Edge-Browsers) -- [Mozilla Firefox](/app/references/launching-browsers#Firefox-Browsers) (_release Firefox [141.0](https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Releases/141) and above requires a minimum Cypress [14.1.0](https://docs.cypress.io/app/references/changelog#14-1-0)_) - -Additionally: - -- [WebKit](https://docs.cypress.io/app/references/launching-browsers#WebKit-Experimental) is experimentally supported +- [Mozilla Firefox](/app/references/launching-browsers#Firefox-Browsers) (_Firefox >=[141.0](https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Releases/141) requires Cypress >=[14.1.0](https://docs.cypress.io/app/references/changelog#14-1-0)_) +- [WebKit](https://docs.cypress.io/app/references/launching-browsers#WebKit-Experimental) support is experimental ### Hardware -When running Cypress locally, it should run comfortably on any machine that is -capable of modern web development. +- Local: Any modern dev machine works +- CI: At least 2 CPUs + 4 GB RAM (8 GB+ recommended for long runs or video recording) -When running Cypress in CI, however, some of the lower-tier configurations might -not be able to run Cypress reliably, especially when recording videos or doing -longer test runs. +Some issues you might run into in CI that could be a sign of insufficient resources are: -Some issues you might run into in CI that could be a sign of insufficient -resources are: - -- Exiting early during `cypress run` or abruptly closing (“crashing”) -- Frozen or missing frames in the video that is captured +- Exiting early during `cypress run` or abruptly closing ("crashing") +- Frozen or missing frames in the video - Increased runtime -When running Cypress in CI, we recommend that you have the following hardware -requirements: - -#### 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 - ### Linux Prerequisites -If you're using Linux, you'll want to have the required dependencies installed -on your system. Depending on your system defaults, these dependencies may already be installed. -If not, run the command line for your operating system listed below. -See below under [Docker Prerequisites](#Docker-Prerequisites) for information on [Cypress Docker images](https://github.com/cypress-io/cypress-docker-images). These already include the necessary dependencies. +Install required dependencies. See below under [Docker Prerequisites](#Docker-Prerequisites) for information on [Cypress Docker images](https://github.com/cypress-io/cypress-docker-images). These already include the necessary dependencies. #### Ubuntu/Debian @@ -240,7 +133,7 @@ For Ubuntu 22.04 and below, and Debian: apt-get install libgtk2.0-0 libgtk-3-0 libgbm-dev libnotify-dev libnss3 libxss1 libasound2 libxtst6 xauth xvfb ``` -For Ubuntu 24.04+ and optionally for Debian 13: +For Ubuntu >=24.04 and optionally for Debian 13: ```shell apt-get install libgtk2.0-0t64 libgtk-3-0t64 libgbm-dev libnotify-dev libnss3 libxss1 libasound2t64 libxtst6 xauth xvfb @@ -273,6 +166,22 @@ If you are not using a Cypress Docker image, make sure that your base operating [Operating Systems](#Operating-System) above and that Node.js is installed in the image. It is recommended to have `unzip` installed. This avoids the Cypress binary installation falling back to a slower unzip method using Node.js. +## Advanced Installation + +If you have more complex requirements, want to level-up your Cypress workflow or +just need help with troubleshooting, check out our +[Advanced Installation](/app/references/advanced-installation) reference. +You can also find instructions to [uninstall Cypress](/app/references/advanced-installation#Uninstall-Cypress) in this reference documentation. + +## Continuous integration + +Please read our +[Continuous Integration](/app/continuous-integration/overview) docs for +help installing Cypress in CI. When running in Linux you may need to install some +[system dependencies](#Linux-Prerequisites) +or you can use our [Docker images](#Docker-Prerequisites) which have everything you +need prebuilt. + ## Next Steps [Open the app](/app/get-started/open-the-app) and take it for a test drive! diff --git a/docs/app/references/advanced-installation.mdx b/docs/app/references/advanced-installation.mdx index 319abd8a76..a1af89407c 100644 --- a/docs/app/references/advanced-installation.mdx +++ b/docs/app/references/advanced-installation.mdx @@ -35,6 +35,15 @@ sidebar_label: 'Advanced Installation' | ~~CYPRESS_SKIP_BINARY_INSTALL~~ | removed use `CYPRESS_INSTALL_BINARY=0` instead | | ~~CYPRESS_BINARY_VERSION~~ | removed use `CYPRESS_INSTALL_BINARY` instead | +## Proxy configuration + +System [proxy properties](/app/references/proxy-configuration) `http_proxy`, `https_proxy` and `no_proxy` are respected +for the download of the Cypress binary. +You can also use the npm properties +`npm_config_proxy` and `npm_config_https_proxy`. +Those have lower priority, so +they will only be used if the system properties are being resolved to not use a proxy. + ## Install binary Using the `CYPRESS_INSTALL_BINARY` environment variable, you can control how diff --git a/docs/app/references/changelog.mdx b/docs/app/references/changelog.mdx index 9392c1a03e..46890187b3 100644 --- a/docs/app/references/changelog.mdx +++ b/docs/app/references/changelog.mdx @@ -12,7 +12,6 @@ sidebar_label: Changelog _Released 7/29/2025 (PENDING)_ - ## 14.5.4 _Released 8/07/2025_ diff --git a/docs/app/references/error-messages.mdx b/docs/app/references/error-messages.mdx index 32ba417580..e92d3b5380 100644 --- a/docs/app/references/error-messages.mdx +++ b/docs/app/references/error-messages.mdx @@ -669,7 +669,7 @@ The Cypress binary is downloaded and installed into a [global cache folder](/app with a package manager install command (such as `npm ci`, `npm install`, `yarn install` or `pnpm install`). The Cypress cache can also be loaded from a CI cache that was saved from a previous CI run. -If you are using pnpm, ensure you are following the [pnpm configuration](/app/get-started/install-cypress#pnpm-Configuration) +If you are using pnpm, ensure you are following the [pnpm configuration](/app/get-started/install-cypress#pnpm-configuration) instructions, otherwise pnpm may skip the Cypress binary installation. If you are using CI caches, then review also the recommendations for