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 chromiumLe 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();
} );
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.editorUtilsaliasé parfois viaeditorselon les versions : sélection de blocs, accès au contenu sérialisé de l’éditeur.PERF_TIMEOUTet 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()ouadmin.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.
