Cypress JSON Tests

A Cypress-based testing framework specifically designed for Drupal projects. This tool allows you to define end-to-end (E2E) workflows and HTTP status code validation tests entirely through a single JSON configuration file, without needing to write custom Cypress JavaScript code for most common test scenarios.

Features

• JSON-Driven Testing: Define your test cases, UI interactions, and assertions entirely in a config.json file.
• Drupal Integration: Built-in commands to interact with Drupal via Drush (supports Lando and Ahoy environments). Includes automated user login, blocking/unblocking, and role management.
• Status Code Validation: Easily verify that specific URLs return expected HTTP status codes for different user roles (e.g., ensuring anonymous users get 403 on admin pages).
• UI Workflow Validation: Simulate complex user journeys including filling forms, interacting with CKEditor 5, changing moderation states, validating text and meta tags, and managing content creation/deletion.

Installation

Install the package as a development dependency alongside Cypress (requires Cypress >=15.4.0):

npm install cypress-json-tests --save-dev

Running Cypress tests

Run the tests by pointing the Cypress runner to your JSON configuration folder (which should contain a config.json file).

To open the Cypress runner:

npx cypress open --config "fixturesFolder=../fixtures,baseUrl=https://example.com" --env env=lando

To run the tests in the CLI:

npx cypress run --config "fixturesFolder=../fixtures,baseUrl=https://example.com" --env env=lando

• fixturesFolder: Path to the folder containing your config.json file.
• baseUrl: The base URL of your Drupal site.
• --env env=lando: (Optional) Specify your local development environment to correctly prefix Drush commands (lando, ahoy, or omit for direct drush execution).

Configuration Format (config.json)

Create a config.json file in your fixtures folder to define your test suite. Example JSON structure:

{
  "config": {
    "save_button_identifier": ".wrapper .form-submit",
    "action_button_identifier": ".tabs .nav-link",
    "skip_antibot": false
  },
  "users": {
    "editor": "editor",
    "approver": "approver",
    "site_administrator": "site_administrator"
  },
  "requests": {
    "Validate URL Article": [
      {
        "url": "node/add/article",
        "role": "editor",
        "action": {
          "fill_values": {
            "#edit-title-0-value": "Testing article",
            "#edit-field-summary-0-value": "Test article summary."
          },
          "save": true
        }
      },
      {
        "clean_this": true,
        "url": "news/testing-article",
        "role": "editor",
        "action": {
          "validate": {
            "contain": {
              "h1": "Testing article"
            },
            "meta": {
              "title": "Testing article | Drupal 11",
              "description": "Test article summary."
            }
          }
        }
      }
    ]
  },
  "statuses": [
    [
      "anonymous",
      "/",
      200
    ],
    [
      "anonymous",
      "/admin",
      403
    ],
    [
      "anonymous",
      "/admin/content",
      403
    ],
    [
      "anonymous",
      "/zzz",
      404
    ],
    [
      "editor",
      "/",
      200
    ],
    [
      "editor",
      "/admin",
      200
    ],
    [
      "editor",
      "/admin/content",
      200
    ],
    [
      "editor",
      "/zzz",
      404
    ]
  ]
}

Supported properties in config object

• save_button_identifier: CSS selector for the save button in the admin form.
• action_button_class: CSS selector for the action button on the node view page.
• skip_antibot: Boolean to skip antibot for anonymous users. If true, antibot will be disabled for anonymous users for the entire test.

Supported action Properties in Workflows:

• fill_values: Object mapping CSS selectors to strings to type into input fields.
• ck5_values: Object mapping CKEditor 5 element IDs to HTML content to set.
• select_values: Object mapping CSS selectors to values to select in dropdowns.
• click: Object where keys are CSS selectors to click (values are ignored).
• validate: Object containing assertion rules:
  • contain: Key-value pairs of selector and expected text.
  • not_contain: Key-value pairs of selector and text that should not be present.
  • exists_and_contain / exists_but_not_contain: Asserts the element exists and checks its text.
  • meta: Validates title and description meta tags.
  • select: Validates dropdown options.
• save: Boolean. If true, clicks the configured save button and handles any confirmation dialogs.
• node_action: Special actions like edit (clicks the Edit tab) or change_node_status (clicks Moderation Sidebar tab).

Available Cypress Commands/Helpers

This package provides several custom Cypress commands/helpers specifically for Drupal testing:

• cy.drush(command, args, options): Executes a Drush command with the environment prefix.
• cy.drupalLogin(username): Generates a random password, sets it via Drush, and logs the user in via the login form.
• cy.drupalLogout(): Visits /user/logout to log the user out.
• cy.blockUserByUsername(username) / cy.unblockUserByUsername(username): Blocks/unblocks user accounts via Drush.
• cy.visitAndDeletePage(pageUrl): Visits a given URL and attempts to delete the node using the configured action and save buttons.