.github/workflows/tests.yml

@@ -14,69 +14,23 @@ on:
         required: false
         default: "false"
 
-defaults:
-  run:
-    shell: bash
-
-env:
-  NIGHTLY_DDEV_PR_URL: "https://nightly.link/drud/ddev/actions/runs/1720215802/ddev-linux-amd64.zip"
+permissions:
+  actions: write
 
 jobs:
   tests:
-    defaults:
-      run:
-        shell: bash
-
     strategy:
       matrix:
         ddev_version: [stable, HEAD]
-#        ddev_version: [PR]
       fail-fast: false
 
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v2
-    - name: Environment setup
-      run: |
-        brew install bats-core mkcert
-        brew tap bats-core/bats-core
-        brew install bats-support bats-assert bats-file
-        mkcert -install
-
-    - name: Use ddev stable
-      if: matrix.ddev_version == 'stable'
-      run: brew install drud/ddev/ddev
-
-    - name: Use ddev edge
-      if: matrix.ddev_version == 'edge'
-      run: brew install drud/ddev-edge/ddev
-
-    - name: Use ddev HEAD
-      if: matrix.ddev_version == 'HEAD'
-      run: brew install --HEAD drud/ddev/ddev
-
-    - name: Use ddev PR
-      if: matrix.ddev_version == 'PR'
-      run: |
-        curl -sSL -o ddev_linux.zip ${NIGHTLY_DDEV_PR_URL}
-        unzip ddev_linux.zip
-        mv ddev /usr/local/bin/ddev && chmod +x /usr/local/bin/ddev
-
-    - name: Download docker images
-      run: |
-        mkdir junk && pushd junk && ddev config --auto && ddev debug download-images >/dev/null
-        docker pull memcached:1.6 >/dev/null
-    - name: tmate debugging session
-      uses: mxschmitt/action-tmate@v3
+    - uses: ddev/github-action-add-on-test@v2
       with:
-        limit-access-to-actor: true
-        github-token: ${{ secrets.GITHUB_TOKEN }}
-      if: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.debug_enabled }}
-
-    - name: tests
-      run: bats tests
-
-    # keepalive-workflow adds a dummy commit if there's no other action here, keeps
-    # GitHub from turning off tests after 60 days
-    - uses: gautamkrishnar/keepalive-workflow@v1
+        ddev_version: ${{ matrix.ddev_version }}
+        token: ${{ secrets.GITHUB_TOKEN }}
+        debug_enabled: ${{ github.event.inputs.debug_enabled }}
+        addon_repository: ${{ env.GITHUB_REPOSITORY }}
+        addon_ref: ${{ env.GITHUB_REF }}

README.md

@@ -1,9 +1,12 @@
 # DDEV-cypress <!-- omit in toc -->
 
