Un test PHPUnit peut garantir qu’une fonction retourne la bonne valeur, mais il ne dit rien de ce que voit réellement un utilisateur dans l’éditeur de blocs, ni de la façon dont un bloc personnalisé se comporte une fois inséré, déplacé, puis republié. Pour ce niveau de vérification, il faut un vrai navigateur, qui charge la page, exécute le JavaScript, et interagit avec l’interface comme le ferait une personne. C’est le rôle des tests end-to-end, et sur l’écosystème WordPress, la combinaison Puppeteer plus le paquet officiel @wordpress/e2e-test-utils reste la voie la plus balisée.
Cet article présente la mise en place de cette chaîne de tests, avec un exemple concret : vérifier qu’un bloc personnalisé s’insère correctement dans l’éditeur et que son rendu apparaît bien sur le front une fois l’article publié.
Pourquoi Puppeteer sur un projet WordPress
Puppeteer est une bibliothèque Node.js développée par l’équipe Chrome, qui pilote une instance de Chromium par le protocole DevTools. C’est l’outil que l’équipe cœur de WordPress utilise elle-même pour tester Gutenberg, ce qui explique pourquoi le paquet @wordpress/e2e-test-utils expose des fonctions prêtes à l’emploi pour interagir avec l’éditeur de blocs : ouvrir l’inserteur, chercher un bloc par son nom, publier un article, attendre que l’éditeur soit prêt.
Installer la chaîne de test
npm install --save-dev jest puppeteer jest-puppeteer @wordpress/e2e-test-utils @wordpress/jest-preset-defaultLes tests E2E WordPress s’exécutent avec Jest comme lanceur de tests, jest-puppeteer comme intégration entre les deux, et le préréglage officiel @wordpress/jest-preset-default qui configure les bons timeouts et la bonne configuration Puppeteer par défaut. Un fichier jest.config.js minimal ressemble à ceci :
module.exports = {
preset: '@wordpress/jest-preset-default',
testMatch: [ '<rootDir>/tests/e2e/**/*.test.js' ],
};
Un premier test : insérer un bloc et vérifier le rendu
Supposons un plugin qui enregistre un bloc personnalisé nommé mon-plugin/citation-mise-en-avant. Le test suivant ouvre un nouvel article, insère le bloc, saisit du texte, publie l’article, puis vérifie le rendu sur le front :
import {
createNewPost,
insertBlock,
publishPost,
visitAdminPage,
} from '@wordpress/e2e-test-utils';
describe( 'Bloc citation mise en avant', () => {
it( 'insère le bloc, publie l\'article et affiche le rendu sur le front', async () => {
await createNewPost();
await insertBlock( 'Citation mise en avant' );
await page.keyboard.type( 'Un test qui échoue en silence n\'aide personne.' );
const url = await publishPost();
await page.goto( url );
const contenu = await page.$eval(
'.wp-block-mon-plugin-citation-mise-en-avant',
( el ) => el.textContent
);
expect( contenu ).toContain( 'Un test qui échoue en silence' );
} );
} );Ce test couvre un parcours complet : l’insertion via l’inserteur de blocs, la saisie de contenu, la publication, puis la vérification du HTML réellement rendu sur le front. Aucun test PHPUnit, même le plus complet, ne peut donner cette garantie, puisqu’il ne charge jamais l’éditeur JavaScript.
Fonctions utilitaires les plus utiles
createNewPost( options ): ouvre l’éditeur sur un nouvel article, avec des options pour le type de contenu ou le titre.insertBlock( nomDuBloc ): ouvre l’inserteur, cherche le bloc par son nom affiché, et l’insère.publishPost(): clique sur le bouton de publication, gère la confirmation, et retourne l’URL publiée.visitAdminPage( chemin ): navigue vers une page d’administration donnée, en gérant l’authentification.clickBlockToolbarButton( libelle ): clique sur un bouton de la barre d’outils du bloc actuellement sélectionné.
Authentification et environnement de test
Les tests E2E WordPress supposent une installation WordPress réelle et accessible, généralement via @wordpress/env ou un environnement Docker équivalent, avec un utilisateur administrateur déjà configuré. Le paquet e2e-test-utils lit les identifiants dans des variables d’environnement (WP_BASE_URL, WP_USERNAME, WP_PASSWORD) et gère la connexion automatiquement au premier appel qui en a besoin.
Les limites à connaître
Les tests E2E sont précieux mais coûteux : chaque test démarre un navigateur réel, charge des pages complètes, et s’exécute donc nettement plus lentement qu’un test PHPUnit ou qu’un test Jest unitaire sur un composant isolé. Ils sont aussi plus fragiles face aux changements d’interface : un simple renommage de bouton dans l’éditeur peut faire échouer plusieurs tests d’un coup.
- Réservez les tests E2E aux parcours critiques : publication, sauvegarde de contenu, interactions front essentielles.
- Évitez de dupliquer en E2E ce qu’un test PHPUnit ou Jest peut déjà couvrir plus rapidement.
- Ajoutez des attentes explicites (
page.waitForSelector) plutôt que des délais fixes, pour limiter les échecs aléatoires liés à la latence.
Sur nos projets, nous limitons volontairement le nombre de tests E2E à une poignée de parcours vraiment critiques pour le client. Une suite E2E de deux cents tests qui prend quarante minutes à s’exécuter finit toujours par être ignorée, alors qu’une suite de vingt tests ciblés reste consultée à chaque déploiement.
En résumé
Puppeteer et @wordpress/e2e-test-utils permettent de vérifier ce qu’aucun test PHPUnit ne peut couvrir : le comportement réel de l’éditeur de blocs et du rendu front, dans un navigateur authentique. Bien dosés, sur un nombre restreint de parcours critiques, ces tests apportent une garantie que ni l’analyse statique ni les tests unitaires ne peuvent offrir, au prix d’un temps d’exécution et d’une fragilité qu’il faut accepter de gérer.
