Maîtrisez assertEqualHTML() sur WordPress

par Thierry Bertrand | WordPress

Ce qu'on va construire

Vous avez probablement déjà entendu parler de l'utilitaire assertEqualHTML() si vous avez passé du temps à écrire des tests unitaires pour vos plugins ou thèmes WordPress. Mais comment l'intégrer efficacement dans vos projets WordPress ? Aujourd'hui, nous allons plonger dans la mise en œuvre de cette fonction utile pour comparer le HTML généré par votre code à celui attendu. Ce tutoriel s'adresse aux développeurs cherchant à améliorer la fiabilité de leurs tests pour des sites complexes, comme ceux utilisant des builders visuels ou des fonctionnalités avancées de WordPress.

Étape 1 : Configuration de l'environnement de test

Avant de commencer à utiliser assertEqualHTML(), nous devons préparer notre environnement de test. Assurez-vous d'avoir PHPUnit installé et configuré pour votre projet WordPress. Voici comment procéder :

composer require --dev phpunit/phpunit

Ensuite, créez un fichier phpunit.xml.dist dans le répertoire racine de votre projet avec le contenu suivant :


<phpunit bootstrap="tests/bootstrap.php" colors="true">
    <testsuites>
        <testsuite name="WordPress Plugin Test Suite">
            <directory>tests</directory>
        </testsuite>
    </testsuites>
    <php>
        <ini name="error_reporting" value="-1"/>
        <ini name="display_errors" value="1"/>
    </php>
</phpunit>

En exécutant phpunit dans votre terminal, vous devriez maintenant voir les tests être exécutés (même s'ils échouent pour l'instant).

Étape 2 : Création des tests unitaires

Maintenant que notre environnement est prêt, nous allons créer un test unitaire basique pour un shortcode qui génère du HTML. Admettons que vous ayez un shortcode [hello_world] qui retourne un simple paragraphe HTML :

add_shortcode('hello_world', function() {
    return '<p>Hello, World!</p>';
});

Dans le dossier tests, créez un fichier test-shortcode.php :


class TestShortcode extends WP_UnitTestCase {
    public function test_hello_world_shortcode() {
        $output = do_shortcode('[hello_world]');
        $this->assertEqualHTML('<p>Hello, World!</p>', $output);
    }
}

Ce test vérifie que le HTML généré par le shortcode est bien ce que nous attendons.

Étape 3 : Construction de la fonction assertEqualHTML

Nous devons maintenant implémenter la fonction assertEqualHTML() dans notre suite de tests. Voici comment :


class WP_UnitTestCase extends PHPUnitFrameworkTestCase {
    public function assertEqualHTML($expected, $actual, $message = '') {
        $normalizedExpected = $this->normalizeHTML($expected);
        $normalizedActual = $this->normalizeHTML($actual);
        $this->assertEquals($normalizedExpected, $normalizedActual, $message);
    }

    private function normalizeHTML($html) {
        return preg_replace('/s+/', '', trim($html));
    }
}

La méthode normalizeHTML() supprime les espaces inutiles afin de faciliter la comparaison du contenu HTML.

Dans mon expérience, cette normalisation est souvent suffisante, mais pour des cas plus complexes incluant des attributs ou des balises imbriquées, une approche basée sur le DOMDocument pourrait être nécessaire pour un parsing plus robuste :


private function normalizeHTMLUsingDOM($html) {
    $dom = new DOMDocument();
    libxml_use_internal_errors(true);
    $dom->loadHTML($html);
    libxml_clear_errors();
    return $dom->saveHTML();
}

Étape 4 : Intégration des tests dans le workflow

Pour intégrer ces tests dans votre workflow de développement continu, ajoutez l'exécution de PHPUnit dans votre pipeline CI/CD. Par exemple, pour un fichier .gitlab-ci.yml :


stages:
  - test

phpunit:
  stage: test
  script:
    - composer install
    - vendor/bin/phpunit

Cela garantit que vos tests sont exécutés à chaque commit, vous alertant immédiatement des régressions potentielles.

Le résultat complet

