SSD Nodes Learn Hosting plans →
Guides Matt ConnorPar Matt Connor · Mis à jour le 2026-10-30

Mocking et tests d’API auto-hébergés sur un VPS

WireMock mocke les dépendances, Hurl teste vos endpoints. Déployez les deux sur un VPS avec Docker Compose, fixtures dans Git et rapports conservés après rebuild.

Deux tâches qui partagent un même dépôt

Le mocking et les tests d’API auto-hébergés correspondent à deux tâches différentes. Les traiter comme une seule tâche vous fait perdre une semaine. Un mock server remplace une dépendance que vous ne pouvez pas appeler depuis la CI : un prestataire de paiement, une API partenaire, un service upstream limité en débit ou un service qu’une autre équipe n’a pas encore livré. Un API test runner appelle vos propres endpoints dans un ordre défini et vérifie les réponses. Il transmet les valeurs d’une réponse à la requête suivante.

Certains outils réalisent ces deux tâches. La fonction principale d’un mock server est de répondre aux requêtes. Un test runner ne préjuge pas de la réponse d’un prestataire de paiement lorsqu’une carte est refusée. La plupart des équipes qui louent déjà un serveur finissent par exécuter un outil de chaque type. Ils sont démarrés par le même fichier Docker Compose et examinés dans la même pull request.

Pourquoi héberger soi-même le mocking et les tests d’API ?

Vos fixtures contiennent des données structurées comme en production. Le corps d’une requête de test d’API est un véritable enregistrement client dont le nom a été modifié, ou dont le nom n’a pas été modifié parce que personne ne l’a vérifié. Les stubs enregistrés sont encore plus risqués : l’enregistrement via un proxy stocke exactement la réponse renvoyée par le service upstream. Un répertoire de stubs créé par enregistrement contient donc des tokens actifs et des adresses e-mail de clients jusqu’à ce que quelqu’un lise chaque fichier. Sur un service hébergé, ces données deviennent l’incident de sécurité et la divulgation de quelqu’un d’autre.

La deuxième raison est l’accessibilité réseau. Un service lié à une adresse privée nécessite une connexion au réseau privé avant qu’un runner hébergé puisse y accéder. Chaque contournement a un coût. Publier l’API sur Internet pour pouvoir la tester annule la raison pour laquelle elle était privée. Un tunnel ou une copie publique de staging est un système supplémentaire à maintenir, et une copie de staging diverge de la production entre deux releases. Les runners GitHub-hosted prennent également en charge l’accès privé via un overlay WireGuard ou un Azure Virtual Network. Un runner présent sur le même réseau privé appelle directement le service et n’a besoin d’aucun de ces contournements. C’est l’argument pratique en faveur de un runner GitHub Actions auto-hébergé.

Quel mock server auto-hébergé devriez-vous utiliser ?

Chacun de ces outils s’exécute dans un conteneur sur un serveur que vous contrôlez. La question importante est de savoir ce que chacun considère comme la source de vérité. Cela détermine si la reconstruction du conteneur ne vous coûte rien ou vous prend tout un après-midi.

  • WireMock conserve chaque stub dans un fichier JSON situé dans le répertoire mappings/, et les corps de réponse volumineux dans __files/. L’image est wiremock/wiremock, son répertoire racine dans le conteneur est /home/wiremock, et elle peut également fonctionner comme proxy d’enregistrement. Les fichiers stockés sur le disque permettent de versionner le mock dans git comme n’importe quel autre code.
  • Mockoon CLI conserve une API mock complète dans un seul fichier de données JSON. Installez-le avec npm install -g @mockoon/cli et démarrez-le avec mockoon-cli start --data ./data-file.json, ou exécutez l’image mockoon/cli en montant ce fichier avec un bind mount. L’application desktop modifie le même fichier. Vous pouvez donc concevoir l’API dans l’interface graphique et versionner le résultat sans problème.
  • MockServer s’exécute depuis l’image mockserver/mockserver et écoute sur le port 1080. Les expectations sont ajoutées via sa propre API REST. C’est pratique depuis le code de test, mais risqué en production : par défaut, une expectation créée par un appel HTTP disparaît lorsque le conteneur redémarre. Utilisez son fichier d’initialisation JSON pour les stubs qui doivent être permanents. Pour conserver les modifications effectuées à chaud, activez persistExpectations, stockez le fichier de sortie en dehors du conteneur et chargez-le au démarrage avec initializationJsonPath.
  • Prism construit le mock à partir de votre document OpenAPI, plutôt qu’à partir de fichiers de stubs distincts. Installez-le avec npm install -g @stoplight/prism-cli, puis exécutez prism mock openapi.yaml. Dans un conteneur, ajoutez -h 0.0.0.0, car Prism se lie à localhost par défaut et reste sinon inaccessible depuis l’extérieur du conteneur.
  • Microcks est l’option la plus complète : une interface web qui importe des documents OpenAPI et des collections Postman, puis les expose sous forme de mocks et exécute des tests de contrat. Une installation complète nécessite MongoDB et Keycloak, ainsi que Kafka pour ses fonctionnalités asynchrones. L’image tout-en-un microcks-uber inclut un MongoDB en mémoire, que le projet présente comme adapté à un usage éphémère. Considérez donc comme temporaires les éléments créés dans cette interface et conservez les artefacts source dans git.

