cypress-documentation

cypress-documentation copied to clipboard

Subject

References > Advanced Installation > Windows Subsystem for Linux

Description

The section Windows Subsystem for Linux describes how to install WSL to display the Cypress UI.

Users who report problems to the Cypress issues list under WSL or WSL2 are however being told that this configuration is not supported (for instance https://github.com/cypress-io/cypress/issues/27858#issuecomment-1729598898).

Suggestion

• If this configuration is not supported, then the details under References > Advanced Installation > Windows Subsystem for Linux should be completely removed and replaced with a corresponding statement. This is an action which needs to come from the core team, not from the community.

• If at some later time it is decided that Cypress can support WSL, then consideration should be given to issue https://github.com/cypress-io/cypress-documentation/issues/5353 which points out that the details to install and use a VcXsrv X11 server are outdated and unnecessary, since WSL2 now includes its own WSLg X11 server by default.

Depending on the reasons for not supporting WSL perhaps something along the lines of the following suggestions could be published?

Option 1 - WSL does not work correctly

We advise against the use of Cypress with Microsoft Windows Subsystem for Linux due to known issues in this environment and for this reason it is not supported.

Then remove all other WSL technical content.

Option 2 - WSL works but is not tested

Users have reported success with Cypress running under the Windows Subsystem for Linux (WSL) virtual environment however we do not test releases of Cypress for compatibility with WSL and for this reason we do not provide support for it. Other Cypress users in the Discord Technical Community may be able to help if you encounter any issues with Cypress running under WSL. If you believe you have found a bug in Cypress operating in a WSL environment and you wish to report it, please ensure that the issue is reproducible without using WSL on one of the Cypress supported operating systems.

For your convenience here are links to Microsoft documentation:

• Windows Subsystem for Linux (WSL)
• Run Linux GUI apps on the Windows Subsystem for Linux
• GitHub: Windows Subsystem for Linux GUI (WSLg)

The combination of WSL2 with WSLg as X11 server is currently the latest and recommended WSL environment for Cypress based on user feedback.

Replacing all other WSL technical content by the above links to Microsoft documentation.

• PR #5756 proposes a simple info section which says:

Cypress.io does not specifically support the use of Cypress under Windows Subsystem for Linux (WSL). If you want to report an issue, please ensure that you can reproduce it without using WSL on one of the Cypress supported operating systems.

This needs to be confirmed by the Cypress.io team.