Testez votre site web Drupal avec Cypress

Si vous n’incluez pas de tests dans votre développement Drupal, c’est probablement parce que vous pensez que cela ajoute de la complexité et des dépenses sans avantage. Cyprès est un outil open source avec de nombreux avantages :

• Teste de manière fiable tout ce qui s’exécute dans un navigateur Web
• Fonctionne sur n’importe quelle plate-forme Web (idéal pour tester des projets utilisant des technologies frontales telles que React)
• Très extensible
• De plus en plus populaire
• Facile à apprendre et à mettre en œuvre
• Protège contre la régression à mesure que vos projets deviennent plus complexes
• Peut rendre votre processus de développement plus efficace

Cet article couvre trois sujets pour vous aider à commencer à tester votre projet Drupal à l’aide de Cypress :

1. Installation de Cypress
2. Rédaction et exécution de tests de base avec Cypress
3. Personnalisation de Cypress pour Drupal

Installer Cyprès

Pour les besoins de ce tutoriel, je suppose que vous avez construit un environnement de développement local pour votre projet Drupal en utilisant le projet `drupal/recommended-project`. Bien que les détails sur la création d’un tel projet sortent du cadre de cet article, je recommande Premiers pas avec Lando et Drupal 9.

Votre projet a au moins cette structure de base :

vendor/
web/
.editorconfig
.gitattributes
composer.json
composer.lock

Le site cypress.io a instructions d’installation complètes pour divers environnements. Pour cet article, j’ai installé Cypress en utilisant npm.

Initialisez votre projet à l’aide de la commande npm init. Répondez aux questions que vous pose Node.js, puis vous aurez un package.json fichier qui ressemble à ceci :

{
  "name": "cypress",
  "version": "1.0.0",
  "description": "Installs Cypress in a test project.",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC"
}

Installez Cypress dans votre projet :

$ npm install cypress --save-dev

Exécutez Cypress pour la première fois :

$ npx cypress open

Étant donné que vous n’avez pas ajouté de fichier de configuration ou d’échafaudage à Cypress, l’application Cypress affiche l’écran de bienvenue pour vous aider à configurer le projet. Pour configurer votre projet pour les tests E2E (de bout en bout), cliquez sur le Pas configuré bouton pour les tests E2E. Cypress ajoute quelques fichiers à votre projet :

cypress/
node_modules/
vendor/ 
web/
.editorconfig
.gitattributes
composer.json
composer.lock
cypress.config.js
package-lock.json
package.json

Cliquez sur Continuer et choisissez votre navigateur préféré pour le test. Cliquez sur Commencer les tests E2E dans [your browser of choice]. J’utilise un navigateur basé sur Chromium pour cet article.

Dans une fenêtre séparée, un navigateur s’ouvre pour Créez votre première spécification page:

Clique sur le Spécifications d’exemple d’échafaudage pour créer quelques nouveaux dossiers avec des exemples de spécifications pour vous aider à comprendre comment utiliser Cypress. Lisez-les dans votre éditeur de code et vous trouverez probablement le langage (basé sur JavaScript) intuitif et facile à suivre.

Cliquer sur n’importe quel dans le navigateur de test. Cela révèle deux panneaux. Sur la gauche, un panneau de texte affiche chaque étape de la spécification active. Sur la droite, une fenêtre de navigateur simulée montre l’expérience utilisateur réelle au fur et à mesure que Cypress parcourt les spécifications.

Ouvrez le cypress.config.js fichier à la racine de votre projet et modifiez-le comme suit :

const { defineConfig } = require("cypress");
 
module.exports = defineConfig({
  component: {
    fixturesFolder: "cypress/fixtures",
    integrationFolder: "cypress/integration",
    pluginsFile: "cypress/plugins/index.js",
    screenshotsFolder: "cypress/screenshots",
    supportFile: "cypress/support/e2e.js",
    videosFolder: "cypress/videos",
    viewportWidth: 1440,
    viewportHeight: 900,
  },

  e2e: {
    setupNodeEvents(on, config) {
      // implement node event listeners here
    },
    baseUrl: "https://[your-local-dev-url]",
    specPattern: "cypress/**/*.{js,jsx,ts,tsx}",
    supportFile: "cypress/support/e2e.js",
    fixturesFolder: "cypress/fixtures"
   },
 });

Changer la baseUrl à l’URL de votre projet dans votre environnement de développement local.

Ces modifications indiquent à Cypress où trouver ses ressources et comment trouver toutes les spécifications de votre projet.

Écrire et exécuter des tests de base à l’aide de Cypress

Créez un nouveau répertoire appelé integration dans ton /cypress annuaire. Au sein de la integration répertoire, créez un fichier appelé test.cy.js:

cypress/
├─ e2e/
├─ fixtures/
├─ integration/ 
│  ├─ test.cy.js
├─ support/ 
node_modules/
vendor/
web/
.editorconfig
.gitattributes
composer.json
composer.lock
cypress.config.js
package-lock.json
package.json

