How to run Cypress on WSL2

Choked by corporate into keeping a windows machine or life is just nicer having low maintenance windows and Linux side by side? Either way, running a GUI based tool like Cypress could be a pain, so let’s solve it!

Photo by Johny vino on Unsplash

Cypress is a great tool for writing automated integration tests for web applications. It opens up a browser window and interacts with the application just as a user would, with all the native browser debug tools (such as chrome DevTools). With features like time-travel, screenshotting and screen recording, it is easy to find out why tests are failing and use them as an aide in writing tests.

But if you are here, you are probably already sold on Cypress! It’s fairly easy to set-up on a native windows, mac or Linux environment, but what if you are trying to run it on a windows subsystem for Linux? The docs are a bit hazy on that one.

The main barrier is running a GUI from WSL. So in this article, we will install an X-server and grant it permission to connect through Windows Defender firewall. We will take cypress as a use case here, but the following steps are useful for running any cli tool on WSL2 that requires a GUI. Future releases may have GUI support out of the box, but for now we need to work around it.

To get started, we will need to open a WSL2 shell and install the prerequisite packages.

apt-get install libgtk2.0-0 libgtk-3-0 libgbm-dev libnotify-dev libgconf-2-4 libnss3 libxss1 libasound2 libxtst6 xauth xvfb

We need to have an X-server to display GUI from the Linux subsystem. There are a variety of X-servers available, here we are going to use VcXsrv, you can use any other similar tool.

Download VcXsrv and install. You can set the settings to your preference (Multiple windows and Start no client is recommended), but on the page that lets you enable extra settings, disable access control. This is required as WSL2 has its own IP address, which changes often.

Extra settings for VcXsrv

In your .bashrc (or equivalent such as .zshrc) set the DISPLAY environment variable by adding the following command.

# set DISPLAY variable to the IP automatically assigned to WSL2
export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2; exit;}'):0.0

To confirm DISPLAY variable has been set, print it out in the terminal.

echo $DISPLAY
# something like 192.168.64.1:0.0

The VcXsrv GUI uses D-BUS to internally communicate. Under the previous line in .bashrc, add the following:

sudo /etc/init.d/dbus start &> /dev/null

Now linux user needs to be granted access to dbus without a password. To do so, use the visido command.

sudo visudo -f /etc/sudoers.d/dbus

In the editor that launches, add the following line with your username.
<your_username> ALL = (root) NOPASSWD: /etc/init.d/dbus

We are almost done! VcXsrv still needs permission to communicate through the Windows Defender Firewall, without which our cypress open command will hang and error out.

Go to Control Panel > System and Security > Windows Defender Firewall > Inbound Rules > New Rule.

Add rule to allow connection to VcXsrv

Select Program and click on next. On the This program path, browse and select path to VcxSrv. On the next page select allow the connection and click next. On the next page, select all three options (Domain, Private, Public).

Select inbound rule application cases for VcXsrv

Give the rule a suitable name and description and click finish. WSL2 should now be able to open a GUI from shell. To test it out, go to a repository with Cypress tests and run cypress open.

Voila, enjoy testing!