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

Smart Mock erstellt in Sekunden eine plausible Mock-API aus Ihrem Endpunkt-Schema: realistische E-Mails, Zeitstempel, Namen und weitere Felddaten. Das reicht für viele Frontend-Aufgaben, solange ein Endpunkt immer dieselbe Antwortform liefern soll.

Apidog noch heute testen

Sobald Antworten von der Anfrage abhängen sollen, benötigen Sie bedingtes Mocking. Beispiele:

• POST /login soll für einen bekannten Benutzer 200 und für alle anderen 401 liefern.
• GET /orders/{id} soll abhängig von der ID eine versandte oder stornierte Bestellung zurückgeben.
• Ein Header soll gezielt einen 500 auslösen, damit Sie Fehlerzustände vor dem Production-Release testen.

Apidog bietet dafür zwei Mechanismen:

1. Mock-Erwartungen für regelbasierte Antworten.
2. Mock-Skripte für Berechnungen und Logik, die sich nicht deklarativ abbilden lassen.

Wenn Sie die Grundlagen auffrischen möchten, lesen Sie die API-Mocking-Übersicht. Dieses Tutorial verwendet Apidog; die OpenAPI-Initiative beschreibt den Contract-First-Workflow dahinter.

Was bedingtes Mocking bedeutet

Ein bedingter Mock folgt diesem Muster:

Wenn eine Anfrage bestimmte Eigenschaften hat, liefere eine bestimmte Antwort.

Apidog arbeitet dabei auf zwei Ebenen:

• Feldbezogene dynamische Werte: Steuern den Inhalt einzelner Felder, erzeugen aber weiterhin eine einheitliche Antwortform.
• Mock-Erwartungen: Prüfen Bedingungen und liefern bei Treffer einen eigenen Body, Statuscode und Header zurück.

Mit Erwartungen können Sie mehrere Antwortpfade für denselben Endpunkt definieren: andere Nutzlasten je Pfadparameter, Fehler bei fehlenden Headern oder gezielte Testdaten für bestimmte Request-Bodies.

Feldbezogene dynamische Werte mit Faker.js

Bevor Sie nach Anfragen verzweigen, können Sie einzelne Felder dynamisch erzeugen. In einem Endpoint-Schema verwenden Sie dafür Faker.js-Ausdrücke im Format {{$category.method}}.

