Les tests qui dépendent d'une API réelle sont des tests qui échouent pour de mauvaises raisons. Un serveur de staging tombe en panne, une limite de débit tierce se déclenche, un collègue modifie un enregistrement, et soudain votre suite de tests est rouge même si votre code est correct. La simulation de l'API supprime cette fragilité. Vous remplacez le point d'accès réel par un substitut contrôlé qui renvoie exactement la réponse que vous demandez, à chaque fois.
Ce guide décrit les étapes concrètes pour simuler une API pour les tests. Vous définirez un schéma, générerez des réponses simulées (mocks), pointerez votre code de test vers le mock et couvrirez les chemins d'erreur qu'un serveur réel produit rarement à la demande. Les exemples utilisent une petite API de gestion des commandes, mais le processus s'applique à tout service REST ou GraphQL.
Quand la simulation d'API est le bon choix
Simulez l'API lorsque ce que vous voulez tester est votre propre code, et non le réseau. Les tests unitaires et la plupart des tests d'intégration entrent dans cette catégorie. Vous voulez savoir si votre client analyse correctement un `200`, réessaie sur un `503` et affiche un message clair sur un `404`. Rien de tout cela ne nécessite un serveur réel.
Gardez l'API réelle pour les tests de contrat et une fine couche de vérifications de bout en bout. Ceux-ci existent pour confirmer que le mock correspond toujours à la réalité. Si vous simulez tout et ne vérifiez jamais par rapport au service réel, votre suite de tests reste au vert pendant que la production tombe en panne. La répartition est la suivante : simuler pour la vitesse et l'isolation, interroger le service réel pour confirmer le contrat. Pour un aperçu plus détaillé de la place de chacun, consultez cette analyse des scénarios où la simulation d'API est rentable et la distinction entre un serveur de simulation et un serveur réel.
Le processus en cinq étapes en un coup d'œil
La simulation d'une API pour les tests se fait toujours en cinq étapes, quel que soit le langage ou le framework :
- Définissez le schéma afin que le mock reflète la forme de la réponse réelle.
- Générez des réponses simulées (mocks), statiques ou dynamiques, à partir de ce schéma.
- Exécutez un serveur de simulation (mock server) qui sert ces réponses à une URL.
- Dirigez vos tests vers le mock en rendant l'URL de base configurable.
- Testez les chemins d'erreur que le serveur réel ne produira pas à la demande.
Le reste de ce guide détaille chaque étape avec un exemple concret : une petite API de gestion des commandes avec un point d'accès `GET /orders/{id}`. Gardez ce point d'accès à l'esprit comme fil conducteur.
Étape 1 : Définir le schéma
Un mock n'est utile que s'il reflète la forme de la réponse réelle. Commencez par un schéma. Si votre API dispose déjà d'un document OpenAPI, utilisez-le. Sinon, écrivez-en un pour le point d'accès testé. Voici une définition raccourcie pour `GET /orders/{id}` :
paths:
/orders/{id}:
get:
parameters:
- name: id
in: path
required: true
schema: { type: string }
responses:
'200':
content:
application/json:
schema:
type: object
properties:
id: { type: string }
status: { type: string, enum: [pending, shipped, delivered] }
total: { type: number }
items: { type: array, items: { type: object } }
'404':
description: Order not found
Le schéma a deux fonctions. Il indique au mock quels champs renvoyer, et il vous donne une source unique de vérité. Lorsque le backend modifie le contrat, vous mettez à jour le schéma et chaque mock qui en dérive reste précis. La simulation basée sur le schéma (schema-first mocking) est ce qui garantit la fiabilité des tests de contrat d'API.
Étape 2 : Générer des réponses simulées
Vous avez deux façons de produire le corps de la réponse.
Les réponses statiques sont du JSON fixe. Vous écrivez la charge utile exacte une fois et le mock la renvoie inchangée. Elles sont prévisibles et faciles à vérifier, ce qui les rend idéales pour les tests unitaires où vous voulez une valeur connue.
Les réponses dynamiques sont générées par requête. Au lieu de coder en dur `\"total\": 149.99`, le mock remplit les champs avec des valeurs générées réalistes : un UUID pour `id`, un membre aléatoire d'énumération pour `status`, un montant monétaire plausible pour `total`. Les données dynamiques détectent les bugs qu'une seule charge utile fixe masquerait, comme un analyseur qui se bloque sur de longues chaînes de caractères ou des champs nuls inattendus.
La plupart des équipes utilisent les deux. Charges utiles statiques pour les tests axés sur les assertions, génération dynamique pour une couverture de type "fuzz testing". Avec Apidog, vous n'écrivez rien à la main. Apidog lit le schéma et génère automatiquement un point d'accès simulé, faisant correspondre les noms de champs comme `email`, `phone` ou `avatar` au type de données correct. Vous pointez un navigateur vers l'URL du mock et obtenez une réponse valide immédiatement.
Lorsque vous écrivez des charges utiles à la main, gardez-les réalistes. Une commande de test avec `\"total\": 0` et un tableau `items` vide passe un analyseur naïf mais cache des bugs. Utilisez des valeurs qui ressemblent à la production : un total réaliste, deux ou trois articles, un statut qui fait réellement partie de l'énumération. Plus les données simulées sont proches de ce qu'une requête réelle renvoie, plus votre test a de la valeur.
Étape 3 : Exécuter le serveur de simulation
Une réponse simulée n'est pas utile tant que rien ne la sert. Vous avez deux options d'hébergement.
Un serveur de simulation local s'exécute sur votre machine, généralement sur un port comme `localhost:4010`. Il est rapide, fonctionne hors ligne et est la valeur par défaut pour les tests unitaires et d'intégration. Des outils légers comme Prism en démarrent un directement à partir d'un fichier OpenAPI :
prism mock openapi.yaml
# Serveur de simulation écoutant sur http://127.0.0.1:4010
Un serveur de simulation cloud a une URL publique. Optez pour un tel serveur lorsqu'une application mobile, un exécutant CI ou un collaborateur externe doit appeler le mock sans avoir accès à votre ordinateur portable. Apidog fournit à chaque projet une URL de Cloud Mock hébergée, de sorte qu'un coéquipier sur un autre réseau puisse atteindre le même point d'accès que vous.
Pour les exécutions de tests, préférez le local. Il n'a pas de latence réseau et pas d'état partagé, donc deux builds ne se chevauchent jamais. Utilisez l'option cloud pour les démonstrations et les tests multi-appareils.
Étape 4 : Diriger vos tests vers le mock
Connectez maintenant le code de test au mock au lieu de la production. L'approche la plus propre est une URL de base configurable. Lisez-la à partir d'une variable d'environnement afin que le même fichier de test s'exécute localement contre le mock et contre l'API réelle dans un travail de contrat.
// orderClient.test.js
import { getOrder } from './orderClient.js';
const BASE_URL = process.env.API_BASE_URL || 'http://127.0.0.1:4010';
test('analyse une commande expédiée', async () => {
const order = await getOrder('order_8842', BASE_URL);
expect(order.status).toBe('shipped');
expect(typeof order.total).toBe('number');
});
Le client prend l'URL de base comme argument ; rien dans le code de production ne sait qu'il est en cours de simulation. En CI, vous définissez `API_BASE_URL` sur l'adresse du mock avant l'exécution de la suite. Ce modèle maintient la simulation entièrement en dehors de la logique de votre application, là où elle doit être. Si vous exécutez des tests via un pipeline, la même idée s'applique lorsque vous automatisez les tests API en CI/CD.
Étape 5 : Tester les chemins d'erreur
C'est l'étape que la plupart des équipes ignorent, et c'est celle qui est la plus rentable. Un serveur réel renvoie rarement un `500` quand vous le souhaitez. Un mock en renvoie un sur commande.
Configurez le mock pour qu'il serve des réponses d'échec spécifiques, puis assurez-vous que votre client gère chacune d'elles :
| Scénario | Le mock renvoie | Ce que vous affirmez |
|---|---|---|
| Enregistrement manquant | `404` | Le client lève une erreur claire "non trouvé" |
| Défaillance du serveur | `500` | Le client réessaie, puis affiche un mécanisme de secours |
| Limite de débit atteinte | `429` avec `Retry-After` | Le client applique un recul approprié |
| Réponse lente | `200` après un délai de 5s | Le client expire et récupère |
| Corps de requête malformé | `200` avec du JSON cassé | Le client échoue proprement, sans plantage |
Les règles de simulation avancées d'Apidog vous permettent de renvoyer différentes réponses en fonction de la requête, ainsi une requête pour `order_404` renvoie un `404` tandis que tout autre ID renvoie un `200` normal. Cela vous donne un point d'accès simulé couvrant à la fois le chemin nominal et les échecs. Associez cela à des assertions API robustes et votre suite vérifie le comportement, et pas seulement les codes de statut.
Organiser les mocks dans une suite de tests en pleine croissance
Un seul point d'accès simulé est facile. Une centaine d'entre eux, répartis sur une suite, est l'endroit où les équipes perdent le contrôle. Quelques habitudes permettent de maintenir l'ensemble gérable.
Regroupez les mocks par le service réel qu'ils remplacent, et non par le test qui les utilise. Lorsque l'API de paiement change, vous voulez un seul endroit à mettre à jour, pas vingt fichiers de test. Nommez les fixtures de mock en fonction du scénario qu'elles représentent, comme `order-shipped` ou `order-rate-limited`, afin qu'un test échoué se lise clairement. Conservez les définitions de mock dans le contrôle de version à côté des tests, car un mock fait partie du test et mérite la même révision.
Résistez à la tentation de donner à chaque test sa propre charge utile sur mesure. La plupart des tests veulent le même objet de commande réaliste avec un champ modifié. Définissez une réponse de base une fois et ne surchargez que le champ testé. Cela maintient la suite lisible et signifie qu'un changement de contrat affecte une seule définition de base au lieu de copies dispersées. La même discipline qui rend une suite de tests pour l'automatisation d'API maintenable s'applique directement aux mocks qui la sous-tendent.
Maintenir l'intégrité du mock
Un mock dérive. Le backend ajoute un champ, renomme `total` en `amount`, ou modifie une énumération, et votre mock continue de renvoyer l'ancienne forme. Les tests passent ; la production échoue. C'est la façon la plus courante dont la simulation tourne mal, et c'est silencieux. Rien dans votre suite ne se plaint, car la suite mesure le mock par rapport à lui-même.
Deux habitudes l'empêchent. Premièrement, dérivez le mock du même schéma que le backend publie, de sorte qu'un changement de contrat mette à jour les deux simultanément. Un mock généré à partir d'un fichier OpenAPI se régénère lorsque ce fichier change ; un mock tapé à la main ne le fait pas. Deuxièmement, exécutez un petit ensemble de tests de contrat contre l'API réelle selon un calendrier. Leur seul travail est de confirmer que la réponse réelle correspond toujours au schéma utilisé par vos mocks. Lorsqu'ils échouent, vous savez que le mock est obsolète avant même les utilisateurs.
Il est également utile de réviser les mocks lors de la revue de code. Lorsqu'une pull request modifie une réponse API, le réviseur doit vérifier que le mock correspondant a également été modifié. Traiter le mock comme faisant partie du contrat, plutôt que comme un utilitaire de test jetable, est ce qui maintient une suite simulée digne de confiance sur des mois de changements.
Si vous voulez un environnement unique qui contient le schéma, génère le mock et exécute les tests, Téléchargez Apidog. Il maintient la conception, le serveur de simulation et la suite de tests synchronisés, de sorte que le mock que vous testez est toujours le contrat actuel. Pour des options plus larges, comparez le domaine dans ce tour d'horizon des outils de simulation d'API REST.
Questions fréquemment posées
Dois-je simuler l'API pour chaque test ?
Non. Simulez pour les tests unitaires et d'intégration où vous vérifiez votre propre code. Gardez un petit ensemble de tests de contrat et de tests de bout en bout qui interrogent l'API réelle, car ceux-ci confirment que votre mock correspond toujours à la production. Tout simuler cache la dérive du contrat.
Quelle est la différence entre une réponse de simulation statique et dynamique ?
Une réponse statique est une charge utile JSON fixe qui ne change jamais, ce qui est bon pour des assertions prévisibles. Une réponse dynamique est générée par requête avec des valeurs réalistes, ce qui détecte les bugs qu'une seule charge utile fixe manquerait. La plupart des équipes utilisent les deux.
Comment m'assurer que mon mock reste précis ?
Générez le mock à partir du même schéma utilisé par le backend, idéalement un document OpenAPI. Ensuite, exécutez des tests de contrat planifiés contre l'API réelle pour confirmer que la réponse en direct correspond toujours à ce schéma. S'ils échouent, votre mock doit être mis à jour.
Un mock peut-il simuler des réponses lentes ou échouées ?
Oui, et c'est l'une des raisons les plus solides de simuler. Vous pouvez configurer un mock pour qu'il renvoie un `500`, un `429` avec un en-tête `Retry-After`, ou un `200` retardé. Cela vous permet de vérifier la logique de réessai et les délais d'attente qu'un serveur réel sain ne déclencheraient jamais à la demande.
Serveur de simulation local ou serveur de simulation cloud pour les tests ?
Utilisez un serveur de simulation local pour les exécutions de tests. Il est rapide, n'a pas de latence réseau et évite l'état partagé entre les builds. Utilisez un mock hébergé dans le cloud lorsqu'un appareil mobile, un exécutant CI ou un collaborateur externe doit atteindre le mock sans avoir accès à votre machine.