Apidog: Bedingte Mock-Daten mit benutzerdefinierten Regeln und Mock-Skripten zurückgeben

Smart Mock verschafft Ihnen in Sekundenschnelle eine gefälschte API. Es liest Ihr Endpunkt-Schema und liefert plausible Daten zurück: eine echt aussehende E-Mail, einen sinnvollen Zeitstempel, einen Namen, der nicht xJ8kQ ist. Für die meisten Frontend-Arbeiten reicht das aus, um Sie zu entlasten.

Dann stoßen Sie auf einen Fall, den Smart Mock nicht abdecken kann. Sie möchten, dass /login für einen bekannten Benutzer 200 zurückgibt und 401 andernfalls. Sie möchten, dass /orders/{id} für eine ID eine versandte Bestellung und für eine andere eine stornierte Bestellung zurückgibt. Sie möchten auf Abruf einen 500 erzwingen, damit Ihre Fehlerbehandlung getestet wird, bevor sie in der Produktion ankommt. Smart Mock liefert pro Endpunkt eine einzige Form zurück, kann also nicht je nach Anfrage verzweigen. Das ist die Lücke, die dieser Leitfaden schließt.

Apidog deckt dies mit zwei Funktionen ab: Mock-Erwartungen (mock expectations) für regelbasierte bedingte Antworten und Mock-Skripte (mock scripts) für Logik, die Regeln nicht ausdrücken können. Dieser Leitfaden zeigt beides mit konkreten Beispielen und erklärt die Prioritätsreihenfolge, damit Ihre benutzerdefinierten Regeln Smart Mock jedes Mal übertreffen. Wenn Sie neu bei den Grundlagen sind, ist die API-Mocking-Übersicht eine gute Aufwärmübung, und Apidog ist das Tool, das wir durchweg verwenden werden. Die OpenAPI-Initiative dokumentiert den Contract-First-Workflow, der all dies ermöglicht.

Schaltfläche

Was bedingtes Mocking tatsächlich bedeutet

Ein bedingter Mock ist eine Regel: Wenn die eingehende Anfrage so aussieht, gib das zurück. Apidog erstellt diese Regeln aus zwei Schichten.

Die erste Schicht ist die feldbezogene Anpassung innerhalb des Endpunkt-Schemas. Sie können ein Feld an einen festen Wert binden oder einen dynamischen Faker.js-Ausdruck anhängen, sodass er bei jedem Aufruf variiert. Dies steuert, was ein Feld enthält, liefert aber immer noch eine einzige Antwortform für den Endpunkt zurück.

Die zweite Schicht ist die Mock-Erwartung für die vollständige Antwort. Eine Erwartung ist eine benannte Regel mit optionalen Bedingungen und einem eigenen Antworttext, Statuscode und Headern. Eine Erwartung ohne Bedingungen gibt feste Daten bedingungslos zurück. Eine Erwartung mit Bedingungen gibt ihre Daten nur zurück, wenn die Anfrage übereinstimmt. Stapeln Sie ein paar davon und Sie erhalten eine echte Verzweigung: Antwort B, wenn die Anfrage Bedingung A entspricht, ein Fehlertext, wenn ein Header fehlt, eine andere Nutzlast pro Pfadparameter.

Diese zweite Schicht ermöglicht fehlerhafte Zustände auf Abruf und anfragespezifische Bodies. Der Rest dieses Leitfadens befasst sich damit.

Zuerst feldbezogene dynamische Werte

Vor der Verzweigung ist es hilfreich zu sehen, wie ein einzelnes Feld seinen Wert erhält, da Ihre bedingten Antworten dieselbe Syntax wiederverwenden werden.

Innerhalb des Schemas eines Endpunkts kann jedes String-Feld einen Faker.js-Ausdruck im Format {{$category.method}} enthalten. Apidog löst diesen bei jedem Mock-Aufruf neu auf, basierend auf den Feldtypen, die Ihre JSON Schema-Definition bereits deklariert.

