Le problème commence lorsqu’un partenaire accepte une requête puis coupe la connexion, renvoie deux fois le même événement, modifie un champ sans préavis, ralentit uniquement à certaines heures ou présente un état différent entre API et portail. Le support ne sait plus s’il faut relancer, l’utilisateur voit un statut périmé et un test qui ne simule que succès et code 500 ne couvre pas cette douleur.
La thèse est que l’application doit être testée autour de l’incertitude, pas autour de la disponibilité supposée du partenaire. L’équipe distingue ce qu’elle sait, ce qu’elle peut relire et ce qu’elle doit rapprocher. Elle prouve ensuite qu’une panne ne transforme pas une intention unique en effets multiples et qu’un opérateur peut reprendre sans bricoler la base.
Contre-intuitivement, appeler la vraie sandbox à chaque exécution rend souvent la suite moins réaliste. Une sandbox stable, lente et partagée ne permet pas de déclencher précisément une coupure après réception. Un fake pilotable couvre cette causalité ; quelques tests de contrat et passages réels protègent ensuite contre la dérive.
Pour une application web métier connectée à un SI externe, la qualité de l’intégration se mesure à sa capacité à expliquer et reprendre les états ambigus. La stratégie associe tests pilotables, seuils qualifiés et runbook afin de rester utile même lorsque le partenaire échappe à votre gouvernance.
Définir la fiabilité sans exiger l’impossible
Le mot fiable doit devenir observable : délai de réponse, taux de refus, cohérence de lecture, ordre des événements, délai de webhook et stabilité du schéma. L’équipe mesure une baseline sur son propre trafic, par parcours et par période. Elle évite d’imposer un chiffre universel à une dépendance qu’elle ne contrôle pas.
La promesse interne demeure pourtant claire. Si l’expédition partenaire est indisponible, le portail doit conserver la commande, signaler l’attente et empêcher le double envoi. La disponibilité de la fonction utilisateur peut donc être supérieure à celle de l’écriture externe grâce à la file, à la lecture différée et au mode dégradé.
Les seuils sont locaux. Par exemple, trois erreurs consécutives peuvent ouvrir un circuit dans un service peu fréquent, alors qu’un flux massif utilisera une fenêtre et un ratio. L’équipe documente la raison, l’effet attendu et la date de révision ; elle ne présente pas ce réglage comme une bonne pratique valable partout.
Séparer contrat documenté et comportement observé
Le contrat documenté décrit URL, authentification, schéma, codes et règles de répétition. Le comportement observé révèle parfois des nuances : champ absent au lieu de null, succès asynchrone, limite non documentée ou date dans un fuseau différent. Les deux sont conservés sans normaliser silencieusement l’écart.
Un adaptateur traduit le langage partenaire vers le domaine. Il valide les entrées, classe les réponses et empêche que les détails externes se propagent dans le métier. Une réponse inconnue devient un verdict explicite, pas un objet partiellement rempli accepté par hasard.
Chaque hypothèse reçoit une preuve : documentation primaire, test de contrat ou observation datée. Si seule une expérience de sandbox justifie une règle, l’équipe la marque comme fragile et crée une alerte de dérive. Cette prudence évite de transformer un accident historique en vérité fonctionnelle.
Cartographier les pannes qui changent une décision
La matrice commence par les effets : paiement, réservation, expédition, identité, document ou simple lecture. Elle note ensuite les moments de panne : avant envoi, pendant transfert, après réception, après effet et pendant la réponse. Un même timeout n’a pas la même signification à ces cinq endroits.
Les scénarios couvrent aussi authentification expirée, quota, réponse invalide, ordre inversé, doublon, événement perdu et indisponibilité prolongée. L’équipe sélectionne ceux qui modifient la décision de retry, de compensation ou d’escalade. Tester toutes les combinaisons sans hiérarchie épuiserait la maintenance.
Un signal faible mérite attention lorsqu’un opérateur consulte le portail partenaire avant chaque relance. Ce détour indique que l’application ne porte pas l’état ou la preuve nécessaires. Le test doit alors inclure la lecture et la décision humaine, pas seulement le client HTTP.
Construire un harnais de test pilotable
Le harnais contrôle délai, code, corps, coupure, répétition et ordre. Un scénario se configure par intention plutôt que par bricolage réseau : « accepter puis couper », « répondre 429 trois fois », « envoyer l’événement B avant A ». Sa configuration voyage avec le test et produit une trace lisible.
Le fake ne recode pas tout le partenaire. Il implémente les comportements qui influencent votre décision et refuse le reste. Plus il accumule de règles métier externes, plus il devient un second produit qui peut partager la même erreur que l’adaptateur.
Le démarrage remet l’état à zéro ou utilise un espace isolé. Les tests parallèles possèdent des clés distinctes. La sortie du harnais indique les requêtes reçues et effets simulés, sans exposer secret ou donnée personnelle. Un échec peut ainsi être reproduit par un autre développeur.
Tester le timeout après réception
La panne la plus dangereuse survient lorsque le partenaire a reçu et traité, mais que la réponse n’arrive pas. Le client ne sait pas si l’écriture existe. Relancer automatiquement sans clé ni lecture peut doubler une facture ou une expédition.
Le test coupe la connexion après l’enregistrement simulé. L’application conserve l’intention et passe en état « à confirmer ». Elle utilise une clé stable, interroge une ressource de lecture ou attend l’événement correspondant. Si aucune preuve n’existe, elle escalade au lieu de déclarer arbitrairement succès ou échec.
Le budget de timeout vient de mesures locales et de l’expérience utilisateur. Le réduire peut libérer des ressources mais augmente les états ambigus ; l’allonger peut bloquer les workers. Le test vérifie la décision après dépassement, pas seulement la durée exacte.
Prouver l’idempotence et les doublons
Une clé d’idempotence représente l’intention métier, pas la tentative réseau. Elle reste identique lors d’un retry et change lorsque l’utilisateur crée une nouvelle opération légitime. Le serveur ou l’adaptateur conserve le résultat associé pendant une durée cohérente avec les répétitions possibles.
Le scénario envoie deux requêtes concurrentes, répète après timeout et redémarre le worker entre les deux. Il attend un effet unique et un résultat compatible. Une contrainte de base ou un verrou qualifié complète la logique ; un simple « déjà vu » en mémoire ne survit pas au run.
Lorsque le partenaire ne fournit aucune idempotence, l’application combine référence externe stable, lecture avant écriture et rapprochement. Le test doit accepter qu’une garantie exactement-once soit impossible et prouver plutôt l’absence de doublon visible ou la détection rapide.
Couvrir formats, volumes et dérive de schéma
Les fixtures incluent champ absent, valeur inconnue, caractères non ASCII, décimale, date de changement d’heure et collection vide. Elles proviennent de contrats nettoyés ou sont synthétiques. Une copie brute d’échange réel peut contenir des données sensibles et vieillir sans révéler son origine.
Le parseur refuse ou met en quarantaine selon l’impact. Il ne convertit pas une valeur inconnue en zéro pour sauver le traitement. Les messages d’erreur indiquent champ et version sans journaliser la charge complète. Le test confirme aussi que les anciens formats restent lisibles pendant la fenêtre de migration décidée.
Un volume représentatif cible les chemins sensibles. Par exemple, cinq mille lignes peuvent être choisies parce qu’un partenaire pagine et qu’un incident est apparu à ce niveau. Ce seuil local est associé à la requête et au budget ; il n’est pas extrapolé comme norme.
Rendre quotas et backpressure visibles
Le code 429 ne signifie pas « réessayer très vite ». Le client respecte l’indication de délai si elle est valide, ajoute une dispersion et plafonne les tentatives. La file protège le partenaire et l’application contre une reprise synchronisée de milliers de messages.
Le test simule quota court, quota prolongé et réponse sans instruction. Il vérifie que les nouveaux travaux ralentissent, que les urgences éventuelles conservent leur voie autorisée et que l’âge du plus ancien message déclenche une décision opérateur.
Le seuil d’alerte dépend de la promesse. Un âge de quinze minutes peut être acceptable pour un export nocturne et critique pour une confirmation de stock. Le tableau associe donc âge, type d’intention et volume, plutôt qu’un unique taux d’erreurs.
Éprouver webhooks désordonnés et répétés
Un webhook est une notification, pas toujours la source finale de vérité. Il peut être répété, retardé ou reçu dans le désordre. Le récepteur authentifie, conserve un identifiant, répond rapidement et traite en asynchrone lorsque la durée dépasse le budget de l’émetteur.
Le test envoie le même événement deux fois, l’événement final avant l’intermédiaire et une signature expirée. La transition métier refuse la régression d’état illégitime. Si le partenaire expose une lecture, une réconciliation périodique ferme les événements manquants.
La preuve relie identifiant externe, type, horodatage partenaire, réception et décision interne. Elle évite de journaliser tout le contenu par défaut. Un opérateur peut distinguer événement ignoré, appliqué, mis en attente ou rejeté.
Cas concret : expédition au statut inconnu
Un portail transmet une demande d’expédition à un transporteur. Le partenaire enregistre l’étiquette puis coupe la réponse. Le premier worker marque une erreur ; un second reprend et envoie à nouveau. Deux étiquettes facturées apparaissent alors que la commande n’en affiche qu’une.
L’équipe introduit une intention d’expédition persistée avant l’appel, avec clé stable. Le fake accepte la première requête, crée une référence puis coupe. Au retry, l’adaptateur consulte par clé client ; s’il retrouve la référence, il attache le résultat sans nouvel envoi.
Si la lecture reste indisponible au-delà du budget local de dix minutes, la commande passe en rapprochement manuel. Ce délai vient de la promesse de préparation de ce site, pas d’un standard transport. Le support voit les tentatives, la dernière preuve et l’action autorisée.
Le scénario final redémarre le worker, répète le webhook et restaure le partenaire. Il prouve un effet unique, un diagnostic compréhensible et une reprise sans SQL manuel. La qualité se mesure au contrôle de l’incertitude, pas à l’absence artificielle d’erreur.
Organiser les tests de contrat
Le consommateur encode les requêtes qu’il produit et les réponses qu’il sait interpréter. Le fournisseur ou une vérification sur spécification confirme leur compatibilité. Ces tests détectent une dérive plus tôt qu’un parcours complet, sans prétendre valider les règles métier internes du partenaire.
Les exemples sont versionnés et minimaux. Un champ optionnel nouveau ne bloque pas si le parseur l’ignore ; la suppression d’un champ requis échoue. La compatibilité est jugée selon l’usage réel, pas selon l’égalité textuelle de toute la charge.
À chaque changement, l’équipe sait qui contacte le partenaire, quelle ancienne version reste supportée et comment activer le fallback. Le contrat produit une alerte actionnable ; il ne remplace ni sandbox ni supervision en production.
Donner une mission limitée à la sandbox
La sandbox vérifie authentification, réseau, exemples réels et comportements impossibles à simuler avec confiance. Elle ne devrait pas être la dépendance de tous les tests. Son état partagé, ses quotas et sa disponibilité rendent les résultats difficiles à attribuer.
Une petite suite planifiée utilise des identifiants isolés et nettoyables. Elle conserve version, compte, réponse et différence avec le contrat. Une indisponibilité de sandbox produit un verdict d’environnement, pas une régression du produit.
Avant mise en production, un scénario bout en bout confirme la configuration et les droits. Il n’est pas présenté comme preuve de tous les modes dégradés : ceux-ci ont déjà été provoqués de manière déterministe dans le harnais.
Observer l’intégration par intention
Les métriques séparent appels et intentions. Dix retries pour une intention ne doivent pas sembler dix opérations métier. Le tableau montre succès confirmés, états inconnus, âges de file, rapprochements et erreurs classées par partenaire.
Les logs contiennent identifiant de corrélation, clé d’intention masquée si nécessaire, tentative, classe de résultat et prochaine action. Ils excluent jetons et charges sensibles. Une trace technique sans état métier oblige le support à reconstruire la causalité.
Les alertes portent sur une décision : ouvrir le circuit, ralentir, escalader ou rapprocher. Un pic bref de codes 500 peut ne rien exiger si les retries réussissent ; un seul paiement ambigu peut au contraire demander une action immédiate.
Implémenter les dépendances et le repli
Entrées, sorties, propriétaires
L’entrée est une intention persistée avec sa version et sa clé. La sortie est un succès confirmé, un refus certain ou un état inconnu. L’adaptateur possède traduction et timeouts ; le domaine possède transitions ; la plateforme possède file et secrets ; le run possède rapprochement. Les dépendances et seuils restent configurés par partenaire.
La journalisation corrèle sans dupliquer la charge. Les responsabilités de repli distinguent lecture, fonctionnalité réduite et escalade ; elles n’inventent pas un succès. Le rollback de code préserve les anciennes intentions, et les dépendances restent compatibles afin que le worker précédent les lise pendant la fenêtre définie.
Tests de reprise
La suite arrête le processus après persistance, après envoi et après réception. Elle redémarre avec la même file, vérifie verrous, contraintes et checkpoints, puis rejoue. Le résultat doit rester explicable même si deux versions de worker se croisent pendant le déploiement.
Tester réconciliation et reprise opérateur
La réconciliation compare intentions internes et états externes sur une fenêtre bornée. Elle produit des catégories : confirmé, absent, contradictoire ou impossible à lire. Elle ne corrige pas silencieusement une conséquence financière sans règle approuvée.
Le runbook indique qui peut relancer, annuler, compenser ou contacter le partenaire. Chaque action est idempotente, journalisée et prévisualisable si son impact est important. Une procédure qui dépend d’une modification directe de base échoue au test de reprise.
Un exercice trimestriel ou après changement majeur peut suffire selon le risque. L’équipe mesure le délai de détection et le délai de fermeture, puis ajuste données et outils. Elle ne transforme pas la fréquence en rituel universel.
Reconnaître les équipes concernées
Cette méthode vise les produits qui dépendent d’ERP, paiement, logistique, identité, CRM ou services publics. Elle devient prioritaire lorsque les opérateurs relancent manuellement, que les incidents restent « chez le partenaire » ou qu’aucun état interne n’explique ce qui s’est passé.
Une intégration de lecture non critique peut se contenter d’un cache et d’un message clair. Une écriture irréversible exige intention, idempotence et rapprochement. Le niveau de dispositif suit l’effet, pas le prestige technique de l’API.
Pour un prototype, quelques scénarios pilotables suffisent. Le contrat doit néanmoins signaler ses garanties limitées, afin qu’un flux expérimental ne devienne pas un processus critique sans reprise.
Éviter les faux tests d’intégration
- Simuler seulement 200 et 500. Les timeouts ambigus, quotas, doublons et dérives portent souvent le vrai risque.
- Utiliser la sandbox comme oracle unique. Elle ne déclenche pas les pannes voulues et son état partagé rend le diagnostic fragile.
- Relancer toute erreur. Un refus fonctionnel ou une authentification invalide demande une correction, pas davantage de charge.
- Confondre requête et intention. Les métriques gonflent et les doublons deviennent invisibles.
- Journaliser les charges complètes. Le diagnostic gagne peu tandis que secrets et données se diffusent.
- Tester sans reprise. Un code d’erreur correctement géré ne suffit pas si le support doit bricoler l’état.
Arbitrer la mise en production
Le go dépend de l’effet. Si une écriture irréversible peut rester inconnue sans lecture, clé ni rapprochement, alors la mise en production est bloquée ou le périmètre réduit. Si seule une lecture secondaire est indisponible et qu’un cache daté existe, le mode dégradé peut être acceptable.
La matrice croise certitude du résultat, possibilité de retry, compensation, visibilité opérateur et âge maximal. « Si inconnu et irréversible, alors escalader » est un arbitrage. « Toujours trois retries » n’en est pas un. Les délais et volumes sont établis sur la baseline locale.
À éviter : promettre une disponibilité supérieure sans file ni état. À privilégier : un contrat interne plus prudent que le marketing partenaire, une preuve déterministe et un exercice de reprise avant d’élargir.
- À bloquer : une écriture irréversible sans lecture ni rapprochement.
- À valider : le mode dégradé et les droits de reprise avant le go.
- À documenter : toute hypothèse issue seulement de la sandbox.
- À différer : l’extension tant que l’état inconnu ne possède pas de propriétaire.
Plan d’action : sécuriser une intégration en huit semaines
Semaines 1 et 2 : exposer l’incertitude
L’équipe inventorie intentions, effets et états actuels. Elle relit incidents et manipulations du support, puis dessine cinq moments de panne pour le parcours prioritaire. La baseline relève délais, retries, états inconnus et âge de file. Chaque hypothèse de contrat pointe vers une source ou une observation datée.
Elle choisit un propriétaire métier, un propriétaire d’adaptateur et un responsable de reprise. Le vocabulaire confirmé, refusé et inconnu devient commun aux écrans, événements et logs.
Semaines 3 à 5 : provoquer et protéger
Le harnais implémente timeout après réception, quota, doublon, désordre et dérive de champ. L’intention persistée, la clé stable et la lecture de confirmation couvrent l’écriture critique. Les tests arrêtent puis redémarrent le worker aux frontières.
Une petite suite de contrat et un passage sandbox vérifient que le fake n’a pas dérivé. Le tableau distingue intention et tentative. Un collègue extérieur reproduit un état inconnu sans aide orale.
Semaines 6 à 8 : fermer le run
La réconciliation classe un échantillon et le support joue les actions autorisées. L’équipe simule indisponibilité prolongée, restauration et reprise progressive sous quota. Les seuils sont ajustés à partir des temps observés et de la promesse locale.
Le périmètre s’élargit uniquement si aucun effet double n’apparaît, si l’état inconnu est visible et si la reprise fonctionne sans SQL. Sinon la fonctionnalité reste bornée et la lacune devient une condition explicite du prochain go.
Consulter les références et approfondissements
La documentation officielle du client HTTP Symfony couvre timeouts, concurrence et gestion des réponses. La sémantique des méthodes, codes et répétitions est définie dans la RFC 9110 publiée par l’IETF.
Pour les contrats automatisés, la documentation officielle Pact explique les responsabilités consommateur-fournisseur. Ces outils ne remplacent pas la qualification métier de l’état inconnu, mais ils rendent les hypothèses testables.
Le test des workflows à exceptions aide à construire les pannes, tandis que leur observabilité relie l’intention au run. La surveillance d’une application métier complète les seuils et alertes.
Conclusion : concevoir pour l’état inconnu
Tester un partenaire peu fiable consiste à maîtriser ce que votre produit décide lorsque la réponse manque. Les scénarios de succès et d’erreur certaine sont nécessaires ; le timeout après effet, le doublon et la dérive sont souvent plus révélateurs.
Un fake pilotable provoque les causalités, les contrats surveillent la compatibilité et la sandbox confirme quelques hypothèses réelles. L’intention, la clé et la réconciliation protègent ensuite le run contre les certitudes inventées.
Commencez par l’écriture dont un doublon coûterait le plus cher. Coupez la réponse après réception, redémarrez le worker et demandez au support de fermer le cas. Les données qui manquent à cette reprise dessinent le bon backlog.
Si vos intégrations restent impossibles à diagnostiquer dès qu’un partenaire ralentit, Dawap peut vous accompagner pour construire une application web métier résiliente et exploitable.
