wp-env valide un endpoint REST maison avant de le brancher au front

npx wp-env start. Trois mots qui évitent à un développeur indépendant travaillant seul sur la refonte d’un site de location de matériel photo de polluer sa machine avec une installation MySQL locale juste pour tester un endpoint REST. C’était le point de départ de ce chantier : avant d’écrire la moindre ligne de front, il fallait un endpoint fiable, testable en isolation, et reproductible sur n’importe quelle machine si un autre développeur rejoignait le projet plus tard.

Le contexte : une plateforme de location de matériel photographique entre particuliers avait besoin d’un catalogue d’annonces consultable par une application mobile développée séparément. Plutôt que de brancher l’application directement sur un WordPress de développement partagé et fragile, la décision a été de construire d’abord l’endpoint dans un environnement jetable, de le valider seul, puis seulement ensuite de le communiquer à l’équipe mobile.

Installer wp-env sans dépendances superflues

wp-env repose sur Docker et ne nécessite qu’un fichier .wp-env.json à la racine du projet pour définir la version de WordPress, les plugins actifs et les thèmes chargés. Aucune configuration serveur, aucun réglage de base de données à la main.

{
    "core": "WordPress/WordPress#6.1",
    "plugins": [ "./plugins/annonces-materiel" ],
    "themes": [],
    "config": {
        "WP_DEBUG": true
    }
}

Le plugin annonces-materiel contient tout le code métier : le type de contenu annonce, ses champs personnalisés et l’endpoint REST dédié. Le placer dans un plugin plutôt que dans un thème garantit qu’il pourra être réutilisé tel quel, indépendamment du thème d’administration finalement choisi.

Construire puis tester l’endpoint en isolation

L’endpoint personnalisé, déclaré via register_rest_route(), retourne les annonces disponibles filtrées par ville et par catégorie de matériel, avec une validation stricte des paramètres d’entrée :

add_action( 'rest_api_init', function () {
    register_rest_route( 'location/v1', '/annonces', array(
        'methods'  => 'GET',
        'callback' => 'lm_get_annonces_disponibles',
        'permission_callback' => '__return_true',
        'args' => array(
            'ville' => array(
                'type'              => 'string',
                'sanitize_callback' => 'sanitize_text_field',
            ),
            'categorie' => array(
                'type'              => 'string',
                'validate_callback' => function ( $value ) {
                    return term_exists( $value, 'categorie_materiel' );
                },
            ),
        ),
    ) );
} );

Avec wp-env lancé, l’endpoint est immédiatement disponible sur http://localhost:8888/wp-json/location/v1/annonces. La commande wp-env run cli wp db import a permis d’injecter un jeu de vingt annonces de démonstration, avec des dates de disponibilité volontairement variées pour tester les cas limites du filtre par ville.

Les trois commandes du quotidien

• npx wp-env start démarre les conteneurs et affiche les ports d’accès
• npx wp-env run cli wp annonce list --format=table vérifie que les contenus de test sont bien présents
• npx wp-env stop arrête tout sans laisser de service tourner en arrière-plan

Chaque scénario de test a été rejoué à la main avec un client HTTP en ligne de commande, avant même d’ouvrir un éditeur de code côté front : ville existante avec résultats, ville inexistante, catégorie invalide, absence de paramètre. Cette étape a permis de repérer que le validate_callback sur categorie renvoyait une erreur 500 au lieu d’une réponse 400 propre lorsque le terme n’existait pas, un détail qui aurait été bien plus pénible à diagnostiquer une fois le code du front écrit autour de l’endpoint.

Tester un endpoint avant d’écrire le front qui le consomme change la nature des bugs qu’on trouve : on cherche des erreurs de contrat d’API, pas des erreurs d’affichage. Les deux catégories ne se corrigent pas de la même façon ni avec la même urgence.

Ce qui reste hors du périmètre

Les tests de bout en bout de l’application mobile ne font pas partie de cette étape : une fois l’endpoint validé et documenté, l’équipe mobile a repris la main pour ses propres suites de tests, avec ses propres outils. Confondre les deux niveaux de test aurait ralenti inutilement la validation de l’API, qui devait rester la priorité avant toute intégration front.

Pour aller plus loin

wp-env n’est pas un outil réservé aux mainteneurs du cœur de WordPress : pour un développeur indépendant, il offre un moyen rapide de garantir qu’un endpoint fonctionne de façon identique chez lui, chez un collègue ou en intégration continue. Le gain principal n’est pas la vitesse de démarrage, mais la certitude qu’un bug constaté plus tard ne viendra pas d’une différence d’environnement local.