{
  "id": "{{$number.int(min=1000,max=9999)}}",
  "customer": "{{$person.fullName}}",
  "email": "{{$internet.email}}",
  "product": "{{$commerce.productName}}",
  "shippingAddress": "{{$location.streetAddress}}, {{$location.city}}",
  "orderedAt": "{{$date.between(from='2024-01-01',to='2024-12-31',format='yyyy-MM-dd')}}"
}

Parametrisierte Methoden funktionieren, so begrenzt {{$number.int(min=1000,max=9999)}} den Wert und {{$date.between(...)}} fixiert einen Bereich und ein Format. Sie können statischen Text und mehrere Ausdrücke in einem Feld verketten, wodurch die obige Adresse aufgebaut wird. Wenn Sie regionalspezifische Daten benötigen, unterstützt Apidog anpassbare Mock-Locales, sodass Ihre Namen, Adressen und Telefonnummern einer bestimmten Sprache oder einem bestimmten Land entsprechen. Die Faker.js-Referenz in Apidog deckt den vollständigen Methodenkatalog ab.

Dies ist das Gebiet von Smart Mock. Es ist dynamisch, aber nicht bedingt. Um bei der Anfrage zu verzweigen, gehen Sie zu den Erwartungen über.

Der kanonische Fall: POST /login nimmt einen JSON-Body mit username und password entgegen. Ein bekannter Benutzer sollte 200 mit einem Token erhalten. Alle anderen sollten 401 erhalten.

Den richtigen Tab öffnen

Wo Sie dies konfigurieren, hängt von Ihrem Arbeitsmodus ab:

Im DEBUG-Modus (Request-first) öffnen Sie den Endpunkt und klicken auf den Tab Mock.

Im DESIGN-Modus (Design-first) öffnen Sie den Endpunkt und klicken auf den Tab Erweiterter Mock.

Beide führen zur gleichen Erwartungsliste. Wenn Sie mitmachen möchten und die App noch nicht haben, laden Sie Apidog herunter und importieren oder erstellen Sie zuerst einen /login-Endpunkt.

Die Erfolgs-Erwartung hinzufügen

Klicken Sie auf Neue Erwartung. Geben Sie ihr einen Erwartungsnamen wie login-success. Fügen Sie nun eine Bedingung hinzu. Da username im JSON-Anfragekörper liegt, gleichen Sie es als Body-Parameter ab: Geben Sie den JSON-Pfad der Ziel-Eigenschaft, username, in das Namensfeld ein und setzen Sie die Bedingung auf alice@example.com.

Body-Parameter-Bedingungen sind nur JSON und werden über den JSON-Pfad im Namensfeld abgeglichen, daher verwenden verschachtelte Eigenschaften Punktpfade wie user.email. Füllen Sie die Antwortdaten mit der Erfolgsnutzlast aus:

{
  "token": "mock-jwt-{{$string.uuid}}",
  "user": {
    "id": 4821,
    "username": "alice@example.com",
    "role": "member"
  }
}

Speichern. Der standardmäßige HTTP-Statuscode ist 200, daher müssen Sie für den Erfolgsfall nichts weiter tun.

Die Fehler-Erwartung hinzufügen

Klicken Sie erneut auf Neue Erwartung. Nennen Sie sie login-failure und lassen Sie ihre Bedingungen leer, damit sie als Fallback dient. Setzen Sie ihre Antwortdaten auf den Fehlertext:

{
  "error": "invalid_credentials",
  "message": "Username or password is incorrect."
}

Diese benötigt einen nicht-standardmäßigen Status. Öffnen Sie den Tab Mehr der Erwartung und setzen Sie den HTTP-Statuscode auf 401. Beachten Sie dort, dass der Tab "Mehr" auch der Ort ist, an dem Sie die Antwortverzögerung in Millisekunden (Standard 0) und alle benutzerdefinierten Antwort-Header einstellen. Eine Verzögerung von 400 ms ist eine günstige Möglichkeit, sicherzustellen, dass Ihr Lade-Spinner tatsächlich angezeigt wird.

