SSD Nodes Learn Hosting plans →
Anleitungen Matt ConnorVon Matt Connor · Aktualisiert 2026-10-30

API-Mocking und API-Tests selbst hosten auf einem VPS

Erfahren Sie, wie Sie WireMock und Hurl effizient auf einem eigenen VPS betreiben. Trennen Sie Mock-Server von Test-Runnern, um stabile CI-Pipelines und persistente Reports zu erhalten.

Zwei Aufgaben mit einem gemeinsamen Repository

Self-hosting für API-Mocking und API-Tests sind zwei unterschiedliche Aufgaben. Wenn Sie beides zusammenlegen, verlieren Sie leicht eine Woche. Ein Mock-Server ersetzt eine Abhängigkeit, die Sie aus CI nicht aufrufen können: einen Zahlungsanbieter, eine Partner-API, einen Upstream mit Rate-Limiting oder einen Dienst, den ein anderes Team noch nicht veröffentlicht hat. Ein API-Test-Runner ruft Ihre eigenen Endpunkte in einer festen Reihenfolge auf und prüft die Antworten. Dabei übernimmt er Werte aus einer Antwort in die jeweils nächste Anfrage.

Einige Tools erledigen beide Aufgaben. Die Hauptaufgabe eines Mock-Servers besteht darin, Anfragen zu beantworten. Ein Test-Runner macht keine Vorgabe dazu, welche Antwort ein Zahlungsanbieter bei der Ablehnung einer Karte zurückgibt. Die meisten Teams, die bereits einen Server mieten, betreiben am Ende jeweils ein Tool pro Aufgabe. Beide werden mit derselben Docker-Compose-Datei gestartet und im selben Pull Request geprüft.

Warum API-Mocking und -Tests selbst hosten?

Ihre Fixtures enthalten produktionsnahe Daten. Ein Request-Body in einem API-Test ist ein echter Kundendatensatz mit geändertem Namen – oder mit unverändertem Namen, weil niemand ihn geprüft hat. Aufgezeichnete Stubs sind noch problematischer: Beim Aufzeichnen über einen Proxy werden die tatsächlichen Antworten des Upstream-Dienstes gespeichert. Ein durch Aufzeichnung erstelltes Stub-Verzeichnis enthält daher Live-Tokens und E-Mail-Adressen von Kunden, bis jemand jede Datei liest. Bei einem gehosteten Dienst werden diese Daten zum Sicherheitsvorfall und zur Offenlegung durch einen Dritten.

Der zweite Grund ist die Erreichbarkeit. Ein Dienst, der an eine private Adresse gebunden ist, benötigt eine private Netzwerkverbindung, bevor ein gehosteter Runner ihn erreichen kann. Jede Umgehung verursacht Aufwand. Wenn Sie die API zum Testen im Internet veröffentlichen, entfällt der Grund für ihre private Erreichbarkeit. Ein Tunnel oder eine öffentliche Staging-Kopie ist ein weiteres zu wartendes System. Außerdem weicht eine Staging-Kopie zwischen Releases von der Produktion ab. GitHub-hosted Runner unterstützen auch den privaten Zugriff über ein WireGuard-Overlay oder ein Azure Virtual Network. Ein Runner im selben privaten Netzwerk kann den Dienst direkt aufrufen und benötigt nichts davon. Das ist das praktische Argument für einen selbst gehosteten GitHub Actions Runner.

Welchen Self-hosted Mock-Server sollten Sie betreiben?