Quel runner de test d’API auto-hébergé devriez-vous utiliser ?

Le travail consiste ici en une séquence : s’authentifier, créer une commande, la relire, puis vérifier que son état a changé. Il faut donc récupérer une valeur dans une réponse et la réutiliser dans la requête suivante. Un outil incapable de conserver l’état entre deux appels est un health check, pas un test d’API.

  • Hurl exécute des fichiers texte contenant des requêtes HTTP depuis un binaire unique. Une section [Captures] extrait des valeurs d’une réponse, une section [Asserts] les vérifie et --test transforme l’ensemble en test runner avec un résumé et un exit code. La version 8.0.1 est la version actuelle en août 2026.
  • Bruno CLI exécute un répertoire de fichiers .bru. Installez-le avec npm install -g @usebruno/cli, puis lancez-le avec bru run folder --env Local --reporter-junit results.xml. Le format des collections repose volontairement sur des fichiers texte dans un répertoire : les diffs restent donc lisibles lors de la revue.
  • Newman exécute des collections Postman en dehors de Postman : npm install -g newman, puis newman run collection.json -r cli,junit --reporter-junit-export results.xml. Le point bloquant est le format. Newman exécute les collections exportées au format JSON v2.1. Postman prend désormais aussi en charge un format de collection v3 et les workflows Native Git via Postman CLI. La documentation de Postman indique que Newman ne recevra plus aucune mise à jour ni correction et recommande de migrer les scripts et les pipelines CI vers Postman CLI.
  • Schemathesis effectue un contrôle d’un autre type. Il lit un schéma OpenAPI et génère des cas destinés à produire des réponses que votre schéma considère comme impossibles : uvx schemathesis run https://your.api/openapi.json. Il détecte les plantages et les violations de contrat. Il ne connaît rien de vos règles métier. Il complète donc une suite de tests scriptés au lieu de la remplacer.
  • Hoppscotch auto-hébergé est l’option avec interface web. Il nécessite une instance Postgres. Prenez en compte ce compromis avant de l’installer : les collections sont stockées dans une base de données, pas dans votre dépôt.

Un outil est à éviter. Step CI apparaît encore dans les comparatifs d’outils et son format de workflow YAML est lisible, mais le dépôt a reçu son dernier commit en août 2024. Un programme placé entre votre CI et votre API est un mauvais endroit pour du code qui n’est plus maintenu.

Protéger le serveur mock derrière le pare-feu

La configuration ci-dessous exécute WireMock comme substitut d’un prestataire de paiement. Si le format des fichiers Compose ne vous est pas familier, Docker Compose sur un VPS couvre les commandes de cycle de vie utilisées dans cette section.

services:
  mock-payments:
    image: wiremock/wiremock:3.13.2
    command: ["--verbose"]
    volumes:
      - ./mocks/payments:/home/wiremock
    ports:
      - "127.0.0.1:8080:8080"
    restart: unless-stopped