Die Reihenfolge ist wichtig

Erwartungen werden von oben nach unten ausgewertet, und die erste Übereinstimmung gewinnt. Daher muss login-success über login-failure stehen. Eine Anfrage mit username gleich alice@example.com entspricht der ersten Regel und gibt das Token zurück. Alles andere fällt auf die bedingungslose Fehlerregel zurück und erhält den 401. Wenn Sie die Reihenfolge umkehren würden, würde die leere Bedingungsregel alles abgleichen und Ihr Erfolgsfall würde nie ausgelöst.

Kopieren Sie die Mock-URL vom Endpunkt und testen Sie beide Pfade:

# bekannter Benutzer -> 200 mit einem Token
curl -X POST https://<ihr-mock-host>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"alice@example.com","password":"whatever"}'

# jeder andere -> 401
curl -X POST https://<ihr-mock-host>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"stranger@example.com","password":"whatever"}'

Anleitung: Verschiedene Bodies für /orders/{id} nach Status

Der zweite häufige Fall verzweigt basierend auf einem Pfadparameter. Sie möchten, dass /orders/{id} für eine ID eine versandte Bestellung und für eine andere eine stornierte Bestellung zurückgibt, damit Ihre Benutzeroberfläche jeden Zustand ohne ein Live-Backend rendern kann.

Erstellen Sie eine Erwartung pro Zustand. Fügen Sie für jede eine Bedingung für den Pfadparameter id hinzu und füllen Sie dann die passenden Antwortdaten aus.

Erwartung order-shipped, Bedingung: Pfadparameter id gleich 5001.

{
  "id": 5001,
  "status": "shipped",
  "total": 129.90,
  "trackingNumber": "1Z{{$string.alphanumeric(length=16)}}",
  "shippedAt": "{{$date.recent(days=3,format='yyyy-MM-dd')}}"
}

Erwartung order-cancelled, Bedingung: Pfadparameter id gleich 5002.

{
  "id": 5002,
  "status": "cancelled",
  "total": 0,
  "cancelledAt": "{{$date.recent(days=1,format='yyyy-MM-dd')}}",
  "refundIssued": true
}

Fügen Sie eine letzte Erwartung ohne Bedingungen hinzu, die eine generische ausstehende Bestellung zurückgibt, sodass jede andere ID immer noch eine gültige Antwort erhält, anstatt durchzufallen. Ordnen Sie die spezifischen Regeln über dem Fallback an, speichern Sie, und Sie haben einen Mock, der jeden Bestellstatus auf Abruf rendert. Das Mischen von Bedingungen funktioniert ebenfalls: Fügen Sie eine Header-Bedingung neben der Pfadbedingung hinzu, und beide müssen erfüllt sein, da Apidog mehrere Bedingungen mit AND-Logik kombiniert (eine Schnittmenge der Bedingungen, wie es in der Dokumentation heißt).

Bedingungen sind nicht auf Body und Pfad beschränkt. Sie können nach Abfrageparametern, Header-Parametern, Cookie-Parametern und sogar IP-Adressen abgleichen, wodurch Sie eine Antwort während eines Tests auf bestimmte Clients beschränken können.

Fehlerzustände auf Abruf erzwingen

Sie benötigen kein kaputtes Backend, um fehlerhafte Antworten zu testen. Eine Erwartung plus der Tab Mehr gibt Ihnen jeden gewünschten Status.

Um einen 500 zu erzwingen, fügen Sie eine Erwartung hinzu, deren Bedingung etwas ist, das Sie vom Client aus steuern können, z. B. ein Header X-Mock-Scenario gleich server-error. Setzen Sie die Antwortdaten auf einen realistischen Fehlertext und den HTTP-Statuscode im Tab "Mehr" auf 500.