Jeder dieser Server läuft als Container auf einem von Ihnen verwalteten System. Entscheidend ist, was jeweils als maßgebliche Quelle gilt. Davon hängt ab, ob das Neuerstellen des Containers keine Arbeit verursacht oder einen ganzen Nachmittag dauert.

  • WireMock speichert jedes Stub als JSON-Datei in einem mappings/-Verzeichnis. Große Antwortdaten liegen in __files/. Das Image ist wiremock/wiremock. Sein Stammverzeichnis im Container ist /home/wiremock. WireMock kann außerdem als aufzeichnender Proxy ausgeführt werden. Dateien auf dem Datenträger bedeuten, dass der Mock wie jeder andere Code in git verwaltet werden kann.
  • Mockoon CLI speichert eine vollständige Mock-API in einer einzelnen JSON-Datendatei. Installieren Sie es mit npm install -g @mockoon/cli und starten Sie es mit mockoon-cli start --data ./data-file.json. Alternativ können Sie das mockoon/cli-Image mit dieser Datei als Bind-Mount ausführen. Die Desktop-Anwendung bearbeitet dieselbe Datei. Dadurch bleiben die Erstellung in einer grafischen Oberfläche und das Einchecken des Ergebnisses kompatibel.
  • MockServer läuft aus dem mockserver/mockserver-Image und lauscht auf Port 1080. Expectations werden über die eigene REST-API übermittelt. Das ist aus Testcode heraus praktisch, für den produktiven Betrieb aber riskant: Standardmäßig verschwindet eine per HTTP-Aufruf erstellte Expectation beim Neustart des Containers. Verwenden Sie für dauerhafte Stubs die JSON-Initialisierungsdatei. Um Laufzeitänderungen zu erhalten, aktivieren Sie persistExpectations, speichern Sie die Ausgabedatei außerhalb des Containers und laden Sie sie beim Start über initializationJsonPath.
  • Prism erstellt den Mock aus Ihrem OpenAPI-Dokument und nicht aus separaten Stub-Dateien. Installieren Sie es mit npm install -g @stoplight/prism-cli und starten Sie es anschließend mit prism mock openapi.yaml. Fügen Sie in einem Container -h 0.0.0.0 hinzu, weil Prism standardmäßig an localhost gebunden ist und andernfalls von außerhalb des Containers nicht erreichbar ist.
  • Microcks ist die umfangreiche Option: eine Weboberfläche, die OpenAPI-Dokumente und Postman-Sammlungen importiert, sie als Mocks bereitstellt und Vertragstests ausführt. Eine vollständige Installation benötigt MongoDB und Keycloak sowie Kafka für asynchrone Funktionen. Das All-in-one-Image microcks-uber bündelt eine MongoDB im Arbeitsspeicher. Laut Projektdokumentation ist es für kurzlebige Nutzung vorgesehen. Behandeln Sie daher alles, was in dieser Oberfläche erstellt wird, als vorübergehend und halten Sie die Quelldateien in git.

Welchen Self-Hosted-API-Test-Runner sollten Sie einsetzen?

Die Aufgabe besteht hier aus einer Abfolge: authentifizieren, eine Bestellung anlegen, sie wieder auslesen und prüfen, ob sich ihr Status geändert hat. Dafür muss ein Wert aus einer Antwort erfasst und in der nächsten Anfrage verwendet werden. Ein Tool, das keinen Zustand zwischen Aufrufen weitergeben kann, ist ein Health Check und kein API-Test.

  • Hurl führt Klartextdateien mit HTTP-Anfragen aus einer einzelnen Binärdatei aus. Ein [Captures]-Abschnitt liest Werte aus einer Antwort aus, ein [Asserts]-Abschnitt prüft sie, und --test macht daraus einen Test-Runner mit Zusammenfassung und Exit-Code. Version 8.0.1 ist im August 2026 aktuell.
  • Bruno CLI führt einen Ordner mit .bru-Dateien aus. Installieren Sie es mit npm install -g @usebruno/cli und starten Sie es anschließend mit bru run folder --env Local --reporter-junit results.xml. Das Sammlungsformat besteht absichtlich aus Textdateien in einem Verzeichnis. Dadurch bleiben die Diffs in Reviews lesbar.
  • Newman führt Postman-Sammlungen außerhalb von Postman aus: npm install -g newman und anschließend newman run collection.json -r cli,junit --reporter-junit-export results.xml. Der Nachteil ist das Format. Newman führt exportierte Sammlungen im JSON-Format v2.1 aus. Postman unterstützt inzwischen außerdem ein Sammlungformat v3 und Native-Git-Workflows über die Postman CLI. Laut der Postman-Dokumentation erhält Newman keine weiteren Aktualisierungen oder Fehlerbehebungen. Sie empfiehlt, Skripte und CI-Pipelines auf die Postman CLI zu migrieren.
  • Schemathesis prüft auf andere Weise. Es liest ein OpenAPI-Schema und erzeugt Fälle, die Antworten zu erzeugen versuchen, die laut Ihrem Schema unmöglich sind: uvx schemathesis run https://your.api/openapi.json. Das Tool findet Abstürze und Vertragsverletzungen. Über Ihre Geschäftsregeln weiß es nichts. Daher ergänzt es eine skriptbasierte Testsuite, statt sie zu ersetzen.
  • Hoppscotch Self-Hosted ist die Option mit Weboberfläche und erfordert eine Postgres-Instanz. Berücksichtigen Sie diesen Kompromiss vor der Installation: Sammlungen werden in einer Datenbank und nicht in Ihrem Repository gespeichert.

