Technical Details

Structure

Cypress Docker Image

The joomla_cypress Docker container from this testing suite is generated directly on the end user's machine. The docker environment simplifies the setup of Cypress configurations, making it easy to run tests for your Joomla sites. The Docker image is based on the cypress/included:13.14.2 image and is designed to run Cypress tests in a graphical environment. The image extends the Cypress base by adding several utilities, including VNC and a text editor, to support end-to-end testing of applications, especially Joomla sites, in a Dockerized environment.

Key Components:

• Base Image: cypress/included:13.14.2—includes Cypress, a popular testing framework for web applications.
• Installed Tools:
  • git: Version control system for managing code.
  • supervisor, xvfb, x11vnc, fluxbox: Utilities to run graphical applications (like Cypress) inside a virtual desktop via VNC.
  • novnc: Web-based VNC client for interacting with the container via a browser.
  • Sublime Text - Text Editor: Installed via its official repository for text editing.
• User and Permissions Setup: The Dockerfile recreates the node user (which is part of the base Cypress image) with custom user and group IDs. This ensures proper permission handling when running the container as a non-root user.

Entrypoint script:

1. Environment Variable Management:
   Loads environment variables from multiple sources, including .env, je2e.env, and .secret files, to configure the container and testing environment.

2. Configuration File Setup:
   Manages the Cypress configuration file by copying a default configuration (cypress.config.dist.mjs) to the working directory. It creates backups and overrides the configuration if the relevant environment variables allow it (JC_OVERRIDE_BACKUP and JC_OVERRIDE_CONFIG). \

3. Test Data Symlinking:
   Links test data from the Cypress folder in the working directory to the appropriate location in the site directory. This ensures that Cypress has access to the required data during tests.

4. Dependency Management:
   Installs required dependencies via npm or pnpm (default) based on the configuration in package.json. The script ensures that the dependencies are up to date, updating them or reinstalling if missing. With the smart option enabled in the environment variables (default), they will only be updated if they are older than one day, to reduce container startup time. If pnpm is declared in the PACKAGE_MANAGER_PREFS environment variable and only a package-lock.json exists, the missing pnpm-lock.yaml is automatically generated via the cli import command.

5. Start Services:
   The script starts the VNC server and noVNC web server (for graphical access via browser) along with Cypress and supervises them using supervisord. The container is designed to run Cypress tests interactively or headlessly with monitoring.

Use Cases:

1. End-to-End (E2E) Testing:
   The image is designed primarily for E2E testing with Cypress, allowing tests to be executed either headlessly or via a web-based VNC session to view the test execution.

2. Remote Access via VNC:
   By using noVNC, the image allows users to interact with the Cypress GUI and other utilities inside the container from a web browser, providing a seamless way to monitor and control tests remotely.
   Developers can use the provided VNC interface (exposed on port 5800) to access a graphical environment inside the container, making it useful for debugging visual or interaction issues during testing.

Functions - run.sh

Manage sites

• remove-site
  This function helps to remove a Joomla site from the testing tool environment.
  It first checks if the necessary Docker image and container (mysql) is running.
  In the next step the user is prompted to select a site from the list. If a valid option is selected, the script checks if the site directory exists.
  After confirmation with yor Y the script proceed with the removal of the site files and database. It also unlinks the site from the web server directory. If an API token for the site exists in the .secret file, it will be removed.
  It provides a user-friendly way to manage the Joomla sites within the environment and keep the system clean.

• update-index.sites
  This function looks in a specific folder (./data/sites/) to find all Joomla sites installed within the testing tool environment.

  It collects the names of these sites, sorts them alphabetically to ensure they appear in order and stores them in a list.

  For each site, the script creates an HTML list item. Each item includes:

  • A link to the Joomla site.
  • A link to the site's backend (administrator) interface.

  Finally the updated content is saved in index.php.

  It ensures that the index file is always current and correctly formatted, making it easy to navigate to any Joomla site or its backend interface.