{
  "error": "internal_error",
  "requestId": "{{$string.uuid}}",
  "message": "Something went wrong on our end. Please retry."
}

Nun liefert derselbe Endpunkt standardmäßig einen normalen 200 und einen 500, wann immer Sie diesen Header senden. Machen Sie dasselbe für 404, 429 (mit einem im Tab "Mehr" eingestellten Retry-After-Header) oder 503. Ihre Frontend-Fehlerbehandlung hat endlich etwas zu fangen. Wenn Sie diese Antworten in automatisierten Prüfungen bestätigen, passt der Leitfaden zu API-Assertions gut zu diesem Setup.

Ein Detail für gemeinsame Projekte: Jede Erwartung kann in der Erwartungsliste unabhängig für lokale und Cloud-Mock-Umgebungen ein- oder ausgeschaltet werden. So können Sie eine 500-Regel lokal aktiv halten, während Sie sie im Cloud-Mock, den Ihre Teamkollegen nutzen, deaktiviert lassen.

Wenn Regeln nicht ausreichen: Mock-Skripte

Erwartungen sind deklarativ. Sie gleichen ab und geben zurück, aber sie können nicht rechnen. Wenn Sie ein von der Anfrage abgeleitetes Feld, eine aus Posten summierte Gesamtsumme oder einen Body benötigen, dessen Form sich basierend auf mehreren Eingaben gleichzeitig ändert, greifen Sie zu einem Mock-Skript.

Ein Mock-Skript ist JavaScript, das gegen die Mock-Antwort ausgeführt wird. Es befindet sich im Mock-Skript-Bereich unten im Tab Mock und wird mit einem Schalter aktiviert. Das Skript stellt zwei globale Variablen zur Verfügung:

$$.mockRequest: liest die eingehende Anfrage über getParam(key) sowie headers, cookies, body, formdata und urlencoded.
$$.mockResponse: formt die ausgehende Antwort über setBody(), setCode(), setDelay(), json() und die headers- und code-Eigenschaften.

Hier ist ein Skript, das eine Bestellsumme aus den gesendeten Posten berechnet und den Währungs-Header des Aufrufers zurückgibt:

const body = $$.mockRequest.body;
const items = body.items || [];

const subtotal = items.reduce((sum, item) => {
  return sum + item.price * item.quantity;
}, 0);

const currency = $$.mockRequest.headers["x-currency"] || "USD";

$$.mockResponse.setCode(201);
$$.mockResponse.setBody({
  orderId: Math.floor(Math.random() * 90000) + 10000,
  currency: currency,
  subtotal: subtotal,
  tax: Number((subtotal * 0.08).toFixed(2)),
  total: Number((subtotal * 1.08).toFixed(2))
});

Der Ablauf ist: Smart Mock generiert eine anfängliche Antwort, Ihr Skript liest $$.mockRequest und das aktuelle $$.mockResponse, wendet seine Logik an, ruft $$.mockResponse.setBody() (und setCode, setDelay oder headers nach Bedarf) auf, und die Engine gibt das Endergebnis zurück. Die MDN JavaScript-Referenz ist ein zuverlässiger Begleiter, wenn Sie die Logik mit Array-Methoden oder Datumsberechnungen weiter vorantreiben möchten.

Die eine Regel, die Leute stolpern lässt

Mock-Skripte funktionieren nur mit Smart Mock. Sie gelten nicht für Mock-Erwartungen oder Antwortbeispiele. Dies ist das Wichtigste, was Sie verinnerlichen müssen: Sie können ein Mock-Skript nicht mit einer erwartungsbasierten Antwort kombinieren. Wenn eine Erwartung der Anfrage entspricht, wird das Skript nie ausgeführt. Wählen Sie also pro Endpunkt einen Ansatz. Verwenden Sie Erwartungen, wenn Sie bei festen Bedingungen verzweigen und feste Bodies zurückgeben. Verwenden Sie ein Mock-Skript, wenn Sie eine berechnete Ausgabe von der generierten Basis von Smart Mock benötigen.

