Les tests qui dépendent d’une API réelle échouent souvent pour de mauvaises raisons : serveur de staging indisponible, limite de débit atteinte, donnée modifiée par un collègue, latence réseau. La simulation d’API supprime cette fragilité : vous remplacez l’endpoint réel par un substitut contrôlé qui renvoie la réponse attendue, de manière répétable.
Essayez Apidog aujourd’hui
Ce guide montre comment simuler une API pour vos tests : définir un schéma, générer des réponses mockées, exposer un serveur de simulation, configurer vos tests pour l’utiliser, puis couvrir les erreurs difficiles à déclencher sur un serveur réel. Les exemples utilisent une API de commandes avec GET /orders/{id}, mais la méthode s’applique à toute API REST ou GraphQL.
Quand utiliser la simulation d’API
Simulez l’API lorsque vous voulez tester votre code, pas le réseau.
Cas typiques :
- tests unitaires ;
- tests d’intégration ;
- parsing de réponses
200 ;
- gestion des
404 ;
- logique de retry sur
503 ;
- timeout côté client ;
- fallback UI ou métier.
Gardez l’API réelle pour :
- les tests de contrat ;
- quelques tests end-to-end ;
- la validation que le mock correspond toujours au service réel.
La règle pratique :
Mockez pour la vitesse et l’isolation. Interrogez le service réel pour valider le contrat.
Pour approfondir, consultez les cas où la simulation d’API est rentable et la différence entre un serveur de simulation et un serveur réel.
Le processus en cinq étapes
Pour simuler une API dans une suite de tests :
-
Définissez le schéma de l’API.
-
Générez des réponses simulées, statiques ou dynamiques.
-
Exécutez un serveur de simulation accessible via une URL.
-
Configurez vos tests pour pointer vers le mock.
-
Testez les chemins d’erreur :
404, 500, 429, timeouts, JSON invalide.
Nous allons utiliser ce endpoint comme fil conducteur :
Étape 1 : Définir le schéma
Un mock fiable commence par un contrat clair. Si votre API possède déjà un document OpenAPI, utilisez-le. Sinon, écrivez un schéma minimal pour l’endpoint testé.
Exemple 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
Ce schéma sert à deux choses :
- indiquer au mock quels champs renvoyer ;
- fournir une source unique de vérité pour les tests et le backend.
Quand le contrat change, mettez à jour le schéma. Les mocks générés depuis ce schéma restent alors alignés. C’est la base des tests de contrat d’API.
Étape 2 : Générer des réponses simulées
Vous avez deux approches principales.
Réponses statiques
Une réponse statique est un JSON fixe. Elle est idéale quand le test doit vérifier une valeur précise.
Exemple :
{
"id": "order_8842",
"status": "shipped",
"total": 149.99,
"items": [
{
"sku": "book_001",
"quantity": 1
},
{
"sku": "pen_002",
"quantity": 3
}
]
}
Utilisez ce type de réponse pour des assertions déterministes :
expect(order.status).toBe('shipped');
expect(order.total).toBe(149.99);
Réponses dynamiques
Une réponse dynamique est générée à chaque requête. Le mock peut produire :
- un UUID pour
id ;
- une valeur autorisée pour
status ;
- un montant réaliste pour
total ;
- des données variables pour
items.
Cette approche aide à détecter des bugs cachés par une seule fixture statique : chaînes longues, valeurs nulles, nombres inattendus, tableaux de tailles différentes.
La plupart des équipes combinent les deux :
-
statique pour les tests précis ;
-
dynamique pour une couverture plus proche du fuzz testing.
Avec Apidog, vous pouvez générer automatiquement des endpoints mockés à partir du schéma. Les champs comme email, phone ou avatar sont associés à des types de données cohérents, sans écrire manuellement chaque payload.
Quand vous écrivez vos fixtures à la main, évitez les données trop simplistes :
{
"id": "1",
"status": "pending",
"total": 0,
"items": []
}
Préférez des données proches de la production :
{
"id": "order_8842",
"status": "shipped",
"total": 149.99,
"items": [
{
"sku": "sku_123",
"name": "Mechanical keyboard",
"quantity": 1,
"price": 129.99
},
{
"sku": "sku_456",
"name": "USB-C cable",
"quantity": 1,
"price": 20
}
]
}
Étape 3 : Exécuter le serveur de simulation
Une réponse mockée doit être servie par une URL. Vous avez deux options.
Option 1 : serveur de simulation local
Un mock local tourne sur votre machine, par exemple :
C’est l’option recommandée pour les tests unitaires et d’intégration :
- rapide ;
- utilisable hors ligne ;
- pas d’état partagé entre builds ;
- pas de latence réseau externe.
Avec Prism, vous pouvez démarrer un mock depuis un fichier OpenAPI :
prism mock openapi.yaml
# Serveur de simulation écoutant sur http://127.0.0.1:4010
Votre endpoint devient alors disponible localement :
curl http://127.0.0.1:4010/orders/order_8842
Option 2 : serveur de simulation cloud
Un serveur cloud expose une URL publique. Utilisez-le quand :
- une app mobile doit appeler le mock ;
- un runner CI externe doit y accéder ;
- un collaborateur hors réseau local doit tester l’API ;
- vous préparez une démo.
Apidog fournit une URL de Cloud Mock par projet, ce qui permet à toute l’équipe d’utiliser le même endpoint simulé.
Pour les tests automatisés, préférez le local. Pour les démos, tests multi-appareils ou collaborations externes, le cloud est plus pratique.
Étape 4 : Pointer vos tests vers le mock
Votre code ne doit pas contenir l’URL de production en dur. Rendez l’URL de base configurable.
Exemple avec une variable d’environnement :
// 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 reçoit l’URL de base en argument :
// orderClient.js
export async function getOrder(id, baseUrl) {
const response = await fetch(`${baseUrl}/orders/${id}`);
if (!response.ok) {
throw new Error(`Failed to fetch order: ${response.status}`);
}
return response.json();
}
En local :
API_BASE_URL=http://127.0.0.1:4010 npm test
En CI, définissez API_BASE_URL vers l’adresse du mock avant d’exécuter la suite.
Ce modèle garde la simulation hors de la logique applicative. La même approche s’applique quand vous automatisez les tests API en CI/CD.
Étape 5 : Tester les chemins d’erreur
C’est souvent l’étape la plus rentable.
Un serveur réel ne renvoie pas forcément un 500, un 429 ou une réponse lente au moment où vous en avez besoin. Un mock, oui.
Configurez des scénarios d’échec explicites :
| Scénario |
Le mock renvoie |
Ce que vous affirmez |
| Enregistrement manquant |
404 |
Le client lève une erreur claire “non trouvé” |
| Défaillance serveur |
500 |
Le client réessaie, puis affiche un fallback |
| Limite de débit atteinte |
429 avec Retry-After
|
Le client applique un backoff approprié |
| Réponse lente |
200 après un délai de 5s |
Le client expire et récupère proprement |
| Corps de réponse malformé |
200 avec JSON invalide |
Le client échoue sans crash |
Exemple de test pour un 404 :
test('renvoie une erreur lisible si la commande est introuvable', async () => {
await expect(getOrder('order_404', BASE_URL))
.rejects
.toThrow('Failed to fetch order: 404');
});
Exemple de test pour un timeout :
test('échoue proprement si la réponse est trop lente', async () => {
const controller = new AbortController();
const timeout = setTimeout(() => {
controller.abort();
}, 1000);
await expect(
fetch(`${BASE_URL}/orders/order_slow`, {
signal: controller.signal
})
).rejects.toThrow();
clearTimeout(timeout);
});
Les règles de simulation avancées d’Apidog permettent de renvoyer des réponses différentes selon la requête. Par exemple :
-
GET /orders/order_404 renvoie 404 ;
-
GET /orders/order_rate_limited renvoie 429 ;
- tout autre ID renvoie
200.
Associez ces scénarios à des assertions API robustes pour tester le comportement, pas seulement les codes de statut.
Organiser les mocks dans une suite de tests qui grandit
Un seul mock est facile à gérer. Une centaine de mocks peut rapidement devenir ingérable.
Adoptez quelques conventions dès le début.
1. Regrouper par service
Organisez les mocks selon le service qu’ils remplacent :
mocks/
orders/
order-shipped.json
order-not-found.json
order-rate-limited.json
payments/
payment-authorized.json
payment-declined.json
Évitez de les ranger par test :
tests/
order-page/
mock1.json
checkout-page/
mock2.json
Quand l’API de paiement change, vous voulez modifier un seul dossier clair, pas chercher des fixtures dispersées.
2. Nommer les scénarios explicitement
Préférez :
order-shipped.json
order-delivered.json
order-rate-limited.json
À :
response1.json
test-data.json
mock-success.json
Un test qui échoue doit être lisible rapidement.
3. Versionner les mocks
Les mocks font partie de vos tests. Gardez-les dans le contrôle de version, à côté de la suite automatisée.
src/
tests/
mocks/
openapi.yaml
Une pull request qui modifie un contrat API doit inclure la mise à jour du schéma et des mocks associés.
4. Créer une réponse de base
Évitez de dupliquer des payloads complets dans chaque test. Définissez une base réaliste et surchargez uniquement ce qui change.
Exemple :
const baseOrder = {
id: 'order_8842',
status: 'shipped',
total: 149.99,
items: [
{ sku: 'sku_123', quantity: 1 },
{ sku: 'sku_456', quantity: 2 }
]
};
const cancelledOrder = {
...baseOrder,
status: 'cancelled'
};
Cette discipline rend les mocks maintenables, comme pour une suite de tests d’automatisation d’API.
Maintenir l’intégrité du mock
Le risque principal d’un mock est la dérive.
Exemples :
- le backend ajoute un champ ;
-
total devient amount;
- une valeur d’énumération change ;
- un champ devient nullable ;
- une erreur retourne un nouveau format.
Si le mock n’est pas mis à jour, vos tests restent verts alors que la production peut casser.
Pour éviter cela, appliquez deux pratiques.
1. Générer le mock depuis le même schéma que le backend
Si le mock vient du fichier OpenAPI, il peut être régénéré quand le contrat change.
Un mock écrit à la main ne suit pas automatiquement ces changements.
2. Exécuter des tests de contrat contre l’API réelle
Ajoutez une petite suite qui vérifie que l’API réelle respecte toujours le schéma.
Objectif :
- pas tester toute l’application ;
- pas remplacer les mocks ;
- seulement détecter une dérive entre le contrat et la production.
Exemple de stratégie :
Tests unitaires et intégration
→ utilisent le mock
Tests de contrat planifiés
→ appellent l’API réelle
Tests end-to-end critiques
→ couvrent quelques parcours complets
Lorsqu’un test de contrat échoue, mettez à jour le schéma, le backend ou les mocks selon l’origine du changement.
Pendant la revue de code, vérifiez aussi les mocks. Si une PR modifie une réponse API, elle doit modifier le mock correspondant.
Si vous voulez centraliser le schéma, le serveur de simulation et les tests dans un même environnement, téléchargez Apidog. Pour comparer les options disponibles, consultez 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. Utilisez des mocks pour les tests unitaires et d’intégration où vous vérifiez votre code. Gardez une petite suite de tests de contrat et quelques tests end-to-end contre l’API réelle pour valider que le mock correspond toujours à la production.
Quelle est la différence entre une réponse statique et dynamique ?
Une réponse statique est un JSON fixe, utile pour des assertions précises et répétables. Une réponse dynamique est générée à chaque requête avec des valeurs réalistes, utile pour exposer des bugs qu’une fixture unique pourrait masquer.
Comment m’assurer que mon mock reste précis ?
Générez-le depuis le même schéma que le backend, idéalement un document OpenAPI. Ensuite, exécutez régulièrement des tests de contrat contre l’API réelle pour vérifier que la réponse live respecte toujours ce schéma.
Un mock peut-il simuler des réponses lentes ou échouées ?
Oui. Vous pouvez configurer un mock pour renvoyer un 500, un 429 avec Retry-After, un 404, un JSON invalide ou un 200 retardé. C’est utile pour tester les retries, les timeouts et les fallbacks.
Serveur de simulation local ou cloud pour les tests ?
Utilisez un serveur local pour les tests automatisés : il est rapide, isolé et sans latence réseau externe. Utilisez un mock cloud lorsqu’un appareil mobile, un runner CI ou un collaborateur externe doit accéder au mock sans dépendre de votre machine.
Anker, “SpaceFlow” adını verdiği yeni ürünüyle Nebula X1 projektör ailesine 3D projeksiyon haritalama özelliği ekliyor. 399 dolardan satışa sunulan ürün, spesifik olarak Nebula X1 ile Nebula X1 Pro’nun üstüne konumlandırılıyor ve baktığı yüzeyin şeklini derinliğiyle birlikte analiz ederek farklı tasarımlar yansıtabiliyor. Ortamdaki kapıları, pencereleri, mobilyaları ve diğer objeleri tespit eden ve projeksiyonu buna göre özelleştiren SpaceFlow, 100’den fazla hazır tasarımla geliyor. Yapay zeka altyapısı sayesinde kişilerin aklından geçen tasarımları da üreterek yansıtabilen ürünün, kampanya dönemi bittikten sonra 799 dolara satılacağı aktarılıyor.