Ajoutez le contenu suivant à votre test.cy.js déposer:

describe('Loads the front page', () => {
  it('Loads the front page', () => {
    cy.visit("https://opensource.com/")
    cy.get('h1.page-title')
      .should('exist')
  });
});
 
describe('Tests logging in using an incorrect password', () => {
  it('Fails authentication using incorrect login credentials', () => {
    cy.visit('/user/login')
    cy.get('#edit-name')
      .type('Sir Lancelot of Camelot')
    cy.get('#edit-pass')
      .type('tacos')
    cy.get('input#edit-submit')
      .contains('Log in')
      .click()
    cy.contains('Unrecognized username or password.')
  });
});

Lorsque vous cliquez sur test.cy.js dans l’application Cypress, regardez chaque description de test sur la gauche pendant que Cypress exécute les étapes de chaque describe() section.

Cette spécification montre comment dire à Cypress de naviguer sur votre site Web, d’accéder aux éléments HTML par ID, d’entrer du contenu dans les éléments d’entrée et de soumettre le formulaire. Ce processus est la façon dont j’ai découvert que je devais ajouter l’affirmation que le <input id="edit-submit"> l’élément contient le texte Connexion avant que l’entrée ne soit cliquable. Apparemment, le style flexible de l’entrée de soumission empêchait Cypress de “voir” l’entrée, de sorte qu’il ne pouvait pas cliquer dessus. Les tests fonctionnent vraiment !

Personnaliser Cypress pour Drupal

Vous pouvez également écrire vos propres commandes Cypress personnalisées. Se souvenir du supportFile entrée dans le cypress.config.js déposer? Il pointe vers un fichier que Cypress a ajouté, qui à son tour importe le ./commands des dossiers. Incidemment, Cypress est si intelligent que lors de l’importation d’appareils logiques ou de données, vous n’avez pas besoin de spécifier l’extension de fichier, vous importez donc ./commandspas ./commands.js. Cypress recherche l’une des douzaines d’extensions de fichiers les plus populaires et comprend comment les reconnaître et les analyser.

Entrez les commandes dans commands.js pour les définir :

/**
 * Logs out the user.
 */
 
Cypress.Commands.add('drupalLogout', () => {
  cy.visit('/user/logout');
})
 
/**
 * Basic user login command. Requires valid username and password.
 *
 * @param {string} username
 *   The username with which to log in.
 * @param {string} password
 *   The password for the user's account.
 */
 
Cypress.Commands.add('loginAs', (username, password) => {
  cy.drupalLogout();
  cy.visit('/user/login');
  cy.get('#edit-name')
    .type(username);
  cy.get('#edit-pass').type(password, {
    log: false,
  });
 
  cy.get('#edit-submit').contains('Log in').click();
});

Cet exemple définit une commande Cypress personnalisée appelée drupalLogout(), que vous pouvez utiliser dans n’importe quelle logique ultérieure, même dans d’autres commandes personnalisées. Pour déconnecter un utilisateur, appelez cy.drupalLogout(). Il s’agit du premier événement de la commande personnalisée loginAs pour vous assurer que Cypress est déconnecté avant de tenter de vous connecter en tant qu’utilisateur spécifique.

En utilisant des variables d’environnement, vous pouvez même créer une commande Cypress appelée drush(), que vous pouvez utiliser pour exécuter des commandes Drush dans vos tests ou commandes personnalisées. Regardez à quel point cela simplifie la définition d’une commande Cypress personnalisée qui connecte un utilisateur à l’aide de son UID :

/**
* Logs a user in by their uid via drush uli.
*/
 
Cypress.Commands.add('loginUserByUid', (uid) => {
 cy.drush('user-login', [], { uid, uri: Cypress.env('baseUrl') })
   .its('stdout')
   .then(function (url) {
     cy.visit(url);
   });
});

Cet exemple utilise le drush user-login commande (drush uli pour faire court) et amène l’utilisateur authentifié à l’URL de base du site.

Considérez l’avantage de sécurité de ne jamais lire ou stocker les mots de passe des utilisateurs dans vos tests. Personnellement, je trouve étonnant qu’une technologie frontale comme Cypress puisse exécuter des commandes Drush, que j’ai toujours considérées comme étant très en arrière-plan.

Tester, tester

Il y a beaucoup plus dans Cypress, comme les appareils (fichiers contenant les données de test) et diverses astuces pour naviguer dans les structures de données parfois complexes qui produisent l’interface utilisateur d’un site Web. Pour un aperçu de ce qui est possible, regardez le Test Cypress pour les sites Web Drupal webinaire, en particulier la section sur les matches qui commence à 18h33. Ce webinaire donne plus de détails sur certains cas d’utilisation intéressants, y compris un formulaire compatible Ajax. Une fois que vous commencez à l’utiliser, n’hésitez pas à utiliser ou à bifurquer Dépôt public d’Aten de Cypress Testing pour Drupal.

Bon test !

Cet article est initialement paru sur le Blog d’Aton et est republié avec autorisation.