Wie sich die Prioritätsreihenfolge auflöst

Fassen Sie alles zusammen, und hier ist die Reihenfolge, die Apidog für jede Mock-Anfrage durchläuft:

Es prüft Ihre Erwartungen von oben nach unten. Die erste Erwartung, deren Bedingungen alle übereinstimmen, gewinnt, und ihre Antwort wird zurückgegeben. Deshalb übertreffen benutzerdefinierte Regeln Smart Mock: Eine übereinstimmende Erwartung umgeht alles darunter.
Wenn keine Erwartung übereinstimmt, greift Apidog auf die Mock-Methodenpriorität zurück, die Sie in Projekteinstellungen - Funktions-Einstellungen - Mock-Einstellungen festgelegt haben. Das ist die Ebene, auf der Smart Mock (und jedes daran angehängte Mock-Skript) die Antwort erzeugt.

Das mentale Modell ist einfach: spezifische Regeln zuerst, generierte Daten an zweiter Stelle. Ordnen Sie Ihre Erwartungen vom spezifischsten zum am wenigsten spezifischen, behalten Sie einen bedingungslosen Fallback am Ende, wenn Sie eine garantierte Übereinstimmung wünschen, und lassen Sie Smart Mock alles andere erledigen. Für eine tiefere Betrachtung, wann welche Schicht zu verwenden ist, ordnet der Leitfaden zu API-Mocking-Anwendungsfällen gängige Szenarien den Funktionen zu.

Wichtige Dinge, die Sie vor dem Deployment wissen sollten

Einige Einschränkungen ersparen Ihnen eine verwirrende Debugging-Sitzung:

Parameterbedingungen unterstützen keine {{Variablen}}. Apidog-Projekt- und Umgebungsvariablen sind innerhalb von Mock-Erwartungen nicht verfügbar, daher geben Sie Literalwerte in Ihre Bedingungen ein.
Body-Parameter-Bedingungen sind nur JSON, nicht XML, und müssen über den JSON-Pfad im Namensfeld abgeglichen werden.
Das Format des Anfrage-Bodies in einer Bedingung muss der API-Spezifikation entsprechen. Ein Formular-Daten-Endpunkt muss mit Formular-Daten-Platzierung gemockt werden, nicht mit JSON.
Innerhalb von Mock-Skripten gibt es keine Protokollierungsfunktion, das pm-Objekt ist nicht verfügbar (es ist eine andere Ausführungsumgebung als bei Testskripten), und Apidog-Variablen können nicht verwendet werden. Halten Sie die Skriptlogik eigenständig.

Keine dieser Funktionen unterliegt einer Plan-Einschränkung in der Dokumentation. Der einzige Unterschied zwischen lokal und Cloud ist funktional: der zuvor beschriebene unabhängige Ein-/Aus-Schalter pro Umgebung, keine Paywall.

Den Workflow mit der Apidog CLI automatisieren

Mocking in Apidog ist eine GUI- und Cloud-Funktion. Die Mock-Engine bedient Ihre Endpunkte von lokalen und Cloud-Mock-URLs, und es gibt keinen CLI-Befehl, der einen laufenden Mock-Server startet. Was die Apidog CLI hinzufügt, ist die Kontrolle über die Ressourcen, aus denen diese Mocks erstellt werden.

Mock-Antworten werden aus dem Endpunkt-Schema generiert, sodass die Genauigkeit Ihres Mocks der Genauigkeit Ihrer Spezifikation folgt. Die CLI und die KI-Coding-Agenten, die sie antreiben (Cursor, Claude Code, Trae, Codex), können die Endpunkte und Schemata in Ihrem Projekt erstellen und aktualisieren. Ändern Sie den Vertrag im Code, synchronisieren Sie ihn, und die Mock-Ausgabe bleibt korrekt, ohne dass jemand die App erneut öffnen muss.

