Chez XPEHO, l’assurance d’un code fiable et sécurisé est une mission qui nous tient particulièrement à cœur.
Garantir que nos développements répondent aux exigences métier, tout en s’assurant qu’aucune modification future ne vienne casser l’existant, est au centre de nos préoccupations quotidiennes.
C’est pourquoi nous avons mis en place des tests “End-to-End” Cucumber en JavaScript. Forts de nos découvertes techniques, nous les avons déployés sur l’un de nos projets phares : XpeApp !
Pour rappel, en quelques lignes, XpeApp est l’application qui permet à nos collaborateurs d’être informés en un clic, directement sur leur téléphone, de toute l’actualité de l’entreprise et de soumettre leurs idées pour la faire grandir.
Grâce à Cucumber, nous traduisons nos scénarios d’usage en tests automatisés lisibles par tous, garantissant ainsi une expérience utilisateur sans faille.
Qu’est-ce que c’est ?
Cucumber.js est la version JavaScript du célèbre framework de test basé sur le BDD (Behavior Driven Development). Il permet de rédiger des scénarios de test en langage naturel (Gherkin), rendant la validation technique compréhensible par tous (développeurs, PO, clients).
Il permet de combiner :
- Des fichiers .feature en Gherkin.
- Des Step Definitions en JavaScript (ES Modules).
- Une intégration fluide avec les outils Node.js pour tester des API REST.
Focus Technique : Cucumber.js & ES Modules
Nous avons opté pour une stack moderne garantissant performance et lisibilité.
Configuration & Stack
- ES Modules : Utilisation du “type”: “module” dans le package.json pour bénéficier des import/export natifs.
- Dépendances clés : @cucumber/cucumber pour le moteur de test et cucumber-html-reporter pour la restitution visuelle.
- Automation : Un seul script npm test qui enchaîne l’exécution des tests et la génération du rapport HTML via un script Node dédié.
Structure du Projet
Nous appliquons une séparation stricte par domaine métier pour assurer la scalabilité :
- features/ : Scénarios Gherkin (ex: jwt_authentication.feature).
- step_definitions/ : Logique de test en JavaScript (ex: user.steps.js).
- report/ : Artefacts de test et rapports d’exécution.
À l’attaque !
Dans notre structure, nous créons notre fichier de test dans features/jwt/jwt_authentication.feature.
Exemple
Feature: JWT Authentication
Scenario: Login to the WordPress JWT API
Given the WordPress JWT API is available
When I login with username "wordpress_dev" and password "wordpress_dev"
Then I receive a valid JWT token
Scenario: Login to the WordPress JWT API with invalid credentials
Given the WordPress JWT API is available
When I login with username "demo" and password "demo"
Then I receive a forbidden error
La logique derrière les mots (Step Definitions)
Pour que Cucumber comprenne ces phrases, nous créons un fichier JavaScript. Le partage de données entre les étapes se fait via le World Object (this) :
import { Given, When, Then } from '@cucumber/cucumber';
import assert from 'node:assert';
Given('the WordPress JWT API is available', async function () {
this.apiUrl = process.env.WP_API_URL || 'http://localhost:7830/wp-json/jwt-auth/v1/token';
});
let response;
When('I login with username {string} and password {string}', async function (username, password) {
// Appel direct à l'API WordPress via fetch
response = await fetch(this.apiUrl, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ username, password })
});
this.body = await response.json(); // Stockage pour l'assertion suivante
});
Then('I receive a valid JWT token', function () {
assert.strictEqual(response.status, 200);
assert.ok(this.body.token);
});Décomposition d’un test Cucumber
- Feature : Description de la fonctionnalité testée.
- Scénario : Un cas d’usage spécifique.
- Given (Étant donné) : Le contexte initial (URL de l’API).
- When (Quand) : L’action réalisée (appel POST avec credentials).
- Then (Alors) : Le résultat attendu (Code 200 et présence du token).
Exécution et Résultats
Pour lancer les tests, il suffit d’une commande : npm test. Le résultat technique s’affiche dans la console, mais Cucumber génère également un rapport JSON qui est ensuite converti en une page HTML élégante grâce à cucumber-html-reporter.
Le rapport se trouve dans : report/cucumber_report.html
Automatiser avec GitHub Actions et Docker
Pour garantir que chaque modification sur XpeApp est saine, nous avons automatisé le lancement de nos tests Cucumber via GitHub Actions. L’avantage de cette approche est qu’elle est universelle : elle fonctionne pour tester n’importe quelle API, qu’elle soit sous WordPress, Node.js ou autre.
L’environnement de test
Pour simuler un environnement réel, nous utilisons Docker directement dans notre CI. Le workflow GitHub Actions se décompose en trois grandes étapes :
- Préparation du terrain : On installe Node.js et on monte une base de données MySQL via les services de GitHub.
- Lancement du serveur : On construit l’image Docker de notre API (ici WordPress) et on la lance.
Petit “tip” technique : on utilise — add-host=host.docker.internal:host-gateway pour permettre au conteneur de communiquer facilement avec la base de données. - Le verdict : Une fois que tout est prêt, on lance npm test.
Aperçu de notre Workflow CI
name: "CI Cucumber Tests"
on:
push:
branches: ["main"]
jobs:
cucumber-tests:
runs-on: ubuntu-latest
services:
db: # On monte une DB MySQL pour les tests
image: mysql:9.0
env:
MYSQL_ROOT_PASSWORD: root
ports:
- 52000:3306
steps:
- uses: actions/checkout@v4
# Montage de l'API via Docker
- name: "Build and start WordPress"
run: |
docker build -t xpeapp-wordpress .
docker run -d - name wordpress \
-p 7830:80 \
xpeapp-wordpress
# Exécution du test runner
- name: "Run Cucumber tests"
run: cd cucumber_xpeapp && npm test
# Récupération du rapport final
- name: "Upload report"
uses: actions/upload-artifact@v4
with:
name: cucumber-report
path: cucumber_xpeapp/report/
Pourquoi c’est puissant ?
Peu importe la complexité de votre API, tant qu’elle peut tourner dans un conteneur Docker, Cucumber peut l’interroger.
Le petit bonus : nous utilisons actions/upload-artifact pour récupérer automatiquement le rapport HTML en fin de job. En cas d’échec, on peut visualiser précisément quelle étape a bloqué directement depuis l’interface GitHub !
Conclusion
L’avantage de Cucumber.js est sa capacité à créer une documentation vivante.
N’importe quel membre de l’équipe XPEHO peut lire les fichiers .feature et comprendre ce qui est testé sur XpeApp.
Résultat
Une documentation vivante, des tests automatisés robustes et un rapport visuel disponible en un clic après chaque build.
C’est un outil puissant pour garantir la non-régression tout en gardant une base de code propre et documentée.
On se retrouve bientôt pour un prochain article chez XPEHO ! 😁
A propos de l’auteur
Article rédigé par Théo Lebègue
Développeur chez XPEHO