Le préfixe 127.0.0.1: du port est l’élément important. Un simple 8080:8080 publie le mock sur toutes les interfaces, y compris votre IP publique. Il reste alors accessible même si ufw refuse ce port, car Docker achemine le trafic publié via la table nat avant qu’il n’atteigne les règles INPUT de ufw. Liez le port à l’adresse loopback pour que le port publié ne soit accessible que depuis l’hôte avec le réseau bridge par défaut de Docker sur Engine 28.0.0 ou version ultérieure. Les versions antérieures permettent aux hôtes du même réseau de couche 2 d’atteindre les ports publiés sur localhost. Une liaison à l’adresse d’une interface privée permet toujours l’accès depuis les réseaux qui peuvent acheminer du trafic vers cette adresse.

Votre service à tester pointe ensuite vers le mock. Lorsque le service s’exécute dans le même projet Compose, l’URL de base du mock est http://mock-payments:8080, car Compose résout les noms de service sur son propre réseau. Lorsque le service s’exécute sur l’hôte, elle est http://127.0.0.1:8080. Définissez cette valeur dans une variable d’environnement, jamais dans le code, sinon l’URL de test sera déployée en production.

Les stubs se trouvent dans ./mocks/payments/mappings/, avec un fichier JSON par stub.

{
  "request": {
    "method": "POST",
    "urlPath": "/v1/charges",
    "bodyPatterns": [{ "matchesJsonPath": "$.amount" }]
  },
  "response": {
    "status": 201,
    "headers": { "Content-Type": "application/json" },
    "jsonBody": { "id": "ch_test_001", "status": "succeeded", "amount": 4200 }
  }
}

Démarrez-le, puis vérifiez ce qui a réellement été chargé.

docker compose up -d --wait mock-payments
curl -fsS http://127.0.0.1:8080/__admin/mappings

--wait attend que le conteneur indique un état healthy. Cela fonctionne parce que l’image WireMock fournit un HEALTHCHECK qui interroge son endpoint /__admin/health. L’appel mappings répertorie tous les stubs lus par le serveur. Un stub que vous avez écrit mais qui n’apparaît pas dans cette liste n’a jamais été chargé. Vérifiez que le fichier se trouve sous mappings/ et non dans la racine montée, puis vérifiez que le JSON est valide.

Lorsqu’une requête arrive et qu’aucun stub ne correspond, WireMock répond 404. S’il trouve une correspondance proche, le corps commence par Request was not matched, suivi d’un diff avec le stub le plus proche. Lorsqu’aucun mapping de stub n’est présent, le corps est No response could be served as there are no stub mappings in this WireMock instance. Lisez le diff lorsqu’il est présent avant de modifier quoi que ce soit, car il indique le champ exact qui diffère. Il s’agit généralement d’un chemin contenant /v1/charge alors que le stub indique /v1/charges.

Écrivez le test sous forme de séquence, en conservant l’état entre les appels

Les fichiers Hurl sont de simples fichiers texte. Installez le deb depuis les releases du projet.

VERSION=8.0.1
curl --location --remote-name https://github.com/Orange-OpenSource/hurl/releases/download/$VERSION/hurl_${VERSION}_amd64.deb
sudo apt update && sudo apt install ./hurl_${VERSION}_amd64.deb

Une suite qui teste votre propre API avec le mock se trouve dans tests/checkout.hurl.

POST {{base_url}}/orders
Content-Type: application/json
{
  "sku": "ssd-1tb",
  "amount": 4200
}
HTTP 201
[Captures]
order_id: jsonpath "$['id']"

GET {{base_url}}/orders/{{order_id}}
HTTP 200
[Asserts]
jsonpath "$.status" == "paid"
jsonpath "$.charge_id" == "ch_test_001"

Le bloc [Captures] transforme ces requêtes en test d’API, au lieu d’en faire deux requêtes indépendantes. order_id est extrait de la première réponse, puis interpolé dans l’URL de la seconde. L’assertion sur charge_id est l’objectif principal du test : elle prouve que votre service a appelé le fournisseur de paiement et enregistré la réponse reçue. La valeur comparée est celle que vous avez écrite dans le stub WireMock. Un seul fichier couvre ainsi les deux parties du flux.