Sobald der Mock die Frontend-Arbeit entblockt hat, werden die Testszenarien desselben Projekts headless in CI ausgeführt, um das reale Backend gegen den vom Mock beschriebenen Vertrag zu validieren:

apidog run -t <scenario_id> -e <env_id> -r cli

Dieser einzelne Befehl führt Ihre Testszenarien aus und meldet die Ergebnisse, sodass Mock und Verifizierung eine einzige Quelle der Wahrheit teilen. Der Apidog CLI Installationsleitfaden behandelt die Einrichtung, und der Apidog CLI in GitHub Actions Walkthrough bindet ihn in eine Pipeline ein.

FAQ

Warum wird meine Erwartung ignoriert, obwohl die Bedingung richtig aussieht? Fast immer liegt es an der Reihenfolge oder einem Formatfehler. Erwartungen werden von oben nach unten ausgewertet und die erste Übereinstimmung gewinnt, sodass eine allgemeine, leere Bedingungsregel, die über einer spezifischen sitzt, die Anfrage „schluckt“. Bestätigen Sie auch, dass das Body-Format der Spezifikation entspricht (JSON-Pfad für JSON-Bodies, Formular-Daten-Platzierung für Formular-Endpunkte). Die API-Mocking-Übersicht behandelt die Grundlagen der Einrichtung, wenn Sie dies überprüfen möchten.

Kann ich ein Mock-Skript und eine Mock-Erwartung für dieselbe Antwort verwenden? Nein. Mock-Skripte werden nur mit Smart Mock ausgeführt. Sie werden von Mock-Erwartungen und Antwortbeispielen ignoriert. Wenn eine Erwartung übereinstimmt, wird das Skript nie ausgeführt, wählen Sie also pro Endpunkt einen Ansatz: Erwartungen für regelbasierte Verzweigungen, Skripte für berechnete Ausgaben.

Wie gebe ich einen 401 oder 500 zurück, ohne den standardmäßigen 200 zu unterbrechen? Fügen Sie eine dedizierte Erwartung mit einer Bedingung hinzu, die Sie vom Client aus steuern können (ein Header funktioniert gut), öffnen Sie dann den Tab „Mehr“ und setzen Sie den HTTP-Statuscode. Die Standardantwort bleibt 200; der Fehler wird nur ausgelöst, wenn die Bedingung übereinstimmt.

Können Bedingungen meine Umgebungsvariablen verwenden? Nein. Apidog {{Variablen}}-Werte sind innerhalb von Mock-Erwartungen nicht verfügbar, und Parameterbedingungen unterstützen keine {{Variablen}}. Verwenden Sie Literalwerte in Bedingungen.

Was passiert, wenn überhaupt keine Erwartung übereinstimmt? Apidog greift auf die Mock-Methodenpriorität in Projekteinstellungen - Funktions-Einstellungen - Mock-Einstellungen zurück, wo Smart Mock eine Antwort aus Ihrem Schema generiert. Das Hinzufügen einer bedingungslosen Fallback-Erwartung ist der Weg, um stattdessen einen spezifischen Fallback zu garantieren.

Zusammenfassung

Smart Mock deckt den Normalfall ab, und Mock-Erwartungen behandeln alles, was ein Wenn enthält: 200 für einen bekannten Benutzer und 401 andernfalls, einen anderen Bestell-Body pro Status, einen 500 auf Abruf. Greifen Sie nur dann zu einem Mock-Skript, wenn Sie eine berechnete Ausgabe benötigen, die Regeln nicht ausdrücken können, und denken Sie daran, dass es nur mit Smart Mock ausgeführt wird. Beachten Sie die Prioritätsreihenfolge (spezifische Erwartungen zuerst, generierte Daten an zweiter Stelle), und Ihre Mocks werden genau so verzweigen, wie es echte APIs tun. Laden Sie Apidog herunter, um Ihren ersten bedingten Mock kostenlos zu erstellen, keine Kreditkarte erforderlich.