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 :

1. Définissez le schéma de l’API.
2. Générez des réponses simulées, statiques ou dynamiques.
3. Exécutez un serveur de simulation accessible via une URL.
4. Configurez vos tests pour pointer vers le mock.
5. Testez les chemins d’erreur : 404, 500, 429, timeouts, JSON invalide.

Nous allons utiliser ce endpoint comme fil conducteur :

GET /orders/{id}

É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 :

http://127.0.0.1:4010

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 :

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.