# @wordpress/e2e-test-utils-playwright : le guide complet pour vos tests E2E

> Le paquet officiel qui a remplacé les utilitaires Puppeteer de l'équipe cœur WordPress regroupe plus de cent cinquante fonctions prêtes à l'emploi. Tour d'horizon des plus utiles.

- Auteur : Clément Hadrot
- Publié le : 2024-03-21
- Mis à jour le : 2024-03-21
- Catégorie : Tests
- URL : https://wpmoderne.dev.wordpress-developpement.fr/tests/guide-e2e-test-utils-playwright/

## L’essentiel

- Les fixtures admin, editor et requestUtils prêtes à l'emploi
- Une API alignée sur celle utilisée par le cœur WordPress lui-même
- requestUtils pour préparer l'état du site sans passer par l'interface

Depuis que l'équipe cœur de WordPress a migré l'intégralité de la suite de tests E2E de Gutenberg vers Playwright, le paquet `@wordpress/e2e-test-utils-playwright` est devenu la référence pour quiconque écrit des tests end-to-end sur WordPress. Il ne s'agit pas d'un simple portage de l'ancien `@wordpress/e2e-test-utils` pensé pour Puppeteer : l'API a été repensée autour du système de fixtures propre à Playwright, avec des objets dédiés qui regroupent les actions par domaine.

Cet article fait le tour des fixtures les plus utiles du paquet, avec des exemples concrets tirés de tests que nous maintenons sur des projets clients, pour vous permettre de démarrer efficacement sans réinventer des utilitaires qui existent déjà.

## Installer le paquet et configurer Playwright

```
npm install --save-dev @wordpress/e2e-test-utils-playwright @playwright/test
npx playwright install --with-deps chromium
```

Le paquet s'utilise en étendant l'objet `test` fourni par `@playwright/test`, ce qui donne accès à des fixtures supplémentaires directement dans la signature de chaque test :

```
const { test, expect } = require( '@wordpress/e2e-test-utils-playwright' );
```

Contrairement à l'ancien paquet Puppeteer, qui exposait des fonctions importées individuellement, ce paquet organise ses utilitaires en objets thématiques injectés automatiquement dans chaque test, un peu comme des services.

## Les trois fixtures principales

### admin

La fixture `admin` regroupe les actions liées à l'administration WordPress : créer un contenu, visiter une page d'administration, gérer les widgets.

```
test( 'crée un nouvel article', async ( { admin } ) => {
    await admin.createNewPost();
} );
```

### editor

La fixture `editor` couvre tout ce qui touche à l'éditeur de blocs : insertion de blocs, publication, manipulation de l'inspecteur.

```
test( 'insère un bloc paragraphe et le remplit', async ( { editor, page } ) => {
    await editor.insertBlock( { name: 'core/paragraph' } );
    await page.keyboard.type( 'Un contenu de test.' );
    await editor.publishPost();
} );
```

> L'essentiel à retenir : Les fixtures admin, editor et requestUtils prêtes à l'emploi ; Une API alignée sur celle utilisée par le cœur WordPress lui-même ; requestUtils pour préparer l'état du site sans passer par l'interface

### requestUtils

La fixture la plus précieuse pour des suites de tests rapides et fiables : `requestUtils` permet de préparer l'état du site directement via l'API REST WordPress, sans passer par l'interface graphique. Créer un article, un utilisateur ou une catégorie via `requestUtils` plutôt qu'en cliquant dans l'interface divise le temps d'exécution et réduit fortement la fragilité du test :

```
test.beforeEach( async ( { requestUtils } ) => {
    await requestUtils.deleteAllPosts();
    await requestUtils.createPost( {
        title: 'Article existant',
        status: 'publish',
    } );
} );

test( 'affiche l\'article existant sur la page d\'accueil', async ( { page } ) => {
    await page.goto( '/' );
    await expect( page.locator( 'h1' ) ).toContainText( 'Article existant' );
} );
```

Cette approche illustre un principe important des tests E2E efficaces : chaque interaction passant par l'interface graphique doit être justifiée par le fait que c'est précisément ce que le test cherche à vérifier. Pour tout le reste, la préparation de données, l'API REST est plus rapide et moins fragile qu'un enchaînement de clics.

## Autres fixtures utiles

- `pageUtils` : utilitaires génériques de navigation et d'attente, indépendants de WordPress.
- `editorUtils` aliasé parfois via `editor` selon les versions : sélection de blocs, accès au contenu sérialisé de l'éditeur.
- `PERF_TIMEOUT` et fixtures liées à la mesure de performance, utilisées par l'équipe cœur pour ses propres benchmarks de l'éditeur.

## Un exemple complet : tester un plugin de formulaire

```
const { test, expect } = require( '@wordpress/e2e-test-utils-playwright' );

test.describe( 'Bloc formulaire de contact', () => {
    test.beforeEach( async ( { requestUtils } ) => {
        await requestUtils.activatePlugin( 'mon-plugin-formulaire' );
    } );

    test( 'affiche une erreur si l\'email est invalide', async ( { admin, editor, page } ) => {
        await admin.createNewPost();
        await editor.insertBlock( { name: 'mon-plugin/formulaire-contact' } );
        await editor.publishPost();

        const url = page.url();
        await page.goto( url.replace( '&action=edit', '' ) );

        await page.fill( 'input[type="email"]', 'pas-un-email' );
        await page.click( 'button[type="submit"]' );

        await expect( page.locator( '.mon-plugin-erreur' ) ).toBeVisible();
    } );
} );
```

Cet exemple combine les trois fixtures principales : `requestUtils` pour activer le plugin sans passer par l'interface d'administration des extensions, `admin` et `editor` pour construire le contenu de test, puis les méthodes natives de Playwright (`page.fill`, `page.click`) pour simuler l'interaction réelle de l'utilisateur final sur le front.

## Pourquoi s'aligner sur l'API du cœur WordPress

Utiliser ce paquet officiel plutôt que de réécrire ses propres utilitaires présente un avantage souvent sous-estimé : la documentation et les exemples les plus riches sur ces fonctions se trouvent directement dans le dépôt Gutenberg lui-même, où des centaines de tests réels les utilisent au quotidien. En cas de doute sur le comportement exact d'une fonction, il suffit de chercher son usage dans la suite de tests E2E du cœur, ce qui n'est pas possible avec un ensemble d'utilitaires maison.

> Sur nos projets, nous déconseillons de réécrire des fonctions équivalentes à `requestUtils.createPost()` ou `admin.createNewPost()` à la main. Le paquet officiel gère déjà les cas limites (attente de chargement, gestion des redirections d'authentification) qu'une implémentation maison finit toujours par redécouvrir un par un, en production.

## En résumé

Le paquet `@wordpress/e2e-test-utils-playwright` fournit une base solide et activement maintenue pour tester un projet WordPress de bout en bout, organisée autour de fixtures claires : `admin` pour l'administration, `editor` pour l'éditeur de blocs, et surtout `requestUtils` pour préparer rapidement l'état du site via l'API REST. S'appuyer sur ces utilitaires plutôt que de les réinventer fait gagner un temps considérable et aligne vos tests sur les pratiques mêmes de l'équipe qui développe WordPress.