Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rework CYPRESS_RUN_BINARY instructions #6024

Merged
merged 1 commit into from
Dec 2, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 33 additions & 9 deletions docs/app/references/advanced-installation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -186,32 +186,56 @@ ensure this, consider exporting this environment variable. For example, in a
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.
`CYPRESS_RUN_BINARY` should be a path to an already unzipped Cypress binary executable.
The Cypress commands [open](./command-line#cypress-open), [run](./command-line#cypress-run) and [verify](command-line#cypress-verify)
will then launch the provided binary.

The following example [cypress run](./command-line#cypress-run) commands assume that you have first
downloaded the Cypress binary to the default `Downloads` directory of your operating system.

Depending on how you then unzip the downloaded Cypress binary `cypress.zip` file,
using a CLI command or alternatively a GUI interface,
the directory structure may include one additional top-level directory named `cypress`,
which you may need to add to the path defined by `CYPRESS_RUN_BINARY`.

If available, use the following to avoid the additional top-level directory level:

```shell
unzip -q cypress
```

:::note

The examples below are for npm.
If you are using Yarn or pnpm as package manager, replace `npx` with `yarn` or `pnpm` as appropriate.
See [How to run commands](./command-line.mdx#How-to-run-commands).

:::

### Mac

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

### Linux

```shell
CYPRESS_RUN_BINARY=~/Downloads/Cypress/Cypress cypress run
CYPRESS_RUN_BINARY=~/Downloads/Cypress/Cypress npx cypress run
```

### Windows

```shell
CYPRESS_RUN_BINARY=~/Downloads/Cypress/Cypress.exe cypress run
CYPRESS_RUN_BINARY=~/Downloads/Cypress/Cypress.exe npx cypress run
```

:::caution
:::tip

We recommend **not exporting** the `CYPRESS_RUN_BINARY` environment variable,
since it will affect every cypress module installed on your file system.
Cypress assumes that `CYPRESS_RUN_BINARY` points to a writeable directory structure so that it can save and re-use
the results of verifying the Cypress binary.
If you encounter a `permission denied` failure message from [cypress verify](./command-line.mdx#cypress-verify),
you may be able to work around the failure by setting the environment variable `CYPRESS_SKIP_VERIFY` to `true`.

:::

Expand Down