Critères d'acceptation d'intégration : définir le fini pour les builds partenaires

Deux ingénieurs, un de chaque côté d'une intégration partenaire, croient tous deux avoir fini. L'un dit que la synchronisation des contacts marche : il a créé un contact et il est apparu dans l'autre système. L'autre dit que non : elle a modifié un contact et rien ne s'est passé, puis en a supprimé un et il est resté. Les deux décrivent la même intégration, et les deux disent la vérité sur ce qu'ils ont testé. Le désaccord ne porte pas sur le code. C'est que personne n'a écrit ce que "fini" veut dire pour cette intégration, alors chaque ingénieur a comblé le vide avec sa propre définition, et les deux définitions ne correspondent pas.

Les critères d'acceptation d'intégration sont la définition écrite du fini qui empêche exactement cela. Ce sont les conditions précises et testables qui doivent être vraies avant qu'une intégration ne compte comme complète, convenues par les deux côtés avant que le build ne commence plutôt que débattues après sa livraison. Là où une user story dit à qui l'intégration est destinée et pourquoi, les critères d'acceptation disent précisément ce qui doit marcher, y compris tous les cas que la démo du parcours idéal saute discrètement : les mises à jour, les suppressions, les erreurs, les états vides, et le volume qu'un vrai client poussera réellement à travers.

Ce guide porte sur écrire ces critères correctement pour un build partenaire, où "fini" est plus difficile car deux équipes doivent en convenir. Nous couvrons ce que sont les critères d'acceptation et en quoi ils diffèrent d'une user story, l'anatomie d'un bon critère, les cas limites que les équipes oublient de façon fiable, comment gérer le fait que les deux côtés doivent accepter, et une checklist réutilisable que vous pouvez appliquer à toute intégration. À la fin, vous obtenez une checklist de critères que vous pouvez adapter à votre prochain build.

L'essentiel en 60 secondes

Si vous ne lisez qu'une section, lisez celle-ci :

• Les critères d'acceptation sont la définition écrite et testable du fini. Ils listent les conditions précises qui doivent être vraies pour que l'intégration compte comme complète, pour que "fini" soit un fait que les deux côtés ont vérifié, pas une opinion.
• Ce n'est pas la user story. La story dit qui et pourquoi ; les critères disent exactement ce qui doit marcher. La story est humaine et lisible ; les critères sont précis et vérifiables.
• Un bon critère est testable et sans ambiguïté. "Les contacts se synchronisent de façon fiable" n'est pas un critère ; "un contact créé dans A apparaît dans B en moins de 60 secondes" en est un, car vous pouvez le lancer et obtenir un oui ou un non.
• Les cas limites sont là où les intégrations cassent. Les mises à jour, suppressions, doublons, erreurs, états vides, et le volume sont les cas que la démo du parcours idéal saute et que le client rencontre en semaine un.
• Les deux côtés doivent accepter. Une intégration n'est finie que quand les deux équipes vérifient leur moitié face aux critères convenus, ce qui explique pourquoi les critères doivent être écrits et partagés, pas gardés dans la tête d'une seule équipe.
• Écrivez les critères avant le build, pas après. Des critères convenus d'emblée sont une spec ; des critères inventés après une démo sont une dispute sur si le travail est fini.

Ce que sont les critères d'acceptation, et en quoi ils diffèrent d'une user story

Les critères d'acceptation sont l'ensemble de conditions qu'un travail doit satisfaire pour être accepté comme complet. Ils traduisent l'intention d'une user story en énoncés précis et vérifiables, pour que "fini" cesse d'être un jugement et devienne un test que n'importe qui peut lancer. Le concept vient directement des tests d'acceptation en logiciel : avant de pouvoir dire qu'une fonctionnalité marche, il vous faut un standard écrit de ce que "marche" veut dire, et les critères d'acceptation sont ce standard exprimé en conditions que le build satisfait ou non.

La distinction avec une user story vaut la peine d'être énoncée clairement, car les équipes qui la brouillent se brûlent. Une user story est la description humaine et lisible de qui veut quoi et pourquoi : "en tant que commercial, je veux que les nouveaux contacts se synchronisent vers mon CRM, afin de relancer vite". Cette story est essentielle pour garder le travail centré sur le client, et nous couvrons leur écriture dans user stories d'intégration. Mais elle n'est pas testable en soi. Que veut dire "synchroniser" ? Dans quelle direction ? À quelle vitesse ? Et les mises à jour ? Les critères d'acceptation répondent à tout cela, transformant l'intention de la story en conditions que la QA peut vérifier une par une.

