Tests E2E pour une intégration WhatsApp : stratégies

Intégrer WhatsApp Business API dans une application marocaine ne s'arrête pas au premier message envoyé avec succès depuis Postman. La vraie question arrive en production : que se passe-t-il quand Meta change un statut de template, quand le BSP réponds avec un code d'erreur inattendu, ou quand le webhook arrive avant même la réponse HTTP de l'appel API ? Les tests end-to-end (E2E) sont la seule réponse sérieuse. Voici une méthodologie éprouvée par les équipes tech marocaines.

Pourquoi les tests unitaires ne suffisent pas

Un test unitaire vérifie qu'une fonction retourne la bonne valeur en isolation. Or, une intégration WhatsApp fait intervenir au minimum trois systèmes distincts : votre backend, le BSP (ou la Cloud API Meta directement), et le canal webhook de retour. Les vrais bugs surgissent aux jointures : sérialisation JSON incorrecte, header d'authentification manquant, retry incohérent lors d'un 429 (rate limit) Meta, ou race condition entre la réponse synchrone et le webhook asynchrone.

Les scénarios qui cassent en production

• Un OTP envoyé deux fois car le webhook delivered arrive après un timeout de 30 secondes.
• Un template rejeté par Meta après un changement de politique (catégorie Marketing reclassée en Utility).
• Un numéro client non-WhatsApp qui déclenche une erreur 131026 mais n'est pas basculé sur SMS.
• Une signature X-Hub-Signature-256 mal validée qui laisse passer des webhooks frauduleux.

Construire un environnement de test réaliste

Le mode sandbox Meta

Meta fournit un environnement de test gratuit via le Meta Business Manager. Un numéro de test préconfiguré permet d'envoyer jusqu'à quelques centaines de messages par jour vers 5 numéros vérifiés, avec de vrais templates approuvés. Idéal pour valider la mécanique de bout en bout sans consommer de crédits.

Le mock BSP

Pour les tests automatisés en CI, on ne peut pas dépendre du réseau. Un serveur mock (WireMock, MSW ou un simple Express) reproduit fidèlement les endpoints du BSP : réponses 200 avec message_id, erreurs 400/429/500, latence variable simulée. Chaque scénario métier possède son propre stub.

Un émetteur de webhooks contrôlé

Le testeur E2E doit pouvoir déclencher à la demande les événements sent, delivered, read, failed. Un petit outil interne qui poste vers votre endpoint webhook avec la bonne signature HMAC permet de rejouer n'importe quel scénario en quelques millisecondes.

Les scénarios E2E incontournables

Parcours OTP nominal

1. L'utilisateur saisit son numéro sur le site.
2. Le backend appelle l'API WhatsApp du BSP.
3. Le webhook sent puis delivered arrive dans les 5 secondes.
4. L'utilisateur saisit le code, la vérification côté serveur passe.

Ce test valide toute la chaîne heureuse — il doit tourner à chaque commit.

Parcours SMS Failback

Simuler un statut failed avec code 131026 (numéro non-WhatsApp) et vérifier que le SMS de secours part dans les 2 secondes vers IAM, Orange ou Inwi. Un test crucial pour tout e-commerce marocain sérieux.

Parcours rate limit

Simuler une réponse 429 avec header Retry-After. Le backend doit respecter le délai, retenter avec un backoff exponentiel, et logger l'incident. Sans ce test, une campagne massive peut se transformer en cascade d'erreurs silencieuses.

Parcours webhook dupliqué

Meta peut renvoyer le même webhook plusieurs fois. Le test vérifie que le système est idempotent : deux delivered pour le même message_id ne doivent pas déclencher deux mises à jour métier.

Intégration dans la CI/CD

Les tests E2E tournent typiquement en trois niveaux dans un pipeline moderne :

• Sur chaque pull request : suite rapide (~2 minutes) contre les mocks BSP.
• Sur merge vers develop : suite complète (~10 minutes) contre le sandbox Meta.
• Nuitammment (nightly) : tests de charge, scénarios exotiques, vérification des templates approuvés en production.

Un critère de blocage clair (bloquer le merge si un scénario OTP nominal échoue) évite les régressions silencieuses. Les frameworks populaires au Maroc pour cette orchestration : Playwright ou Cypress pour la partie UI, Jest ou Vitest pour l'orchestration API, GitHub Actions ou GitLab CI pour l'exécution.

Conclusion

Une intégration WhatsApp Business API sans tests E2E, c'est un pont sans garde-fous : elle tient tant que rien ne bouge. Investir 2 à 3 jours en amont pour construire un harnais de tests réaliste évite des semaines de firefighting en production, protège les OTP critiques des utilisateurs finaux et rassure les équipes lors des mises à jour Meta trimestrielles.