Tester des transformations de blocs Gutenberg automatiquement

Un bloc « Citation mise en avant » que nous avons développé pour un client média propose une transformation vers le bloc core/quote natif, pratique pour les rédacteurs qui changent d’avis sur la mise en forme d’un encart. Après une mise à jour de l’extension, un rédacteur a signalé que la transformation supprimait silencieusement l’attribution de la citation. Personne n’avait cliqué manuellement sur « Transformer en » depuis des semaines ; le bug dormait depuis la dernière modification des attributs du bloc.

Une transformation de bloc est du code JavaScript ordinaire, testable comme n’importe quelle fonction pure — encore faut-il l’appeler dans le bon contexte, celui de l’API de blocs elle-même.

Comprendre la mécanique de switchToBlockType

Le paquet @wordpress/blocks expose switchToBlockType(), la fonction que l’éditeur appelle en coulisses quand un utilisateur choisit une transformation dans l’interface. L’appeler directement dans un test Jest permet de vérifier le résultat sans jamais ouvrir de navigateur :

import { createBlock } from '@wordpress/blocks';
import { switchToBlockType } from '@wordpress/blocks';
import './index'; // enregistre le bloc et ses transformations

describe('transformation citation-mise-en-avant vers core/quote', () => {
    it('conserve le texte et l'attribution', () => {
        const blocOrigine = createBlock('mon-theme/citation-mise-en-avant', {
            texte: 'La qualité ne s'improvise pas.',
            auteur: 'Julie Mercier',
        });

        const [blocTransforme] = switchToBlockType(blocOrigine, 'core/quote');

        expect(blocTransforme.name).toBe('core/quote');
        expect(blocTransforme.attributes.value).toContain('La qualité ne s\'improvise pas.');
        expect(blocTransforme.attributes.citation).toBe('Julie Mercier');
    });
});

Déclarer la transformation testée dans le bloc

Pour mémoire, ce test vérifie une transformation déclarée côté bloc source, dans son fichier transforms.js :

const transforms = {
    to: [
        {
            type: 'block',
            blocks: ['core/quote'],
            transform: (attributes) => {
                return createBlock('core/quote', {
                    value: `<p>${attributes.texte}</p>`,
                    citation: attributes.auteur,
                });
            },
        },
    ],
};

export default transforms;

C’est précisément cette fonction transform que le test précédent exécute indirectement via switchToBlockType() — un test qui appellerait directement la fonction sans passer par l’API publique manquerait les vérifications de compatibilité que WordPress effectue avant d’autoriser la conversion.

Ne pas oublier le sens inverse

Une transformation bidirectionnelle déclare aussi un bloc from, qui permet de convertir un core/quote existant vers le bloc personnalisé — un scénario tout aussi fréquent quand un rédacteur veut enrichir une citation simple avec la mise en forme du thème :

it('convertit un core/quote existant sans perte', () => {
    const quoteOrigine = createBlock('core/quote', {
        value: '<p>Testez toujours les deux sens.</p>',
        citation: 'Notre équipe qualité',
    });

    const [blocTransforme] = switchToBlockType(quoteOrigine, 'mon-theme/citation-mise-en-avant');

    expect(blocTransforme.attributes.auteur).toBe('Notre équipe qualité');
    expect(blocTransforme.attributes.texte).toContain('Testez toujours les deux sens.');
});

Cas limites à ne pas négliger

• Une citation sans attribution renseignée : la transformation ne doit pas planter sur un attribut vide, ni insérer la chaîne littérale undefined dans le résultat.
• Un texte contenant du HTML enrichi (gras, lien) : vérifier que la conversion ne dépouille pas le balisage interne si le bloc cible l’accepte.
• Plusieurs citations imbriquées sélectionnées en bloc multiple : switchToBlockType peut recevoir un tableau de blocs, pas seulement un bloc isolé.

Une transformation non testée reste, dans les faits, une fonctionnalité non maintenue : personne ne la revérifie manuellement à chaque changement d’attribut, jusqu’au jour où un rédacteur la découvre cassée en production.

Intégrer ce test à la suite existante

Ces tests s’exécutent avec wp-scripts test-unit-js, au même titre que les tests de rendu du bloc, sans configuration supplémentaire dès lors que le paquet @wordpress/blocks est déjà une dépendance du projet. Il est recommandé de les placer dans un fichier transforms.test.js dédié, séparé du test de rendu visuel du bloc, pour que l’intention du test reste immédiatement lisible dans l’arborescence.

En résumé

Tester une transformation de bloc ne demande ni navigateur ni capture d’écran : switchToBlockType() suffit à reproduire fidèlement ce que l’éditeur exécute lors d’un clic utilisateur. Sur un projet où les blocs personnalisés évoluent souvent, ce test devient la seule garantie fiable qu’une conversion annoncée dans l’interface fonctionne réellement, sans dépendre de la mémoire de quelqu’un qui se souviendrait avoir testé la fonctionnalité « il y a quelques semaines ».