Comment simuler une API pour les tests: Guide pratique

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.

et la différence entre un , 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 , 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 .

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

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, .

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.