+[![tests](https://github.com/tyler36/ddev-cypress/actions/workflows/tests.yml/badge.svg)](https://github.com/tyler36/ddev-cypress/actions/workflows/tests.yml) ![project is maintained](https://img.shields.io/maintenance/yes/2026.svg)
 - [Introduction](#introduction)
 - [Requirements](#requirements)
 - [Steps](#steps)
   - [Configure `DISPLAY`](#configure-display)
+    - [macOS](#macos)
+    - [Linux](#linux)
     - [Windows 10](#windows-10)
       - [Running DDEV on Win10 (not WSL)](#running-ddev-on-win10-not-wsl)
   - [A note about the Cypress image](#a-note-about-the-cypress-image)
@@ -14,44 +17,104 @@
 - [Troubleshooting](#troubleshooting)
   - ["Could not find a Cypress configuration file, exiting"](#could-not-find-a-cypress-configuration-file-exiting)
   - ["Unable to open X display."](#unable-to-open-x-display)
-- [TODO](#todo)
 
 ## Introduction
 
-[Cypress](https://www.cypress.io/) 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](https://docs.cypress.io/guides/overview/why-cypress) page.
+[Cypress](https://www.cypress.io/) 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](https://docs.cypress.io/guides/overview/why-cypress) 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:
+- provides Cypress without the need to install <a href="https://nodejs.org">Node.js</a>
+- provides Firefox and Chromium out of the box, preconfigured for Cypress
+- configures your project's HTTPS site a base URL
+- provides helper commands for running Cypress GUI or in headless mode
+
+Installing Cypress with favorite package manager works great locally. However, maintaining a consistent node and browser environments across teams, operating systrems, CI/CS development pipelines and cloud development spaces can become a challenge.
+
+<a href="https://www.drupal.org/docs/develop/automated-testing/browser-testing-using-cypress">Browser testing using Cypress</a> sets up Cypress for Drupal manually. For Linux users this could be easier, since X11 and Firefox are usually already present.
+
 ## Requirements
 
 - DDEV >= 1.19
-- Windows or Linux
-
-NOTE: This uses [cypress/include](https://hub.docker.com/r/cypress/included) which does not have arm64 images and therefore does **not** support M1 Macs.
+- Modern OS
+  - MacOS 10.9 and above (Intel or Apple Silicon 64-bit (x64 or arm64))
+  - Linux Ubuntu 12.04 and above, Fedora 21 and Debian 8 (x86_64 or Arm 64-bit (x64 or arm64))
+  - Windows 7 and above (64-bit)
+- Interactive mode requires a X11 server running on the host machine.
 
 ## Steps
 
 - Install service
 
+  For DDEV v1.23.5 or above run
+
+  ```shell
+  ddev add-on get tyler36/ddev-cypress
+  ```
+
+  For earlier versions of DDEV run
+
   ```shell
   ddev get tyler36/ddev-cypress
+  ```
+
+  Then restart the project
+
+  ```shell
   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.
+> [!NOTE]
+> If you change `additional_hostnames` or `additional_fqdns`, you have to re-run `ddev add-on get tyler36/ddev-cypress`
 
-```json
-{
-    "baseURL": "https://ddev-cypress-demo.ddev.site",
-    "integrationFolder": "./tests/E2E",
-}
-```
+- Run cypress via `ddev cypress-open` or `ddev cypress-run` (headless).
 
-- Run cypress via `cypress run` (headless) or `cypress open`.
+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 correctly display the Cypress screen and browser output, you must configure a `DISPLAY` environment variable.
+To display the Cypress screen and browser output, you must configure a `DISPLAY` environment variable.
+
+#### macOS
+
+ddev Cypress Setup (Mac)
+
+```bash
+# 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.
+
+```bash
+# 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: 
+
+```yaml
+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:
+
+```sh
+export DISPLAY=:0
+xhost +
+```
 
 #### Windows 10
 
@@ -77,7 +140,7 @@ Ethernet adapter Ethernet:
    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.
+- In your project `./docker-compose.cypress.yaml`, add the IPv4 address and `:0` (For example `192.168.0.196:0` ) to the display section under environment.
 
 ```yaml
     environment:
@@ -86,22 +149,30 @@ Ethernet adapter Ethernet:
 
 ### A note about the Cypress image
 
-This recipe uses the latest `cypress/include` image (`cypress/include:10.2.0`) which includes the following browsers:
+This recipe uses the latest `cypress/include` image which includes the following browsers:
 
 - Chrome
 - Firefox
 - Electron
 
-It is considered best practice to use a [specific image tag](https://github.com/cypress-io/cypress-docker-images#best-practice).
+Best practice encourages using a [specific image tag](https://github.com/cypress-io/cypress-docker-images#best-practice).
 
 - 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](https://github.com/cypress-io/cypress-docker-images) page.
+- Available images and versions are available on the [cypress-docker-images](https://github.com/cypress-io/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.
 
+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:
+
+- Windows 10 / WSL users:
+  - [GWSL](https://opticos.github.io/gwsl/tutorials/manual.html) (via [Microsoft store](ms-windows-store://pdp/?productid=9NL6KD1H33V3))
+  - [VcXsrv](https://sourceforge.net/projects/vcxsrv/) (via [chocolatey](https://community.chocolatey.org/packages/vcxsrv#versionhistory)).
+- Mac users:
+  - [XQuartz](https://www.xquartz.org/). See [Running GUI applications using Docker for Mac](https://sourabhbajaj.com/blog/2017/02/07/gui-applications-docker-mac/).
+
 ### `cypress-open`
 
 To open cypress in "interactive" mode, run the following command:
@@ -110,7 +181,7 @@ To open cypress in "interactive" mode, run the following command:
 ddev cypress-open
 ```
 
-This command also accepts arguments. Refer to the ["#cyress open" documentation](https://docs.cypress.io/guides/guides/command-line#cypress-open) for further details.
+See ["#cypress open" documentation](https://docs.cypress.io/guides/guides/command-line#cypress-open) for a full list of available arguments.
 
 Example: To open Cypress in interactive mode, and specify a config file
 
@@ -126,7 +197,7 @@ To run Cypress in "runner" mode, run the following command:
 ddev cypress-run
 ```
 
-This command also accepts arguments. Refer to [#cypress run](https://docs.cypress.io/guides/guides/command-line#cypress-run) page for a full list of available arguments.
+See [#cypress run](https://docs.cypress.io/guides/guides/command-line#cypress-run) for a full list of available arguments.
 
 Example: To run all Cypress tests, using Chrome in headless mode
 
@@ -137,25 +208,19 @@ 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.
+- Some plugins may require specific settings, such as environmental variables. Pass them 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.
+Cypress expects a directory structures 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](https://opticos.github.io/gwsl/tutorials/manual.html) (via [Microsoft store](ms-windows-store://pdp/?productid=9NL6KD1H33V3)), or [VcXsrv](https://sourceforge.net/projects/vcxsrv/) (via [chocolatey](https://community.chocolatey.org/packages/vcxsrv#versionhistory))
-
-## TODO
-
-- [ ] Add arm64 / mac solution
-- [ ] Add steps for intergrating into Github Actions
 
 **Contributed by [@tyler36](https://github.com/tyler36)**

docker-compose.cypress.yaml

@@ -1,8 +1,7 @@
 #ddev-generated
-version: '3.6'
 services:
   cypress:
-    image: cypress/included:10.2.0
+    image: cypress/included:13.17.0
     container_name: ddev-${DDEV_SITENAME}-cypress
     labels:
       com.ddev.site-name: ${DDEV_SITENAME}
@@ -15,16 +14,15 @@ services:
     environment:
       - CYPRESS_baseUrl=${DDEV_PRIMARY_URL}
       - DISPLAY
+      - HOME=/root
 
     volumes:
       # Mount the project root to Cypress's project point
       - "${DDEV_APPROOT}:/e2e"
       # Mount DDEV to allow commands
       - ".:/mnt/ddev_config"
-
-    external_links:
-      # Resolve links via DDEV router
-      - "ddev-router:${DDEV_HOSTNAME}"
+      # Allow X11 forwarding
+      - /tmp/.X11-unix:/tmp/.X11-unix
 
     entrypoint: /bin/bash
     working_dir: /e2e

install.yaml

@@ -4,12 +4,7 @@ name: ddev-cypress
 # Examples would be removing an extraneous docker volume,
 # or doing a sanity check for requirements.
 pre_install_actions:
-- |
-  #ddev-nodisplay
-  if [ "$(arch)" = "arm64" -o "$(arch)" = "aarch64" ]; then 
-    echo "This package does not work on arm64 machines"; 
-    exit 1; 
-  fi
+
 
 # list of files and directories listed that are copied into project .ddev directory
 project_files:
@@ -22,3 +17,35 @@ global_files:
 
 
 post_install_actions:
+  - |
+    #ddev-nodisplay
+    #ddev-description:Checking docker-compose.cypress_extras.yaml for changes
+    if [ -f docker-compose.cypress_extras.yaml ] && ! grep -q '#ddev-generated' docker-compose.cypress_extras.yaml; then
+      echo "Existing docker-compose.cypress_extras.yaml does not have #ddev-generated, so can't be updated"
+      exit 2
+    fi
+  - |
+    #ddev-nodisplay
+    #ddev-description:Adding all hostnames to the cypress container to make them available
+    cat <<-END >docker-compose.cypress_extras.yaml
+    #ddev-generated
+    services:
+      cypress:
+        external_links:
+        {{- $cypress_hostnames := splitList "," (env "DDEV_HOSTNAME") -}}
+        {{- range $i, $n := $cypress_hostnames }}
+          - "ddev-router:{{- replace (env "DDEV_TLD") "\\${DDEV_TLD}" (replace (env "DDEV_PROJECT") "\\${DDEV_PROJECT}" $n) -}}"
+        {{- end }}
+    END
+
+removal_actions:
+  - |
+    #ddev-nodisplay
+    #ddev-description:Remove docker-compose.cypress_extras.yaml file
+    if [ -f docker-compose.cypress_extras.yaml ]; then
+      if grep -q '#ddev-generated' docker-compose.cypress_extras.yaml; then
+        rm -f docker-compose.cypress_extras.yaml
+      else
+        echo "Unwilling to remove '$DDEV_APPROOT/.ddev/docker-compose.cypress_extras.yaml' because it does not have #ddev-generated in it; you can manually delete it if it is safe to delete."
+      fi
+    fi