Ein Tool sollten Sie vermeiden. Step CI erscheint weiterhin in Tool-Übersichten, und sein YAML-Workflow-Format ist gut lesbar. Das Repository erhielt jedoch zuletzt im August 2024 einen Commit. Ein Programm zwischen Ihrer CI und Ihrer API ist ein ungeeigneter Ort für nicht mehr gepflegten Code.

Mock-Server hinter der Firewall betreiben

Die folgende Konfiguration führt WireMock als Ersatz für einen Zahlungsanbieter aus. Wenn das Format der Compose-Datei für Sie neu ist, beschreibt Docker Compose auf einem VPS die in diesem Abschnitt vorausgesetzten Befehle für den Lebenszyklus.

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

Der Präfix 127.0.0.1: am Port ist entscheidend. Ein einfacher Eintrag 8080:8080 veröffentlicht den Mock an jeder Schnittstelle, einschließlich Ihrer öffentlichen IP-Adresse. Der Mock bleibt auch erreichbar, wenn ufw diesen Port sperrt, weil Docker veröffentlichten Datenverkehr über die Tabelle nat leitet, bevor er die INPUT-Regeln von ufw erreicht. Binden Sie die Veröffentlichung an die Loopback-Adresse, damit der Port mit dem standardmäßigen Bridge-Netzwerk von Docker nur vom Host aus erreichbar ist. Dies gilt für Engine 28.0.0 und höher. Ältere Releases ermöglichen Hosts im selben Layer-2-Netzwerk den Zugriff auf Ports, die an localhost veröffentlicht wurden. Wenn Sie eine private Schnittstellenadresse verwenden, bleibt der Zugriff aus Netzwerken möglich, die diese Adresse routen können.

Ihr zu testender Dienst verweist anschließend auf den Mock. Wenn der Dienst im selben Compose-Projekt ausgeführt wird, lautet die Basis-URL des Mocks http://mock-payments:8080, weil Compose Dienstnamen in seinem eigenen Netzwerk auflöst. Wenn der Dienst auf dem Host ausgeführt wird, lautet sie http://127.0.0.1:8080. Setzen Sie diesen Wert über eine Umgebungsvariable und niemals im Code. Andernfalls gelangt die Test-URL in die Produktionsumgebung.

Die Stubs werden unter ./mocks/payments/mappings/ abgelegt, jeweils eine JSON-Datei pro 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 }
  }
}

Starten Sie den Mock und prüfen Sie anschließend, was tatsächlich geladen wurde.

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

--wait wartet, bis der Container einen gesunden Status meldet. Das funktioniert, weil das WireMock-Image einen HEALTHCHECK für seinen Endpunkt /__admin/health enthält. Der Aufruf mappings listet alle Stubs auf, die der Server eingelesen hat. Fehlt ein von Ihnen erstellter Stub in dieser Liste, wurde er nicht geladen. Prüfen Sie, ob sich die Datei unter mappings/ und nicht im eingehängten Stammverzeichnis befindet. Prüfen Sie außerdem, ob das JSON gültig ist.

Wenn eine Anfrage eingeht und kein Stub passt, antwortet WireMock mit 404. Wenn WireMock eine annähernd passende Anfrage findet, beginnt der Antworttext mit Request was not matched. Danach folgt ein Diff zum ähnlichsten Stub. Ohne Stub-Zuordnungen lautet der Antworttext No response could be served as there are no stub mappings in this WireMock instance. Lesen Sie den Diff, sofern vorhanden, bevor Sie Änderungen vornehmen. Er nennt das genaue Feld, das abweicht. Meist handelt es sich um einen Pfad mit /v1/charge, während der Stub /v1/charges enthält.

Schreiben Sie den Test als Sequenz mit Zustandsübergabe zwischen den Aufrufen

Hurl-Dateien sind einfache Textdateien. Installieren Sie das deb-Paket aus den Releases des Projekts.

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

Eine Testsuite, die Ihre eigene API gegen den Mock testet, befindet sich in 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"

Der Block [Captures] macht daraus einen API-Test und nicht zwei voneinander unabhängige Requests. order_id wird aus der ersten Antwort gelesen und in die URL des zweiten Requests eingesetzt. Die Assertion für charge_id ist der entscheidende Teil des gesamten Tests: Sie weist nach, dass Ihr Dienst den Zahlungsanbieter aufgerufen und die Antwort gespeichert hat. Der Vergleichswert stammt aus dem WireMock-Stub, den Sie zuvor erstellt haben. Damit deckt eine Datei nun beide Teile des Ablaufs ab.

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

