n3amil / ddev-cypress

Cypress E2E testing for use with ddev

DDEV-cypress

• Introduction
• Requirements
• Steps
  • Configure DISPLAY
    • Windows 10
      • Running DDEV on Win10 (not WSL)
  • A note about the Cypress image
• Commands
  • cypress-open
  • cypress-run
• Notes
• Troubleshooting
  • "Could not find a Cypress configuration file, exiting"
  • "Unable to open X display."
• TODO

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.

Requirements

• DDEV >= 1.19
• Windows or Linux

NOTE: This uses cypress/include which does not have arm64 images and therefore does not support M1 Macs.

Steps

• Install service

  ddev get tyler36/ddev-cypress
  ddev restart

• Add a ./cypress.json cypress configuration. Note: DDEV automatically sets the "BaseURL" via the image environmental variables. The baseURL setting below will be ignored.

{
    "baseURL": "https://ddev-cypress-demo.ddev.site",
    "integrationFolder": "./tests/E2E",
}

• Run cypress via cypress run (headless) or cypress open.

Configure DISPLAY

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

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)

• Install GWSL via the Windows Store
• Get you "IPv4 Address" for your "Ethernet adapter" via networking panel or by typing ipconfig in a terminal. The address in the below example is 192.168.0.196

❯ 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

• In your project ./docker-compose.cypress.yaml, add the IPv4 address and :0 (EG. 192.168.0.196:0 ) to the display section under environment.

    environment:
      - DISPLAY=192.168.0.196:0

A note about the Cypress image

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

• Chrome
• Firefox
• Electron

It is considered best practice to use a specific image tag.

• If you require a specific browser, update image in your ./.ddev/docker-compose.cypress.yaml.
• Available images and versions can be found on the cypress-docker-images page.

Commands

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

cypress-open

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

ddev cypress-open

This command also accepts arguments. Refer to the "#cyress open" documentation for further details.

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

This command also accepts arguments. Refer to #cypress run page for a full list of available arguments.

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

ddev cypress-run --browser chrome

Notes

• The dockerized Cypress should find any locally installed plugins in your project's node_modules; assuming they are install via npm or yarn.
• Some plugins may require additional settings, such as environmental variables. These can be passed through via command arguments.

Troubleshooting

"Could not find a Cypress configuration file, exiting"

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

• If the ./cypress directory does not exist, it will scaffold out these directories, including a default cypress.json setting file and example tests when you first run ddev cypress-open.
• Make sure you have a cypress.json file in your project root, or use --config [file] argument to specify one.

"Unable to open X display."

• This recipe forwards the Cypress GUI via an X11 / X410 server. Please ensure you have this working on your host system.
• For Windows 10 users, try GWSL (via Microsoft store), or VcXsrv (via chocolatey)

TODO

• Add arm64 / mac solution
• Add steps for intergrating into Github Actions

Contributed by @tyler36