Raised: $0
0% of monthly goal Help us cross the finish line!
Goal: $12,000
Raised: $0 Goal: $12,000
0% of monthly goal Help us cross the finish line!
Sponsor DDEV

add-on registry tests last commit release

DDEV-cypress

Introduction

Cypress is a “complete end-to-end testing experience”. It allows you to write JavaScript test files that automate real browsers. For more details, see the Cypress Overview page.

This recipe integrates a Cypress docker image with your DDEV project.

The main benefit is integration of Chrome and Firefox browsers out of the box, providing a known static state regardless of local OS or cloud CI/CS development. It also provides X11 display support for MacOS and Windows users, whereas this usually just works in Linux.

This addon:

Installing Cypress with favorite package manager works great locally. However, maintaining a consistent node and browser environments across teams, operating systems, CI/CS development pipelines and cloud development spaces can become a challenge.

Browser testing using Cypress sets up Cypress for Drupal manually. For Linux users this could be easier, since X11 and Firefox are usually already present.

Requirements

Steps

Note

If you change additional_hostnames or additional_fqdns, you have to re-run ddev add-on get ddev/ddev-cypress

We recommend running ddev cypress-open first to create configuration and support files. This addon sets CYPRESS_baseUrl to DDEV’s primary URL in the docker-compose.cypress.yaml.

Configure DISPLAY

To display the Cypress screen and browser output, you must configure a DISPLAY environment variable.

macOS

ddev Cypress Setup (Mac)

# Install XQuartz
brew install xquartz --cask

# Run XQuartz
open -a Xquartz

In the XQuartz preferences, go to the “Security” tab and make sure the “Allow connections from network clients” checkbox is checked.

Now restart your Mac. XQuartz will not properly be set to listen for X11 connections until you do this.

# Run the below command
xhost + 127.0.0.1

Add a file called docker-compose.cypress_extra.yaml with the following content to the .ddev directory:

services:
  cypress:
    environment:
      - DISPLAY=host.docker.internal:0

Linux

You may need to set up access control for the X server for this to work. Install the xhost package (one is available for all distros) and run:

export DISPLAY=:0
xhost +

Windows 10

If you are running DDEV on Win10 or WSL2, you need to configure a display server on Win10. You are free to use any X11-compatible server. A configuration-free solution is to install GWSL via the Windows Store.

Running DDEV on Win10 (not WSL)
❯ ipconfig

Windows IP Configuration


Ethernet adapter Ethernet:

   Connection-specific DNS Suffix  . :
   IPv4 Address. . . . . . . . . . . : 192.168.0.196
   Subnet Mask . . . . . . . . . . . : 255.255.255.0
   Default Gateway . . . . . . . . . : 192.168.0.1
    environment:
      - DISPLAY=192.168.0.196:0

A note about the Cypress image

This recipe uses the latest cypress/include image which includes the following browsers:

Best practice encourages using a specific image tag.

Commands

Cypress can run into 2 different modes: interactive and runner. This recipe includes 2 alias commands to help you use Cypress.

To see Cypress in interactive mode, Cypress forward XVFB messages out of the Cypress container into an X11 server running on the host machine. Each OS has different options. Developers have reported success with the following:

cypress-open

To open cypress in “interactive” mode, run the following command:

ddev cypress-open

See “#cypress open” documentation for a full list of available arguments.

Example: To open Cypress in interactive mode, and specify a config file

ddev cypress-open --config cypress.json

cypress-run

To run Cypress in “runner” mode, run the following command:

ddev cypress-run

See #cypress run for a full list of available arguments.

Example: To run all Cypress tests, using Chrome in headless mode

ddev cypress-run --browser chrome

Notes

Troubleshooting

“Could not find a Cypress configuration file, exiting”

Cypress expects a directory structures containing the tests, plugins and support files.

“Unable to open X display.”

Contributed by @tyler36