Voici l'ensemble du code nécessaire pour intégrer et tester le HTML dans votre plugin ou thème WordPress :


// Shortcode definition
add_shortcode('hello_world', function() {
    return '<p>Hello, World!</p>';
});

// PHPUnit test class
class TestShortcode extends WP_UnitTestCase {
    public function test_hello_world_shortcode() {
        $output = do_shortcode('[hello_world]');
        $this->assertEqualHTML('<p>Hello, World!</p>', $output);
    }
}

// WP_UnitTestCase modification
class WP_UnitTestCase extends PHPUnitFrameworkTestCase {
    public function assertEqualHTML($expected, $actual, $message = '') {
        $normalizedExpected = $this->normalizeHTML($expected);
        $normalizedActual = $this->normalizeHTML($actual);
        $this->assertEquals($normalizedExpected, $normalizedActual, $message);
    }

    private function normalizeHTML($html) {
        return preg_replace('/s+/', '', trim($html));
    }
}

Ce code vous offre une base solide pour développer des tests HTML robustes.

Adapter pour Divi 5

Si vous développez avec Divi 5, vous pouvez utiliser des hooks spécifiques pour tester vos modules personnalisés. Intégrez assertEqualHTML() dans vos tests de modules Divi en ajoutant les hooks de rendu de module dans vos tests unitaires :


class TestDiviModule extends WP_UnitTestCase {
    public function test_divi_module_render() {
        $output = apply_filters('et_pb_module_shortcode', '

				
				
				
				
				
			
', array());
        $this->assertEqualHTML('<div class="et_pb_text"><p>Content</p></div>', $output);
    }
}

Cela vous permet de vérifier que le HTML généré par vos modules Divi correspond à vos attentes.

Un point important avec Divi est de s'assurer que les styles CSS et les scripts JS spécifiques aux modules sont également chargés correctement dans l'environnement de test, ce qui peut nécessiter des mocks pour les fonctions d'enqueue.

Si ça ne marche pas

  • Problème : PHPUnit ne se lance pas. Assurez-vous que composer install a été exécuté correctement.
  • Problème : Les tests échouent à cause des espaces. Vérifiez que normalizeHTML() est bien appliqué.
  • Problème : do_shortcode() ne fonctionne pas dans les tests. Assurez-vous que le WordPress Testing Framework est bien chargé.
  • Problème : Des erreurs de PHP apparaissent. Vérifiez la version de PHP et assurez-vous qu'elle est compatible avec PHPUnit.
  • Problème : Les modules Divi ne se chargent pas correctement. Vérifiez que Divi 5 est installé et actif dans votre environnement de test.

Pièges courants

Un piège courant est de ne pas prendre en compte les hooks d'action qui peuvent altérer le HTML en cours de test. Assurez-vous de désactiver ou de mocker les actions et filtres globaux qui pourraient influencer le résultat de vos shortcodes ou modules pour isoler le test.

Un autre aspect souvent négligé est la gestion des dépendances CSS et JS dans l'environnement de test, ce qui peut être particulièrement pertinent avec Divi. Les tests devraient idéalement refléter l'environnement de production autant que possible pour éviter des surprises lors du déploiement.

Pour aller plus loin

Une fois que vous maîtrisez assertEqualHTML(), vous pouvez explorer les tests d'intégration en combinant plusieurs shortcodes ou modules pour tester des scénarios utilisateur complexes. Pensez aussi à automatiser la génération de rapports de test avec des outils comme Jenkins ou Travis CI pour une visibilité accrue sur la santé de votre code.

Ressources

FAQ

Pourquoi utiliser assertEqualHTML() ?

Cette méthode permet des comparaisons plus précises du contenu HTML qui peut varier en formatage (espaces, sauts de ligne) mais pas en structure.

Est-ce compatible avec des versions antérieures de WordPress ?

Assurez-vous que votre environnement de test est compatible avec les versions que vous supportez. Cette approche est généralement compatible avec les versions 4.7 et supérieures.

Articles connexes

Envoyer Un Commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Ce site utilise Akismet pour réduire les indésirables. En savoir plus sur la façon dont les données de vos commentaires sont traitées.