{
  "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 erlauben kontrollierbare Testdaten:

• {{$number.int(min=1000,max=9999)}} begrenzt Zahlenwerte.
• {{$date.between(...)}} legt Datumsbereich und Format fest.
• Statischer Text und mehrere Ausdrücke lassen sich in einem Feld kombinieren.

Für lokalisierte Daten können Sie die Mock-Locale anpassen. Die Faker.js-Referenz in Apidog enthält weitere verfügbare Methoden.

Das ist Smart Mock: dynamisch, aber nicht anfrageabhängig. Für Verzweigungen verwenden Sie Mock-Erwartungen.

Anleitung: Login mit 200 oder 401 mocken

Angenommen, POST /login erwartet folgenden JSON-Body:

{
  "username": "[e-mail]",
  "password": "whatever"
}

Für [e-mail] soll der Endpunkt ein Token mit 200 liefern. Alle anderen Anfragen sollen 401 erhalten.

1. Den Mock-Tab öffnen

Je nach Arbeitsmodus konfigurieren Sie Erwartungen an unterschiedlichen Stellen:

• DEBUG-Modus: Endpunkt öffnen und den Tab Mock auswählen.

• DESIGN-Modus: Endpunkt öffnen und den Tab Erweiterter Mock auswählen.

Beide Wege führen zur Liste der Mock-Erwartungen. Falls Sie noch keinen Endpunkt haben, laden Sie Apidog herunter und erstellen oder importieren Sie zuerst /login.

2. Erfolgs-Erwartung anlegen

1. Klicken Sie auf Neue Erwartung.
2. Vergeben Sie den Namen login-success.
3. Fügen Sie eine Bedingung für den Body-Parameter hinzu:
   • Name bzw. JSON-Pfad: username
   • Wert: [e-mail]
4. Hinterlegen Sie diese Antwortdaten:

{
  "token": "mock-jwt-{{$string.uuid}}",
  "user": {
    "id": 4821,
    "username": "[e-mail]",
    "role": "member"
  }
}

Speichern Sie die Erwartung. Der Standardstatus ist 200, daher ist für diesen Pfad keine weitere Konfiguration nötig.

Für verschachtelte JSON-Werte verwenden Sie Punktnotation, beispielsweise user.email.

3. Fallback für ungültige Logins anlegen

1. Klicken Sie erneut auf Neue Erwartung.
2. Nennen Sie sie login-failure.
3. Lassen Sie die Bedingungen leer. Dadurch wird die Regel zum Fallback.
4. Verwenden Sie diesen Response-Body:

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

Öffnen Sie anschließend den Tab Mehr und setzen Sie den HTTP-Statuscode auf 401.

Im Tab Mehr können Sie außerdem konfigurieren:

• Antwortverzögerung in Millisekunden
• eigene Response-Header
• alternative Statuscodes

Eine Verzögerung von beispielsweise 400 ms ist nützlich, um Ladeindikatoren im Frontend zu testen.

4. Reihenfolge der Erwartungen prüfen

Apidog wertet Erwartungen von oben nach unten aus. Die erste passende Regel gewinnt.

Ordnen Sie die Regeln daher so an:

1. login-success mit Bedingung für [e-mail]
2. login-failure ohne Bedingung als Fallback

Steht die bedingungslose Regel oben, fängt sie jede Anfrage ab. Die Erfolgsregel würde dann nie ausgeführt.

Testen Sie anschließend die Mock-URL:

# Bekannter Benutzer -> 200 mit Token
curl -X POST https://<ihr-mock-host>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"[e-mail]","password":"whatever"}'

# Anderer Benutzer -> 401
curl -X POST https://<ihr-mock-host>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"[e-mail]","password":"whatever"}'

Anleitung: Unterschiedliche Antworten für /orders/{id}

Ein weiterer häufiger Fall: Ihre UI soll verschiedene Bestellzustände anzeigen, ohne dass ein Live-Backend notwendig ist.

Legen Sie eine Erwartung pro Zustand an und prüfen Sie jeweils den Pfadparameter id.

Versandte Bestellung

Erwartung: order-shipped

Bedingung: Pfadparameter id ist 5001

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

Stornierte Bestellung

Erwartung: order-cancelled

Bedingung: Pfadparameter id ist 5002

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

Fügen Sie abschließend eine bedingungslose Fallback-Erwartung hinzu, etwa für ausstehende Bestellungen. Platzieren Sie die spezifischen Regeln immer oberhalb des Fallbacks.

Sie können Bedingungen kombinieren. Wenn Sie zum Beispiel eine Pfadparameter- und eine Header-Bedingung definieren, müssen beide erfüllt sein. Apidog kombiniert mehrere Bedingungen mit AND-Logik.

Mögliche Bedingungstypen sind:

• Body-Parameter
• Pfadparameter
• Query-Parameter
• Header
• Cookies
• IP-Adressen

Fehlerzustände gezielt erzwingen

Sie brauchen kein defektes Backend, um Fehlerbehandlung zu testen. Legen Sie eine Erwartung an, die über einen steuerbaren Request-Wert aktiviert wird.

Beispiel: Ein 500 wird über den Header X-Mock-Scenario: server-error ausgelöst.

1. Erstellen Sie eine Erwartung mit folgender Header-Bedingung:
   • Header: X-Mock-Scenario
   • Wert: server-error
2. Setzen Sie im Tab Mehr den HTTP-Status auf 500.
3. Definieren Sie einen realistischen Fehler-Body:

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

Ihr Client kann den Fehler nun gezielt auslösen:

curl https://<ihr-mock-host>/orders/5001 \
  -H "X-Mock-Scenario: server-error"

Dasselbe Muster funktioniert für:

• 404 Not Found
• 429 Too Many Requests, optional mit Retry-After-Header
• 503 Service Unavailable

Wenn Sie diese Antworten automatisiert prüfen möchten, passt der Leitfaden zu API-Assertions zu diesem Setup.

In gemeinsamen Projekten lassen sich Erwartungen für lokale und Cloud-Mock-Umgebungen unabhängig aktivieren oder deaktivieren. So bleibt eine 500-Regel lokal aktiv, ohne Teammitglieder im Cloud-Mock zu blockieren.

Wenn Regeln nicht reichen: Mock-Skripte

Mock-Erwartungen sind deklarativ: Sie prüfen Bedingungen und liefern vordefinierte Antworten. Für Berechnungen oder komplexere Transformationen verwenden Sie ein Mock-Skript.

Ein Mock-Skript ist JavaScript, das im Bereich Mock-Skript unten im Tab Mock aktiviert wird. Verfügbar sind unter anderem diese globalen Objekte:

• $$.mockRequest für die eingehende Anfrage:
  • getParam(key)
  • headers
  • cookies
  • body
  • formdata
  • urlencoded
• $$.mockResponse für die ausgehende Antwort:
  • setBody()
  • setCode()
  • setDelay()
  • json()
  • headers
  • code

Beispiel: Berechnen Sie eine Bestellsumme aus den Request-Positionen und übernehmen Sie die angefragte Währung.

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:

1. Smart Mock erzeugt eine Basisantwort.
2. Das Skript liest $$.mockRequest und die aktuelle Mock-Response.
3. Das Skript berechnet oder verändert Daten.
4. $$.mockResponse.setBody() und bei Bedarf setCode(), setDelay() oder Header setzen das Ergebnis.
5. Apidog liefert die finale Antwort zurück.

Für weiterführende JavaScript-Logik ist die MDN JavaScript-Referenz hilfreich.

Wichtige Einschränkung: Skripte und Erwartungen nicht mischen

Mock-Skripte funktionieren nur mit Smart Mock. Sie werden nicht auf Mock-Erwartungen oder Antwortbeispiele angewendet.

Wenn eine Erwartung passt, wird das Mock-Skript nicht ausgeführt.

Wählen Sie deshalb pro Endpunkt bewusst einen Ansatz:

• Mock-Erwartungen: feste Bedingungen, feste Response-Bodies, gezielte Statuscodes.
• Mock-Skripte: berechnete oder aus mehreren Eingaben abgeleitete Antworten.

Prioritätsreihenfolge verstehen

Für jede Mock-Anfrage arbeitet Apidog in dieser Reihenfolge:

1. Mock-Erwartungen prüfen
   
   Erwartungen werden von oben nach unten ausgewertet. Die erste Regel, deren Bedingungen vollständig passen, liefert die Antwort.

2. Mock-Methodenpriorität anwenden
   
   Falls keine Erwartung passt, verwendet Apidog die in Projekteinstellungen → Funktions-Einstellungen → Mock-Einstellungen festgelegte Mock-Methodenpriorität. Dort erzeugt Smart Mock die Antwort; ein aktiviertes Mock-Skript wird dabei ebenfalls ausgeführt.

Praktische Regel:

• Spezifische Erwartungen zuerst.
• Allgemeine Fallback-Erwartungen zuletzt.
• Smart Mock für alles, was nicht durch Erwartungen abgedeckt wird.

Der Beitrag zu API-Mocking-Anwendungsfällen hilft bei der Entscheidung, welche Ebene für welches Szenario passt.

Einschränkungen vor dem Deployment

Beachten Sie diese Punkte, um Debugging-Aufwand zu vermeiden:

• Parameterbedingungen unterstützen keine {{Variablen}}. Projekt- und Umgebungsvariablen stehen in Mock-Erwartungen nicht zur Verfügung.
• Body-Parameter-Bedingungen funktionieren nur mit JSON, nicht mit XML.
• Verschachtelte JSON-Felder müssen über JSON-Pfade wie user.email angesprochen werden.
• Das Format der Bedingung muss zur API-Spezifikation passen. Für Formular-Endpunkte verwenden Sie Formular-Daten, nicht JSON.
• In Mock-Skripten gibt es keine Protokollierungsfunktion.
• Das pm-Objekt ist in Mock-Skripten nicht verfügbar.
• Apidog-Variablen können innerhalb von Mock-Skripten nicht verwendet werden. Halten Sie die Logik daher eigenständig.

Mock-Erwartungen und Skripte unterliegen laut Dokumentation keiner Plan-Einschränkung. Lokal und Cloud unterscheiden sich funktional vor allem durch die unabhängige Aktivierung einzelner Erwartungen je Umgebung.

Workflow mit der Apidog CLI automatisieren

Mocking selbst ist eine GUI- und Cloud-Funktion: Die Mock-Engine stellt Endpunkte über lokale und Cloud-Mock-URLs bereit. Die CLI startet keinen lokalen Mock-Server.

Die Apidog CLI hilft stattdessen dabei, die API-Ressourcen und Schemata zu verwalten, auf denen Ihre Mocks basieren.

Da Smart Mock Antworten aus Endpunkt-Schemas erzeugt, hängt die Qualität des Mocks direkt von der Spezifikation ab. CLI und KI-Coding-Agenten wie Cursor, Claude Code, Trae oder Codex können Endpunkte und Schemata im Projekt aktualisieren. Ändern Sie den Vertrag im Code und synchronisieren Sie ihn, damit die Mock-Ausgabe aktuell bleibt.

Sobald das echte Backend verfügbar ist, führen Sie Testszenarien headless in CI aus:

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

Der Befehl führt Testszenarien aus und meldet die Ergebnisse. Damit verwenden Mock und Verifikation dieselbe Quelle der Wahrheit.

Weitere Schritte:

• Apidog CLI installieren
• Apidog CLI mit GitHub Actions verwenden

FAQ

Warum wird meine Erwartung ignoriert?

Prüfen Sie zuerst die Reihenfolge. Eine allgemeine Regel ohne Bedingungen kann jede Anfrage abfangen, wenn sie über einer spezifischen Erwartung steht.

Prüfen Sie außerdem das Request-Format:

• JSON-Body: Bedingung über JSON-Pfad angeben.
• Formular-Endpunkt: Formular-Daten verwenden.
• Request muss zur API-Spezifikation passen.

Die API-Mocking-Übersicht hilft bei der Grundkonfiguration.

Kann ich ein Mock-Skript und eine Mock-Erwartung für dieselbe Antwort verwenden?

Nein. Mock-Skripte laufen nur mit Smart Mock. Sobald eine Erwartung passt, wird das Skript übersprungen.

Verwenden Sie Erwartungen für regelbasierte Verzweigungen und Skripte für berechnete Antworten.

Wie gebe ich 401 oder 500 zurück, ohne den normalen 200-Pfad zu ändern?

Erstellen Sie eine dedizierte Erwartung mit einer steuerbaren Bedingung, etwa einem Header. Setzen Sie dann im Tab Mehr den gewünschten HTTP-Statuscode.

Die Standardantwort bleibt 200; der Fehler tritt nur bei passender Bedingung auf.

Können Bedingungen Umgebungsvariablen verwenden?

Nein. {{Variablen}} sind in Mock-Erwartungen nicht verfügbar. Verwenden Sie Literalwerte in den Bedingungen.

Was passiert, wenn keine Erwartung passt?

Apidog verwendet die Mock-Methodenpriorität aus Projekteinstellungen → Funktions-Einstellungen → Mock-Einstellungen. Dort kann Smart Mock anhand Ihres Schemas eine Antwort generieren.

Wenn Sie stattdessen immer einen kontrollierten Fallback liefern möchten, erstellen Sie eine letzte Erwartung ohne Bedingungen.

Zusammenfassung

Smart Mock deckt dynamische Standarddaten ab. Mock-Erwartungen ergänzen die fehlende Verzweigung:

• 200 für bekannte Benutzer, 401 für alle anderen
• verschiedene Order-Bodies je ID oder Status
• gezielte 500, 404, 429 oder 503 für Fehler-Tests

Verwenden Sie Mock-Skripte nur, wenn die Antwort berechnet werden muss. Denken Sie an die Priorität: spezifische Erwartungen zuerst, Fallbacks zuletzt und Smart Mock für alles Übrige.

Laden Sie Apidog herunter, um Ihren ersten bedingten Mock zu erstellen.