hurl --test --variable base_url=http://127.0.0.1:3000 \
  --report-junit reports/junit.xml \
  --report-json reports/json \
  tests/

Une exécution réussie affiche une ligne par fichier, puis un récapitulatif.

tests/checkout.hurl: Success (2 request(s) in 61 ms)
Executed files:    1
Executed requests: 2 (30.1/s)
Succeeded files:   1 (100.0%)
Failed files:      0 (0.0%)
Duration:          64 ms

En cas d’échec, error: Assert failure affiche le fichier et le numéro de ligne, puis la valeur obtenue et la valeur attendue. hurl se termine alors avec un code différent de zéro, afin que la CI s’arrête. Si status lit pending alors que vous attendiez paid, votre service n’a pas traité la réponse du mock. Consultez ensuite le journal des requêtes WireMock à l’emplacement /__admin/requests. Il indique si l’appel a atteint le mock.

Déclencher la suite depuis votre propre runner CI

Avec un runner enregistré sur le même serveur, le workflow est court. Le runner s’exécute comme un processus classique sur l’hôte. docker et hurl doivent donc être installés sur cet hôte. Rien n’est hérité d’une image hébergée.

name: api-tests
on: [push]
jobs:
  hurl:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v4
      - name: Start the mock
        run: docker compose up -d --wait mock-payments
      - name: Run the suite
        run: hurl --test --variable base_url=http://127.0.0.1:3000 --report-junit reports/junit.xml tests/
      - name: Archive the reports
        if: always()
        run: install -d /srv/api-tests/reports/$GITHUB_SHA && cp -r reports/. /srv/api-tests/reports/$GITHUB_SHA/
      - name: Stop the mock
        if: always()
        run: docker compose down

if: always() à l’étape d’archivage est important. Sans lui, un échec des tests ignore la copie. Vous perdez donc précisément le rapport que vous vouliez consulter. La copie doit également être placée en dehors du workspace, car actions/checkout@v4 exécute par défaut git clean -ffdx avant la récupération. Cette commande supprime les rapports non suivis du répertoire du dépôt lors du checkout suivant.

Conservez les résultats, pas seulement ceux de la dernière exécution

Un fichier XML JUnit par commit répond à une seule question : le test a-t-il réussi ? Il n’indique pas quand un endpoint a commencé à ralentir, car plus rien ne lit ces fichiers dès que vous cessez de les ouvrir. Pour suivre une tendance, ajoutez une ligne par exécution dans une petite base de données sur le même serveur. Une seule table contenant le SHA du commit, le nom du fichier, le nombre de réussites, le nombre d’échecs et la durée suffit. SQLite en production sur un VPS constitue un choix raisonnable : un seul fichier, aucun processus serveur, et tout l’historique est inclus dans la sauvegarde que vous effectuez déjà. Analysez la sortie --report-json de Hurl pour obtenir les données détaillées de l’exécution ; JSON et XML JUnit sont tous deux lisibles par une machine.

Ce qui doit survivre à la reconstruction d’un conteneur

Les définitions de mocks et les suites de tests sont du code source. Elles doivent se trouver dans un dépôt à côté du service qu’elles décrivent, et être modifiées dans la même pull request que celle qui modifie un endpoint. Un stub modifié dans une interface web, ou une attente envoyée à MockServer via son API REST au moment de l’exécution, nécessite une exportation ou une configuration de persistance pour survivre à une reconstruction. Exécutez docker compose down : la mémoire du conteneur et ses couches inscriptibles sont alors perdues, tandis que les données stockées dans des bind mounts ou des named volumes persistent. Si vos dépôts s’exécutent également sur votre propre matériel, un serveur git auto-hébergé maintient les fixtures et le service dans une même limite de confiance.