Le modèle mental est que la story et les critères sont deux couches de la même exigence. La story garde tout le monde ancré au but du client ; les critères rendent ce but vérifiable. Vous avez besoin des deux, et vous devez les garder distincts : une story surchargée de conditions techniques devient illisible pour la conversation partenaire, et des critères écrits sans story perdent le fil de pourquoi tout cela compte. Écrivez la story d'abord pour établir le qui et le pourquoi, puis décomposez-la en critères qui fixent le quoi.

L'anatomie d'un bon critère d'acceptation

Toute phrase qui sonne comme une exigence n'est pas un critère d'acceptation utilisable. Les deux propriétés qui séparent un vrai critère d'une aspiration vague sont qu'il est testable et qu'il est sans ambiguïté. Testable signifie que vous pouvez lancer une vérification et obtenir un oui ou un non clair. Sans ambiguïté signifie que deux personnes le lisant lanceront la même vérification et s'accorderont sur le résultat. "La synchronisation devrait être fiable" échoue aux deux : vous ne pouvez pas tester "fiable" directement, et deux ingénieurs seront en désaccord sur si un comportement donné compte. "Un contact créé dans le système A apparaît dans le système B en moins de 60 secondes, avec nom, e-mail et entreprise renseignés" passe les deux : c'est un test précis et lançable avec une seule bonne réponse.

Un format courant et puissant pour écrire les critères est Given-When-Then (Étant donné-Quand-Alors), emprunté au développement piloté par le comportement. Vous énoncez le contexte de départ, l'action, et le résultat attendu : étant donné qu'un contact existe dans le système A, quand son e-mail est mis à jour, alors le changement apparaît dans le système B en moins de 60 secondes. La structure Given-When-Then est utile précisément parce qu'elle vous force à nommer la précondition et le résultat attendu, qui est là où les critères vagues s'effondrent. Tout critère n'a pas besoin de cette forme exacte, mais tout critère a besoin de ses ingrédients : un contexte, un déclencheur, et un résultat précis et observable.

Il y a une couche de plus que beaucoup d'équipes oublient : les critères non fonctionnels. Au-delà de ce que l'intégration fait, il y a des conditions sur à quel point elle le fait bien, latence, débit, sécurité, et gestion des erreurs, que le client ressent même si aucune fonctionnalité unique ne les capture. Ces exigences non fonctionnelles appartiennent aussi aux critères d'acceptation, car une intégration qui synchronise correctement mais prend dix minutes, ou fuit des données, ou s'écroule au volume réel, n'est pas réellement finie. Quand les données échangées ont une forme définie, encoder ces attentes au niveau du champ, requis versus optionnel, types, formats, est bien plus facile si l'intégration est construite face à un schéma ; un standard comme JSON Schema vous laisse transformer "le payload doit inclure un e-mail valide" d'un critère en prose en un critère vérifiable par machine.

Les cas limites que les équipes oublient de façon fiable

La raison pour laquelle les intégrations passent leur démo et échouent en production est presque toujours la même : la démo montre le parcours idéal, et le parcours idéal est le seul cas qui allait toujours marcher. Un client crée un enregistrement, il apparaît de l'autre côté, tout le monde applaudit. Puis le client fait quelque chose que la démo n'a jamais couvert, modifie un champ, supprime un enregistrement, importe dix mille lignes d'un coup, et l'intégration fait quelque chose de faux ou rien du tout. Les cas limites ne sont pas exotiques ; ce sont les choses ordinaires que les vrais utilisateurs font et que la démo du parcours idéal saute, et ce sont exactement ce que les critères d'acceptation existent pour forcer dans le plan.

Il y a un ensemble reconnaissable de cas limites que les équipes d'intégration oublient encore et encore, ce qui signifie que vous pouvez les transformer en checklist permanente et cesser de les redécouvrir à la dure. Chacun est une question à laquelle les critères doivent répondre avant que le build ne soit accepté :

La discipline est de parcourir cette liste pour chaque intégration et d'écrire un critère pour chaque ligne qui s'applique, même si la réponse est "hors périmètre pour la v1". Un explicite "les suppressions ne sont pas gérées en v1, les enregistrements doivent être retirés manuellement" est un bon critère ; un vide silencieux où personne n'a décidé est la façon dont un client perd des données. Décider ceux-ci à l'avance est aussi ce qui garde le build dans les temps, car les cas limites découverts tard sont la cause classique des dépassements d'intégration, ce qui explique pourquoi ils reçoivent un traitement de premier plan dans la gestion de projet d'intégration. La ligne de gestion des erreurs mérite un soin particulier, puisqu'une API partenaire peut et va retourner des échecs que vous ne contrôlez pas ; notre guide sur la conception des erreurs d'API couvre à quoi ressemble un bon comportement d'erreur des deux côtés de cette frontière.

