Non-working advanced installation example for mismatched binary

[MikeMcC399]

Subject

References > Advanced Installation > Install binary

Description

Issue

References > Advanced Installation > Install binary uses [email protected] and [email protected] as an example in the usage of the CYPRESS_INSTALL_BINARY environment variable.

Install a version different than the default npm package.
CYPRESS_INSTALL_BINARY=2.0.1 npm install [email protected]

1. Cypress 2.x are legacy versions released in 2018. These are not compatible with currently supported Ubuntu environments. Cypress 2.0.3 does not run on Ubuntu 20.04.06 LTS with Node.js 18.x (the lowest currently supported versions) and fails to start. See also Remove obsolete libgconf-2-4 from Ubuntu/Debian prerequisites #5528 which identified Cypress 3.4.1 as the last version to require the obsolete libgconf-2-4, so essentially Cypress 3.5.0 is the lowest version which can be used in any examples.

2. The use-case for installing a Cypress binary version which does not match the version of the Cypress npm module is unclear and not explained.

Suggestions

Remove

If there is no valid use-case for installing a Cypress binary version which does not match the version of the Cypress npm module, then remove the example.

Update

1. If there is a valid use-case for this installation option, then the use-case should be explained.
2. If the example is to remain in the documentation, then update to current non-legacy 13.x versions.

Test of update

Executing the following on Ubuntu 22.04 causes the Cypress binary 13.7.1 to be placed in the cache folder for 13.7.0.

CYPRESS_INSTALL_BINARY=13.7.1 npm install [email protected]

The cache folder created is ~/.cache/Cypress/13.7.0.

Running Cypress with npx cypress open results in a warning

$ npx cypress open
Found binary version 13.7.1 installed in: /home/mike/.cache/Cypress/13.7.0/Cypress

⚠ Warning: Binary version 13.7.1 does not match the expected package version 13.7.0

  These versions may not work properly together.

Judging by the warning, this is not something which should be done, making it questionable whether the example should remain in the documentation at all, even if the version is updated to a current non-legacy version.

[MikeMcC399]

I would favor removing the example and I'm looking for guidance here about what the best course of action is.

[jennifer-shehane]

@MikeMcC399 I can't remember what this use case was for adding the version functionality. It's been there for a long time. I think we should leave it documented and update the version numbers.

[MikeMcC399]

@jennifer-shehane

I can't remember what this use case was for adding the version functionality. It's been there for a long time. I think we should leave it documented and update the version numbers.

• I have followed your guidance and submitted PR Update example CYPRESS_INSTALL_BINARY #5779 to update the versions.