Voici les règles pratiques. Épinglez les tags d’image, car latest peut modifier la façon dont votre mock fait correspondre les requêtes sans aucun changement dans votre dépôt, et il est alors très difficile de relier l’échec à sa cause. Montez les répertoires de stubs en lecture seule lorsque l’outil n’a pas besoin d’y écrire. Ne placez jamais les stubs d’un mock dans un named Docker volume, car le volume devient alors la source de vérité et la copie présente dans git devient silencieusement incorrecte.

Autre point important, qui prend souvent les utilisateurs au dépourvu. Si vous créez des stubs en enregistrant du trafic réel via un proxy, lisez chaque fichier généré avant de le valider. Un enregistrement contient exactement ce que l’amont a renvoyé, y compris les bearer tokens et les adresses e-mail des clients. Sa validation place définitivement ces données dans votre dépôt, car git conserve le contenu supprimé dans son historique.

FAQ

Quelle est la différence entre un serveur mock d’API et un test runner d’API ?

Un serveur mock répond aux requêtes. Il remplace une dépendance que vous ne pouvez pas appeler depuis la CI. Certains outils exécutent aussi des tests de contrat et en indiquent les résultats. Un test runner d’API envoie des requêtes à votre propre service, vérifie les réponses, réutilise certaines valeurs d’un appel au suivant et se termine avec un code différent de zéro si une assertion échoue. Ces outils répondent à des besoins différents. Une configuration classique exécute les deux en parallèle : le runner appelle votre service, tandis que votre service appelle le mock.

Puis-je tester une API interne depuis un runner de CI hébergé ?

Oui, avec un réseau privé. Les runners hébergés par GitHub prennent en charge un overlay WireGuard ou un Azure Virtual Network pour accéder aux ressources privées sans publier l’API. Vous pouvez aussi publier l’API, utiliser un tunnel ou maintenir une copie publique de staging. Chacune de ces options ajoute un système susceptible de tomber en panne ou de divulguer des données. Un runner situé sur le même réseau privé appelle directement le service. C’est la principale raison pratique pour laquelle les équipes hébergent elles-mêmes cette partie.

Où doivent se trouver les stubs mock et les suites de tests d’API ?

Dans git, à côté du service qu’ils décrivent. Les outils qui stockent les définitions sous forme de fichiers, comme le répertoire mappings/ de WireMock, le fichier de données de Mockoon, les fichiers Hurl et le répertoire .bru de Bruno, facilitent la revue de code et la reconstruction d’un conteneur sans coût supplémentaire. Les outils qui stockent les définitions dans une base de données ou une interface web nécessitent un plan de sauvegarde et une étape d’export. C’est généralement cette étape que les équipes oublient jusqu’à ce que le conteneur ait déjà disparu.

Pourquoi mon mock renvoie-t-il 404 alors que le stub semble correct ?

WireMock ne sert un stub que si la requête respecte les matchers configurés. Une requête sans correspondance reçoit 404. Lorsqu’une correspondance proche existe, le corps commence par Request was not matched, puis affiche un diff par rapport au stub le plus proche. Ce diff indique le champ qui diffère. Lorsqu’aucun stub mapping n’existe, le corps explique à la place que l’instance n’en contient aucun. Les causes courantes sont une barre oblique finale dans le chemin, un en-tête Content-Type requis par le stub mais absent de la requête du client, urlPath utilisé alors que le stub attend urlPathPattern pour un segment variable, ou un matcher de corps qui ne correspond pas au payload. Vérifiez d’abord /__admin/requests pour confirmer que la requête a bien atteint le mock.

Ai-je encore besoin de mocks si j’ai un environnement de staging ?

Oui, pour deux raisons. Une copie de staging d’un service upstream que vous ne contrôlez pas peut toujours tomber en panne et appliquer des limites de débit. Votre suite échoue alors pour des raisons sans rapport avec votre code. Cette copie ne peut pas non plus produire les réponses dont vous avez le plus besoin pour vos tests, comme une carte refusée ou un timeout de gateway. Un mock renvoie ces réponses à la demande, à la vitesse du réseau local. Une suite qui prend plusieurs minutes contre un sandbox s’exécute ainsi en quelques secondes. Conservez staging pour la vérification finale avant la mise en production et utilisez des mocks dans la CI.

Cet article vous a-t-il été utile ?