Gérer l'acceptation quand les deux côtés doivent s'accorder

Une fonctionnalité interne a une équipe qui décide quand elle est finie. Une intégration partenaire en a deux, et cela transforme l'acceptation d'un point de contrôle en une négociation. L'intégration n'est pas complète quand votre côté marche ; elle est complète quand les deux côtés marchent ensemble face à une définition partagée, ce qui signifie que les critères d'acceptation ne peuvent vivre dans la tête d'une seule équipe ou le système de tickets d'une seule équipe. Ils doivent être un artefact partagé que les deux équipes ont revu et accepté avant le build.

Le mode d'échec est prévisible. Votre équipe construit selon votre compréhension du fini, leur équipe construit selon la sienne, et les deux se rencontrent au moment de l'intégration pour découvrir que les définitions n'ont jamais correspondu. Un côté a supposé une synchro temps réel, l'autre a construit un batch nocturne. Un côté gère les suppressions, l'autre non. Aucune équipe n'a tort selon ses propres critères, car il n'y a jamais eu de critères partagés, seulement deux critères privés. Écrire une seule définition du fini que les deux équipes valident avant le build est l'assurance bon marché contre une coûteuse surprise de semaine d'intégration.

Concrètement, cela signifie trois choses. D'abord, les critères sont rédigés conjointement, ou rédigés par un côté et explicitement revus et acceptés par l'autre, pour que les deux sachent vers quoi ils construisent. Ensuite, chaque critère a un propriétaire clair : certains sont la responsabilité de votre côté, certains la leur, et un critère partagé comme "un contact créé dans A apparaît dans B en moins de 60 secondes" a besoin des deux pour le rendre vrai. Enfin, l'acceptation est un acte conjoint : vous testez les critères ensemble, ou chaque côté teste sa moitié et la démontre à l'autre, et alors seulement l'intégration est finie. Ce standard partagé, écrit et accepté conjointement est la même discipline qui rend tout le build prévisible, ce qui explique pourquoi il siège à l'intérieur de la stratégie d'intégration SaaS plus large plutôt que d'être une réflexion après coup à la fin.

Erreurs fréquentes, et comment les corriger

Écrire des critères qui ne sont pas testables. La correction : remplacez chaque adjectif par une mesure. "Fiable", "rapide", et "élégant" ne sont pas des critères ; "se termine en moins de 60 secondes", "réessaie cinq fois avec backoff", et "remonte un message d'erreur précis" en sont. Si vous ne pouvez pas lancer une vérification et obtenir un oui ou un non, ce n'est pas encore un critère.

Confondre la user story avec les critères d'acceptation. La correction : gardez la story humaine et les critères précis, comme deux documents distincts. La story dit qui et pourquoi pour la conversation partenaire ; les critères disent exactement quoi pour l'ingénieur. Surchargez la story et elle devient illisible ; sautez les critères et elle devient inbuildable.

Ne spécifier que le parcours idéal. La correction : parcourez la liste permanente de cas limites, mises à jour, suppressions, doublons, erreurs, données vides, volume, expiration d'auth, et écrivez un critère pour chacun, même si le critère est un explicite "hors périmètre pour la v1". Le parcours idéal marche toujours dans la démo ; les cas limites sont ce que le client rencontre en semaine un.

Ignorer les critères non fonctionnels. La correction : ajoutez des conditions sur la latence, le débit, la sécurité, et la gestion des erreurs, car une intégration fonctionnellement correcte mais lente, non sécurisée, ou fragile au volume n'est pas finie. Le client vit ceux-ci même si aucune fonctionnalité unique ne les nomme.

Laisser chaque côté définir le fini en privé. La correction : écrivez une seule définition du fini partagée que les deux équipes revoient et acceptent avant le build, avec un propriétaire clair par critère. Deux définitions privées garantissent un décalage au moment de l'intégration ; une seule définition partagée et acceptée conjointement est ce qui fait que les deux côtés construisent la même chose.

FAQ

Que sont les critères d'acceptation d'intégration ? Ce sont les conditions précises et testables qui doivent être vraies pour qu'une intégration compte comme finie, convenues par les deux côtés avant le build. Ils traduisent l'intention d'une user story, "les contacts devraient se synchroniser", en énoncés vérifiables comme "un contact créé dans A apparaît dans B en moins de 60 secondes avec nom, e-mail et entreprise renseignés", pour que l'acceptation soit un test que n'importe qui peut lancer plutôt qu'une opinion.

En quoi les critères d'acceptation diffèrent-ils d'une user story ? La user story dit qui veut l'intégration et pourquoi, dans une phrase humaine lisible. Les critères d'acceptation disent exactement ce qui doit marcher, en checklist de conditions testables. La story est pour la conversation partenaire et client ; les critères sont ce contre quoi l'ingénieur et la QA vérifient. Vous avez besoin des deux, gardés comme documents distincts faisant des jobs distincts.