Bei einem erfolgreichen Lauf wird für jede Datei eine Zeile sowie eine Zusammenfassung ausgegeben.

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

Bei einem Fehler wird error: Assert failure mit der Datei und der Zeilennummer ausgegeben. Danach folgen der erhaltene und der erwartete Wert. hurl beendet den Prozess mit einem Fehlercode, sodass CI stoppt. Wenn status pending liest, obwohl Sie paid erwartet haben, hat Ihr Dienst die Antwort des Mocks nicht verarbeitet. Als Nächstes sollten Sie das WireMock-Request-Journal unter /__admin/requests prüfen. Dort sehen Sie, ob der Aufruf den Mock überhaupt erreicht hat.

Die Testsuite über den eigenen CI-Runner starten

Mit einem auf demselben Host registrierten Runner ist der Workflow kurz. Der Runner läuft als normaler Prozess auf dem Host. Daher müssen docker und hurl auf diesem Host installiert sein. Von einem gehosteten Image wird nichts übernommen.

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() im Archivierungsschritt ist wichtig. Ohne diese Option wird das Kopieren übersprungen, wenn ein Testlauf fehlschlägt. Dadurch verlieren Sie genau den Report, den Sie prüfen wollten. Die Kopie muss außerdem außerhalb des Workspace abgelegt werden. actions/checkout@v4 führt vor dem Abrufen standardmäßig git clean -ffdx aus. Dadurch werden nicht versionierte Reports beim nächsten Checkout aus dem Repository-Verzeichnis entfernt.

Ergebnisse dauerhaft speichern, nicht nur den letzten Lauf

Eine JUnit-XML-Datei pro Commit beantwortet eine Frage: Ist der Test erfolgreich durchgelaufen? Sie zeigt jedoch nicht, wann ein Endpunkt langsamer wurde, weil niemand diese Dateien auswertet, sobald Sie sie nicht mehr öffnen. Für einen Trend hängen Sie pro Lauf eine Zeile an eine kleine Datenbank auf demselben System an. Eine einzelne Tabelle mit Commit-SHA, Dateiname, Anzahl erfolgreicher Tests, Anzahl fehlgeschlagener Tests und Dauer reicht aus. SQLite in Produktion auf einem VPS ist dafür ein sinnvoller Speicherort: eine Datei, kein Serverprozess, und die gesamte Historie ist in dem Backup enthalten, das Sie ohnehin erstellen. Parsen Sie die --report-json-Ausgabe von Hurl für detaillierte Laufdaten. Sowohl JSON als auch JUnit XML sind maschinenlesbar.

Was einen Container-Rebuild überstehen muss

Mock-Definitionen und Testsuiten sind Quellcode. Sie gehören in ein Repository neben den beschriebenen Dienst und sollten im selben Pull Request geändert werden wie der zugehörige Endpunkt. Ein Stub, der in einer Weboberfläche bearbeitet wurde, oder eine Erwartung, die zur Laufzeit über die REST API an MockServer übergeben wurde, benötigt einen Export oder eine Persistenzkonfiguration, damit sie einen Rebuild übersteht. Bei docker compose down gehen der Container-Speicher und beschreibbare Layer verloren; Daten in Bind Mounts oder benannten Volumes bleiben erhalten. Wenn Ihre Repositories ebenfalls auf eigener Hardware laufen, hält ein selbst gehosteter Git-Server die Fixtures und den Dienst innerhalb derselben Vertrauensgrenze.

Nun zu den praktischen Regeln. Fixieren Sie Image-Tags, da latest ändern kann, wie Ihr Mock Anfragen abgleicht, ohne dass sich etwas in Ihrem Repository ändert. Dieser Fehler lässt sich nur sehr schwer auf seine Ursache zurückführen. Binden Sie Stub-Verzeichnisse schreibgeschützt ein, wenn das Tool nicht in sie schreiben muss. Legen Sie die Stubs eines Mocks niemals in einem benannten Docker-Volume ab, weil das Volume dann zur maßgeblichen Quelle wird und die Kopie in Git unbemerkt veraltet.

Noch ein Punkt, der häufig übersehen wird. Wenn Sie Stubs erstellen, indem Sie echten Datenverkehr über einen Proxy aufzeichnen, lesen Sie jede erzeugte Datei, bevor Sie sie committen. Eine Aufzeichnung enthält exakt die Daten, die das Upstream-System zurückgesendet hat, einschließlich Bearer-Tokens und E-Mail-Adressen von Kunden. Durch das Committen gelangen diese Daten dauerhaft in Ihr Repository, weil Git gelöschte Inhalte in der Historie behält.

