# Tests end-to-end avec Puppeteer et @wordpress/e2e-test-utils

> PHPUnit ne voit jamais l'éditeur de blocs tel qu'un utilisateur le manipule. Puppeteer et le paquet officiel e2e-test-utils automatisent un vrai navigateur pour le tester.

- Auteur : Clément Hadrot
- Publié le : 2021-07-14
- Mis à jour le : 2021-07-14
- Catégorie : Tests
- URL : https://wpmoderne.dev.wordpress-developpement.fr/tests/tests-e2e-puppeteer-wordpress/

## L’essentiel

- Un vrai navigateur Chromium piloté depuis Node.js
- Des utilitaires officiels pour l'éditeur de blocs
- Un parcours de publication testé de bout en bout

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](https://pptr.dev/) 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-default
```

Les 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' ],
};
```

> L'essentiel à retenir : Un vrai navigateur Chromium piloté depuis Node.js ; Des utilitaires officiels pour l'éditeur de blocs ; Un parcours de publication testé de bout en bout

## 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.