Qu'est-ce qui rend un critère bon ? Il est testable et sans ambiguïté : vous pouvez lancer une vérification et obtenir un oui ou un non clair, et deux personnes le lisant s'accorderont sur le résultat. Remplacez les adjectifs vagues comme "fiable" ou "rapide" par des mesures comme "se termine en moins de 60 secondes". Un format utile est Given-When-Then, qui vous force à énoncer le contexte, le déclencheur, et le résultat observable attendu.

Quels cas limites les critères d'intégration devraient-ils couvrir ? Ceux que la démo du parcours idéal saute et que le client rencontre vite : mises à jour, suppressions, doublons, erreurs et réessais, données vides ou partielles, volume réel, et expiration d'auth ou de token. Parcourez cette liste pour chaque intégration et écrivez un critère pour chaque ligne qui s'applique, même si le critère est un explicite "non géré en v1". Un vide silencieux est la façon dont les clients perdent des données.

Pourquoi les deux côtés doivent-ils accepter une intégration ? Parce qu'une intégration connecte deux produits, et elle n'est pas finie quand seule votre moitié marche. Si chaque équipe construit selon sa propre définition privée du fini, les définitions se rencontrent au moment de l'intégration et s'avèrent ne pas correspondre, un côté a supposé le temps réel, l'autre a construit un batch nocturne. Une seule définition partagée et écrite que les deux équipes acceptent avant le build empêche cette coûteuse surprise.

Les critères d'acceptation devraient-ils inclure les exigences non fonctionnelles ? Oui. Au-delà de ce que l'intégration fait, les critères devraient couvrir à quel point elle le fait bien : latence, débit, sécurité, et gestion des erreurs. Une intégration qui synchronise les bonnes données mais prend dix minutes, fuit de l'information, ou s'effondre au volume réel n'est pas réellement finie, même si chaque critère fonctionnel passe. Le client ressent ces conditions directement.

Quand les critères d'acceptation devraient-ils être écrits ? Avant le build, pas après. Des critères convenus d'emblée sont une spécification vers laquelle les deux équipes construisent ; des critères inventés après une démo sont une dispute sur si le travail est fini. Les écrire d'abord fait aussi remonter les cas limites et les questions de direction et de timing tôt, quand elles sont bon marché à résoudre plutôt que coûteuses à rajouter.

Pour aller plus loin

• Wikipédia, tests d'acceptation, sur le standard écrit qui définit si un build répond à ses exigences.
• Wikipédia, Given-When-Then, sur une structure pour écrire des critères qui nomment le contexte, le déclencheur, et le résultat attendu.
• Wikipédia, définition du fini, sur un standard partagé et explicite de quand un travail est complet.
• Wikipédia, exigence non fonctionnelle, sur les conditions de qualité comme la latence et la sécurité que les critères devraient inclure.
• JSON Schema, json-schema.org, sur transformer les attentes de payload au niveau du champ en conditions vérifiables par machine.

En bref

Les critères d'acceptation d'intégration sont la définition écrite et testable du fini qui empêche deux équipes de finir une intégration avec deux idées différentes de ce que finir veut dire. Là où une user story dit à qui l'intégration est destinée et pourquoi, les critères disent exactement ce qui doit marcher, en conditions que n'importe qui peut lancer et sur lesquelles obtenir un oui ou un non. Un critère qui n'est pas testable et sans ambiguïté n'est pas un critère ; remplacez chaque "fiable" et "rapide" par une mesure.

Les cas qui cassent les intégrations sont ceux que la démo du parcours idéal saute : mises à jour, suppressions, doublons, erreurs, données vides, volume, et expiration d'auth. Parcourez cette liste pour chaque build et écrivez un critère pour chacun, plus les conditions non fonctionnelles comme la latence et la sécurité que le client ressent. Et parce qu'une intégration partenaire a deux côtés, écrivez une seule définition du fini partagée que les deux équipes acceptent avant le build, avec un propriétaire clair par critère, pour que l'acceptation soit un test conjoint face à un standard convenu plutôt qu'une dispute après la démo.

Si vous voulez que tout le chemin soit pris en charge, de la stratégie partenaire et d'une API prête pour les partenaires jusqu'à un travail d'intégration périmétré et piloté par les critères, au lancement et à l'adoption, c'est exactement à cela que sert un audit partenaire. Nous étudions votre produit, votre API et votre potentiel de partenariats, puis définissons quoi construire, ce que fini veut dire, et comment livrer et prouver ensemble.