FAQ

Was ist der Unterschied zwischen einem API-Mock-Server und einem API-Test-Runner?

Ein Mock-Server beantwortet Anfragen. Er ersetzt eine Abhängigkeit, die Sie aus der CI nicht aufrufen können. Einige Tools führen zusätzlich Vertragstests aus und melden deren Ergebnisse. Ein API-Test-Runner sendet Anfragen an Ihren eigenen Dienst, prüft die Antworten, übernimmt Werte aus einem Aufruf in den nächsten und beendet sich mit einem Fehlercode ungleich 0, wenn eine Prüfung fehlschlägt. Beide Komponenten lösen unterschiedliche Probleme. In einer typischen Konfiguration laufen sie gleichzeitig: Der Runner ruft Ihren Dienst auf, während Ihr Dienst den Mock aufruft.

Kann ich eine interne API von einem gehosteten CI-Runner aus testen?

Ja, mit privater Netzwerkanbindung. Von GitHub gehostete Runner unterstützen ein WireGuard-Overlay oder ein Azure Virtual Network, um private Ressourcen zu erreichen, ohne die API zu veröffentlichen. Die API zu veröffentlichen, einen Tunnel zu betreiben oder eine öffentliche Staging-Kopie zu pflegen, sind weitere Möglichkeiten. Jede davon fügt ein System hinzu, das ausfallen oder Daten offenlegen kann. Ein Runner im selben privaten Netzwerk ruft den Dienst direkt auf. Das ist der wichtigste praktische Grund, warum Teams diese Arbeit selbst hosten.

Wo sollten Mock-Stubs und API-Testsuiten abgelegt werden?

In git, neben dem Dienst, den sie beschreiben. Tools, die Definitionen als Dateien speichern, etwa das mappings/-Verzeichnis von WireMock, die Datendatei von Mockoon, Hurl-Dateien und der .bru-Ordner von Bruno, ermöglichen Code-Reviews und einen Container-Neuaufbau ohne zusätzlichen Aufwand. Tools, die Definitionen in einer Datenbank oder einer Weboberfläche speichern, benötigen einen Backup-Plan und einen Exportschritt. Der Export ist der Teil, den viele erst vergessen, wenn der Container bereits gelöscht ist.

Warum gibt mein Mock 404 zurück, obwohl der Stub korrekt aussieht?

WireMock stellt einen Stub nur bereit, wenn die Anfrage seine konfigurierten Matcher erfüllt. Eine nicht passende Anfrage erhält 404. Wenn eine ähnliche Übereinstimmung existiert, beginnt der Antworttext mit Request was not matched. Danach folgt ein Diff zum ähnlichsten Stub. In diesem Diff wird das abweichende Feld genannt. Wenn keine Stub-Mappings vorhanden sind, erklärt der Antworttext stattdessen, dass die Instanz keine besitzt. Häufige Ursachen sind ein abschließender Schrägstrich im Pfad, ein Content-Type-Header, den der Stub verlangt, den Ihr Client aber nicht gesendet hat, urlPath an einer Stelle, an der der Stub für ein variables Segment urlPathPattern benötigt, sowie ein Body-Matcher, der nicht zur Nutzlast passt. Prüfen Sie zuerst /__admin/requests, um zu bestätigen, dass die Anfrage den Mock überhaupt erreicht hat.

Benötige ich weiterhin Mocks, wenn ich eine Staging-Umgebung habe?

Ja, aus zwei Gründen. Eine Staging-Kopie eines Upstream-Dienstes, den Sie nicht kontrollieren, fällt weiterhin aus und begrenzt weiterhin Ihre Anfragerate. Dadurch schlägt Ihre Testsuite aus Gründen fehl, die nichts mit Ihrem Code zu tun haben. Außerdem kann diese Kopie die Antworten, die Sie am dringendsten testen müssen, nicht erzeugen, etwa eine abgelehnte Karte oder ein Gateway-Timeout. Ein Mock gibt solche Antworten bei Bedarf mit lokaler Netzwerkgeschwindigkeit zurück. Dadurch wird aus einer Testsuite, die gegen eine Sandbox Minuten benötigt, eine Testsuite, die Sekunden benötigt. Verwenden Sie Staging für die abschließende Prüfung vor einem Release und Mocks in der CI.

War dieser Artikel hilfreich?