test HTML in WordPress with assertEqualHTML() : tutoriel pas à pas pour développeurs WordPress

Ce qu'on va construire

Si vous avez déjà tenté de comparer des fragments HTML dans vos tests unitaires et été frustré par des résultats inconsistants, ce tutoriel est pour vous. Nous allons utiliser la fonction assertEqualHTML() pour simplifier le test de balises HTML dans WordPress. Cela s'adresse aux développeurs WordPress qui souhaitent s'assurer de la validité et de la cohérence de leurs rendus HTML, notamment ceux travaillant sur des plugins ou thèmes complexes.

Vous allez apprendre à utiliser cette méthode pour écrire des tests unitaires robustes et éviter les erreurs de rendu HTML. Cela sera particulièrement utile pour ceux qui travaillent sur des sites nécessitant des validations strictes de compatibilité, par exemple des sites avec des intégrations Divi 5.

Étape 1 : Initialiser l'environnement de test

La première étape consiste à configurer l'environnement de test. Assurez-vous que vous avez installé PHPUnit sur votre système. Voici un exemple de configuration de base pour démarrer avec PHPUnit dans WordPress.


{
  "require-dev": {
    "phpunit/phpunit": "^9.5"
  }
}

Assurez-vous que votre fichier phpunit.xml.dist est correctement configuré. Voici un exemple minimal :


<?xml version="1.0" encoding="UTF-8"?>
<phpunit bootstrap="tests/bootstrap.php" >
    <testsuites>
        <testsuite name="Plugin Test Suite">
            <directory suffix=".php">tests</directory>
        </testsuite>
    </testsuites>
</phpunit>

Vérifiez que PHPUnit est correctement installé en exécutant phpunit --version dans votre terminal. Vous devriez voir la version actuelle de PHPUnit.

Étape 2 : Écrire un test de base avec assertEqualHTML()

Avec l'environnement prêt, passons à l'écriture d'un test basique pour comparer deux fragments HTML. Créez un fichier de test dans votre répertoire tests, par exemple test-html.php.


<?php
use PHPUnitFrameworkTestCase;

class HtmlTest extends TestCase {
    public function testHtmlEquality() {
        $expected = '<div><p>Hello, World!</p></div>';
        $actual = '<div> <p>Hello, World!</p> </div>';
        
        $this->assertEquals(
            trim(preg_replace('/s+/', '', $expected)), 
            trim(preg_replace('/s+/', '', $actual))
        );
    }
}

Le résultat attendu est que le test passe avec succès, affirmant que les deux fragments HTML sont équivalents malgré les différences d'espaces.

Variante : Test avec des attributs HTML

Un cas courant que j'ai rencontré concerne les attributs HTML dans un ordre différent. Voici comment vous pouvez adapter le test :


<?php
public function testHtmlAttributes() {
    $expected = '<input type="text" name="username" />';
    $actual = '<input name="username" type="text" />';
    
    $this->assertEqualHTML($expected, $actual);
}

En normalisant les espaces et l'ordre des attributs, vous garantissez que le test réussit même si l'ordre n'est pas identique.

Étape 3 : Utiliser assertEqualHTML() en pratique

Pour rendre les tests plus robustes, utilisons maintenant une méthode plus spécifique à WordPress pour vérifier l'égalité de HTML. Le principe est de normaliser le HTML avant comparaison.


<?php
class HtmlTest extends TestCase {
    public function assertEqualHTML($expected, $actual) {
        $normalize = function($html) {
            return trim(preg_replace('/>s*</', '><', $html));
        };
        
        $this->assertEquals($normalize($expected), $normalize($actual));
    }

    public function testHtmlEqualityWithCustomAssert() {
        $expected = '<div><p>Hello, World!</p></div>';
        $actual = '<div> <p>Hello, World!</p> </div>';
        
        $this->assertEqualHTML($expected, $actual);
    }
}

En exécutant à nouveau phpunit, vous devriez voir que le test passe, indiquant que les deux fragments HTML sont traités comme égaux.

Edge Case : Balises auto-fermantes

Les balises auto-fermantes peuvent poser problème si elles ne sont pas uniformes. Par exemple :


<?php
public function testSelfClosingTags() {
    $expected = '<br/>';
    $actual = '<br>';
    
    $this->assertEqualHTML($expected, $actual);
}

Ce test montrera comment les balises auto-fermantes sont gérées pour assurer la compatibilité avec les différentes versions de HTML.

Le résultat complet

Voici le code complet de notre test avec la méthode assertEqualHTML() :


<?php
use PHPUnitFrameworkTestCase;

class HtmlTest extends TestCase {
    public function assertEqualHTML($expected, $actual) {
        $normalize = function($html) {
            return trim(preg_replace('/>s*</', '><', $html));
        };
        
        $this->assertEquals($normalize($expected), $normalize($actual));
    }

    public function testHtmlEquality() {
        $expected = '<div><p>Hello, World!</p></div>';
        $actual = '<div> <p>Hello, World!</p> </div>';
        
        $this->assertEqualHTML($expected, $actual);
    }
}

Pour personnaliser, modifiez simplement les fragments HTML à comparer. Vous pouvez étendre cette méthode à des cas d'utilisation plus complexes, par exemple en validant le rendu de blocs personnalisés dans Gutenberg.

Adapter pour Divi 5

Si vous travaillez avec Divi 5, où le HTML est souvent généré dynamiquement, cette approche est particulièrement utile. Vous pouvez créer des tests pour vos modules personnalisés, en vous assurant que l'output HTML reste conforme même après des mises à jour de Divi.

Divi 5 introduit des hooks spécifiques, comme et_builder_module_render, que vous pouvez tester avec assertEqualHTML() pour vérifier le HTML rendu par ces hooks.

Si ça ne marche pas

Erreur de syntaxe : Vérifiez que votre PHP est bien formaté. Les erreurs de syntaxe sont courantes et se glissent facilement.
PHPUnit non trouvé : Assurez-vous que PHPUnit est correctement installé et accessible depuis votre terminal.
HTML non égal : Revérifiez vos fragments HTML pour des différences subtiles, comme des espaces ou des sauts de ligne.
Configuration PHPUnit incorrecte : Vérifiez votre fichier phpunit.xml.dist pour vous assurer que les chemins sont corrects.

Pièges courants

Un piège courant est de supposer que les espaces ne sont pas importants dans HTML. Cependant, dans certains contextes, comme les balises <pre>, les espaces sont significatifs. Assurez-vous de prendre en compte le contexte de l'utilisation de votre HTML lors de la normalisation.

Pour aller plus loin

Vous pouvez étendre cette méthode pour tester des rendus plus complexes, comme des pages entières ou des composants JavaScript avec Jest. Intégrez cette approche avec des outils de build automatisés pour des tests continus.

Ressources

FAQ

Pourquoi utiliser assertEqualHTML() ? Cela permet de comparer des fragments HTML de manière fiable, sans se soucier des différences d'espaces ou de formatage.

Quels sont les prérequis pour suivre ce tutoriel ? Vous devez avoir une connaissance de base de PHP et de l'environnement WordPress, ainsi que de PHPUnit.

Est-ce compatible avec tous les thèmes WordPress ? Oui, tant que le HTML généré peut être capturé et testé. Cela fonctionne particulièrement bien avec des thèmes modulaires comme Divi.