diff --git a/source/guides/getting-started/installing-cypress.md b/source/guides/getting-started/installing-cypress.md index 8bf36ced82..437753831a 100644 --- a/source/guides/getting-started/installing-cypress.md +++ b/source/guides/getting-started/installing-cypress.md @@ -108,3 +108,28 @@ By installing Cypress through `npm` you also get access to many other CLI comman As of version `0.20.0` Cypress is also a fully baked `node_module` you can require in your node scripts. You can {% url 'read more about the CLI here' command-line %}. + +# Advanced installation + +If the normal `npm install cypress` command does not work for some reason (like a corporate proxy not allowing downloading the Cypress binary from the `https://cdn.cypress.io` server), you still have a workaround. The installer can override the version and/or path of the binary to download via the `CYPRESS_BINARY_VERSION` environment variable. You have three choices: + +1. Install a different binary version from the {% url "`cypress` npm package" https://www.npmjs.com/package/cypress %} version. For example, to install the `cypress` npm package version `1.0.3` with the binary `1.0.1` version use this command: + + ```shell + CYPRESS_BINARY_VERSION=1.0.1 npm install cypress@1.0.3 + ``` + +2. Install the Cypress binary from the given URL. For example, you can download the Cypress binary from our CDN server `https://download.cypress.io/desktop` and place it on our company's server. Then use the following command: + + ```shell + CYPRESS_BINARY_VERSION=https://company.domain.com/cypress.zip npm install cypress + ``` + +3. Download the Cypress binary zip file and install it from a local file. In the example below, we download the version `1.0.2` of the binary for the Mac OS and save it as a local file `cypress.zip`. Then we install the latest `cypress` npm package version and the downloaded zip file. + + ```shell + curl -O https://cdn.cypress.io/desktop/1.0.2/osx64/cypress.zip + CYPRESS_BINARY_VERSION=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 would have to use the same environment variable to install the same binary. diff --git a/source/guides/guides/continuous-integration.md b/source/guides/guides/continuous-integration.md index 3be27000a1..39ca8de49b 100644 --- a/source/guides/guides/continuous-integration.md +++ b/source/guides/guides/continuous-integration.md @@ -143,6 +143,8 @@ You can set any configuration value as an environment variable. This overrides v - `CYPRESS_BASE_URL` - `CYPRESS_VIDEO_COMPRESSION` - `CYPRESS_REPORTER` +- `CYPRESS_VERSION` +- `CYPRESS_BINARY_VERSION` {% note info %} Refer to the {% url 'configuration' configuration#Environment-Variables %} for more examples. diff --git a/source/guides/references/changelog.md b/source/guides/references/changelog.md index a8eae713f9..f44dec6d13 100644 --- a/source/guides/references/changelog.md +++ b/source/guides/references/changelog.md @@ -25,6 +25,7 @@ comments: false - Cypress binaries can now be pointed to a staging environment with `CYPRESS_ENV=staging`. Fixes {% issue 813 %}. - The Desktop GUI displays the scrollbar correctly when the update banner is displayed. Fixes {% issue 803 %}. - The branch name is now properly collected when recording in Buildkite CI. Fixes {% issue 777 %}. +- You can install the Cypress binary from any URL or file path using the {% url "`CYPRESS_BINARY_VERSION` environment variable" installing-cypress#Advanced-installation %}. Closes {% issue 701 %}. **Documentation Changes:**