Wie man parametrisierte API-Tests mit CSV und JSON ausführt

Sie haben einen Login-Test geschrieben. Er ist erfolgreich. Dann stellt ein Teamkollege die offensichtliche Frage: Besteht er auch für das gesperrte Konto, die unbestätigte E-Mail-Adresse, das Passwort mit einem nachgestellten Leerzeichen, die SQL-Injection-Zeichenkette, die irgendjemand schließlich in das Feld einfügen wird? Jetzt haben Sie eine Wahl. Kopieren Sie diesen Test fünfmal und ändern Sie einen Wert in jeder Kopie, oder finden Sie einen Weg, denselben Test mit vielen Eingabezeilen zu füttern und ihn alle ausführen zu lassen.

Der Copy-Paste-Weg ist, wie die meisten Testsuiten verrotten. Fünf nahezu identische Tests entwickeln sich im Laufe eines Jahres auseinander. Einer erhält eine neue Assertion, die anderen nicht. Eine Feldumbenennung unterbricht vier davon stillschweigend. Am Ende pflegen Sie fünf Dinge, die eigentlich eines sein sollten. Parametrisiertes Testen behebt dies an der Wurzel: Sie schreiben den Test einmal und verweisen ihn dann auf eine Tabelle von Eingaben und erwarteten Ausgaben. Ein Szenario, Hunderte von Fällen, ein einziger Bearbeitungsort.

Was parametrisiertes Testen wirklich bedeutet

Parametrisiertes Testen, manchmal auch datengesteuertes Testen genannt, trennt die Logik eines Tests von den Daten, gegen die er ausgeführt wird. Die Logik ist die Abfolge der Schritte: eine Anfrage senden, den Statuscode überprüfen, ein Feld in der Antwort validieren. Die Daten sind die Menge der Eingaben und Erwartungen, gegen die diese Logik ausgeführt werden soll.

Stellen Sie sich ein einzelnes Testszenario für einen Endpunkt mit Rabattcodes vor. Die Logik ist immer dieselbe. Senden Sie POST /api/orders mit einem Code und überprüfen Sie dann die Antwort. Die Daten ändern sich pro Fall:

Fünf Zeilen, fünf unterschiedliche Verhaltensweisen, ein Test. Der Runner iteriert über die Zeilen. Bei jedem Durchlauf bindet er die Spaltenwerte an Variablen, sendet die Anfrage und überprüft die Assertions gegen die Erwartungen dieser Zeile. Wenn Zeile 3 fehlschlägt, weil der abgelaufene Code 200 statt 410 zurückgab, erhalten Sie einen klaren Fehler, der auf eine einzige Zeile verweist. Sie müssen nicht fünf separate Testdateien durchsuchen, um herauszufinden, welche Kopie defekt ist.

Dieses Muster ist am wichtigsten an den Rändern. Die Absicherung des "Happy Path" ist einfach zu schreiben und fängt selten den Fehler ab, der Sie um 2 Uhr morgens weckt. Die Fehler liegen in den Grenzbereichen: der leere String, die negative Zahl, der Unicode-Name, das abgelaufene Token, der Wert, der einen Cent über dem Limit liegt. Durch Parametrisierung ist das Hinzufügen eines Grenzfalles so einfach wie das Hinzufügen einer Zeile zu einer Tabelle.

Warum eine separate Datendatei besser ist als fest codierte Werte

Sie könnten jeden Fall direkt im Test fest codieren. Die meisten Leute beginnen so. Das Problem zeigt sich später.

Wenn die Daten im Test liegen, kann ein Nicht-Entwickler keine Fälle beisteuern. Ihr QA-Leiter kennt fünfzehn knifflige Eingaben, die diesen Endpunkt zuvor zum Absturz gebracht haben, aber er kann sie nicht hinzufügen, ohne Code zu bearbeiten und einen Pull Request zu öffnen. Wenn die Daten in einer CSV-Datei liegen, bearbeiten sie eine Tabelle und committen sie. Die Hürde sinkt auf nahezu Null.

Eine separate Datei hält Ihr Testszenario auch lesbar. Ein Test, der eine externe Datei durchläuft, ist kurz: eine Anfrage, eine Handvoll Assertions, fertig. Ein Test mit dreißig Inline-Fällen ist eine Wand der Wiederholung, die niemand anfassen möchte. Und wenn Sie Fälle programmatisch generieren müssen, z.B. tausend Zeilen aus Produktionsprotokollen, ist eine Datei die einzig vernünftige Option. Sie können nicht tausend Fälle in einen Testkörper einfügen.

Das Format, das Sie wählen, hängt von der Struktur Ihrer Daten ab. Flache, tabellarische Fälle passen zu CSV. Verschachtelte oder strukturierte Payloads passen zu JSON. Beide sind erstklassige Eingaben in Apidogs Runner, sodass die Wahl von Ihren Daten und nicht von Tool-Einschränkungen abhängt.

Ihre Datendatei einrichten

Beginnen Sie mit CSV für tabellarische Fälle. Die Kopfzeile benennt Ihre Variablen; jede Zeile darunter ist eine Iteration. Hier ist die Rabattcode-Tabelle als echte Datei, discount-cases.csv:

code,order_total,expected_status,expected_discount
WELCOME10,100,200,10
WELCOME10,5,422,0
EXPIRED,100,410,0
,100,400,0
FAKE123,100,404,0

Jede Spaltenüberschrift wird zu einer Variablen, die Sie im Test referenzieren. Im Anfragekörper schreiben Sie {{code}} und {{order_total}}; in den Assertions vergleichen Sie mit {{expected_status}} und {{expected_discount}}. Der Runner nimmt die Bindung Zeile für Zeile vor.

Wenn Ihre Eingaben verschachtelt sind, greifen Sie zu JSON. Ein Array von Objekten, ein Objekt pro Iteration, ermöglicht es jedem Fall, strukturierte Daten zu transportieren, die sich nur schwer in Spalten flachklopfen ließen. Hier ist user-cases.json für einen Endpunkt zur Benutzererstellung, bei dem die Nutzlast verschachtelte Felder enthält:

[
  {
    "scenario": "gültiges vollständiges Profil",
    "user": {
      "email": "ada@example.com",
      "roles": ["admin", "billing"],
      "profile": { "country": "US", "timezone": "America/New_York" }
    },
    "expected_status": 201
  },
  {
    "scenario": "fehlende E-Mail",
    "user": {
      "email": "",
      "roles": ["viewer"],
      "profile": { "country": "GB", "timezone": "Europe/London" }
    },
    "expected_status": 400
  },
  {
    "scenario": "unbekannte Rolle",
    "user": {
      "email": "grace@example.com",
      "roles": ["wizard"],
      "profile": { "country": "CA", "timezone": "America/Toronto" }
    },
    "expected_status": 422
  }
]

Innerhalb des Tests referenzieren Sie die strukturierten Werte mit derselben {{user}}, {{expected_status}}-Syntax, und Apidog übergibt die Felder jedes Objekts an die Iteration. Die Spalte "scenario" ist eine Bezeichnung für Sie selbst; sie erscheint im Bericht, sodass eine fehlgeschlagene Iteration „unbekannte Rolle“ anstelle von „Iteration 3“ anzeigt.

Ein paar Regeln bewahren Datendateien davor, Ihnen Probleme zu bereiten:

• Pro Datei ein Anliegen. Eine Rabattcode-Datei und eine Benutzererstellungsdatei sind zwei Dateien, nicht eine mit gemischten Spalten.
• Legen Sie das erwartete Ergebnis in die Daten, nicht in den Test. Der ganze Sinn besteht darin, dass Zeile 2 einen 422 erwartet, während Zeile 1 einen 200 erwartet. Wenn die Erwartung fest codiert ist, sind Sie wieder bei einem Test pro Fall.
• Setzen Sie alles mit einem Komma in CSV in Anführungszeichen oder wechseln Sie die Datei zu JSON. Ein Freitextfeld mit Kommas ist die klassische CSV-Falle.
• Speichern Sie diese Dateien in Ihrem Repository neben dem Rest Ihrer Testkonfiguration, damit sie zusammen mit dem Code, den sie testen, versioniert werden.

Das parametrisierte Szenario in Apidog erstellen

Erstellen Sie in der Apidog-App das Testszenario einmal wie jedes andere. Fügen Sie die Anfrage zu Ihrem Endpunkt hinzu. Im Body tauschen Sie die Literalwerte gegen Variablenreferenzen aus: {{code}}, {{order_total}} usw. Dies sind die Spalten aus Ihrer Datendatei.

Fügen Sie dann die Assertions hinzu, die aus derselben Datei lesen. Für das Rabattbeispiel würden Sie bestätigen, dass der Antwortstatus gleich {{expected_status}} ist und dass das Rabattfeld im JSON-Body gleich {{expected_discount}} ist. Da sowohl die Eingabe als auch die erwartete Ausgabe aus der Zeile stammen, validiert dieselbe Assertionslogik jeden Fall korrekt. Wenn Sie Assertions in Apidog noch nicht geschrieben haben, behandelt API-Assertions: ein praktischer Leitfaden die Muster, und wie man Assertions setzt und Variablen aus einer JSON-Antwort extrahiert zeigt die JSONPath-Seite im Detail.

Um die Daten einzubinden, öffnen Sie die Ausführungseinstellungen des Testszenarios und fügen Ihre CSV- oder JSON-Datei als Iterationsdatenquelle an. Apidog liest die Datei, zählt die Zeilen und führt das Szenario einmal pro Zeile aus, wobei die Spalten jeder Zeile an die entsprechenden Variablen gebunden werden. Führen Sie es in der App aus und Sie erhalten eine Aufschlüsselung pro Iteration: welche Zeilen bestanden wurden, welche fehlschlugen und den tatsächlichen gegenüber dem erwarteten Wert für jede fehlgeschlagene Assertion.

Hier fügt sich die Parametrisierung auch mit dem Rest Ihrer Suite zusammen. Ein parametrisiertes Szenario ist immer noch ein Szenario, sodass Sie mehrere davon zu einer Testsuite gruppieren und die gesamte Menge als einen Job ausführen können. Die datengesteuerte Schleife deckt die Breite innerhalb eines einzelnen Endpunkts ab; die Testsuite die Abdeckung über Endpunkte hinweg.

Ausführung über die Kommandozeile

Die App ist der Ort, an dem Sie entwickeln und debuggen. CI ist der Ort, an dem der Test seinen Wert beweist, indem er bei jedem Pull Request ausgeführt wird, ohne dass jemand einen Knopf drücken muss. Diese Übergabe ist der Zweck der Apidog CLI. Sie nimmt das Szenario, das Sie in der App erstellt haben, und führt es im Headless-Modus von einem Terminal aus mit denselben Iterationsdaten aus.

Die CLI wird als npm-Paket ausgeliefert. Installieren Sie es global:

npm install -g apidog-cli

Das Binary ist apidog, daher beginnt jeder Befehl mit apidog run. Eine Basisausführung verweist auf ein Szenario über dessen ID und eine Umgebung über deren ID:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

Um dieses Szenario aus einer Datendatei zu steuern, fügen Sie das Flag iteration-data hinzu. Es akzeptiert einen Pfad zu einer JSON- oder CSV-Datei:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 \
  -d ./discount-cases.csv -r cli,junit --out-dir ./test-reports

Das -d Flag (Langform --iteration-data) ist das Herzstück parametrisierter Ausführungen über die Kommandozeile. Apidog liest die Datei, führt das Szenario einmal pro Zeile aus und meldet jede Iteration. Ersetzen Sie discount-cases.csv durch user-cases.json, und dasselbe Flag verarbeitet das JSON-Array; der Runner erkennt das Format anhand der Datei. Behandeln Sie das Zugriffstoken wie ein Passwort und speichern Sie es als CI-Secret, niemals in einer committeten Datei. Deshalb verweist jedes Beispiel auf $APIDOG_ACCESS_TOKEN anstatt auf einen Literalwert.

Einige Flags passen natürlich zu parametrisierten Ausführungen:

• -d, --iteration-data <path> verweist die Ausführung auf Ihre CSV- oder JSON-Datei. Dies ist das Flag, das eine einmalige Ausführung in eine datengesteuerte umwandelt.
• -n, --iteration-count <n> führt das Szenario eine feste Anzahl von Malen aus. Wenn Sie eine Datendatei bereitstellen, bestimmt die Zeilenanzahl normalerweise die Iterationen, daher verwenden Sie -n hauptsächlich für Wiederholungen ohne Daten, wie z.B. Soak-Tests.
• -r, --reporters <list> wählt Ausgabeformate. Verwenden Sie cli für lesbare Build-Log-Ausgaben und junit, um das XML zu erzeugen, das CI-Dashboards in einen Pass/Fail-Baum pro Iteration parsen.
• --out-dir <path> legt fest, wo Berichte gespeichert werden, damit Sie sie als Build-Artefakte archivieren können.

Wenn Sie die maßgebliche, aktuelle Liste der Flags für Ihre installierte Version wünschen, führen Sie apidog run --help aus. Die CLI druckt jede Option mit ihrer Kurz- und Langform.

Parametrisierte Ausführungen in CI integrieren

Der Grund, in parametrisierte Tests zu investieren, ist, dass sie sich automatisch auszahlen. Hier ist ein GitHub Actions Job, der die CLI installiert und ein CSV-gesteuertes Szenario bei jedem Pull Request ausführt:

name: API tests
on: [pull_request]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Install Apidog CLI
        run: npm install -g apidog-cli
      - name: Run parameterized API tests
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
        run: |
          apidog run --access-token $APIDOG_ACCESS_TOKEN \
            -t 605067 -e 1629989 \
            -d ./tests/discount-cases.csv \
            -r cli,junit --out-dir ./test-reports
      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: api-test-report
          path: ./test-reports

Das Token stammt aus secrets.APIDOG_ACCESS_TOKEN, das einmal in Ihren Repo-Einstellungen festgelegt wird. Der JUnit-Reporter schreibt XML, das die meisten CI-Dashboards in einen pro-Iterations-Ergebnisbaum umwandeln, sodass eine fehlschlagende Zeile als benannter fehlschlagender Test und nicht als eine Wand von Log-Text erscheint. Das if: always() im Upload-Schritt bedeutet, dass Sie den Bericht auch dann behalten, wenn der Lauf fehlschlägt, was genau der Zeitpunkt ist, an dem Sie ihn benötigen. Für eine tiefere Betrachtung der Actions-Seite siehe wie man API-Tests in GitHub Actions automatisiert.

Dasselbe Szenario und dieselbe Datendatei laufen in jedem CI-System. GitLab CI, Jenkins, CircleCI und der Rest reduzieren sich alle auf dieselben drei Schritte: Node und die CLI installieren, das Token als Umgebungsvariable verfügbar machen, apidog run mit -d aufrufen. Es gibt keine plattformspezifische Umschreibung Ihrer Tests.

Vergleich parametrisierter Testansätze

Apidog ist nicht der einzige Weg, datengesteuerte API-Tests auszuführen. Es lohnt sich, die Landschaft zu kennen, damit Sie die richtige Wahl treffen.

Postman und seine Runner unterstützen ebenfalls Datendateien. Mit Postmans Collection Runner oder dem Newman Kommandozeilen-Tool fügen Sie eine CSV- oder JSON-Datei an und referenzieren {{column}}-Variablen in Anfragen, ähnlich dem hier gezeigten Muster. Es ist ein leistungsfähiger und gut dokumentierter Ansatz. Der Nachteil ist, dass Ihre Testlogik in JavaScript Pre-Request- und Testskripten liegt, sodass Sie mit zunehmenden Assertions mehr Code pflegen müssen. Wenn Sie speziell die Kommandozeilen-Runner abwägen, erklärt Postman CLI vs Newman die Unterschiede.

Code-First-Frameworks wie pytest mit @pytest.mark.parametrize, JUnits @ParameterizedTest oder REST Assured geben Ihnen die volle Kontrolle über die Programmiersprache. Sie sind die richtige Wahl, wenn Ihre Testlogik tatsächlich Code benötigt: komplexe Einrichtung, benutzerdefinierte Datengenerierung, enge Kopplung an eine bestehende Testcodebasis. Der Nachteil ist, dass jeder Fall im Code lebt, sodass Nicht-Ingenieure nicht dazu beitragen können und Sie die HTTP-Kommunikation selbst pflegen müssen.

Apidogs Ansatz ist, dass das Szenario visuell und die Daten extern sind, sodass die Logik lesbar bleibt und die Fälle für jeden zugänglich bleiben, der eine Tabelle bearbeiten kann, während dasselbe Szenario immer noch Headless in CI ausgeführt wird. Wenn Sie speziell ein Tool für CSV- und JSON-datengesteuerte Läufe auswählen, geht der Vergleich in welches Tool für datengesteuertes API-Testen mit CSV oder JSON tiefer auf die Kompromisse ein. Keiner dieser Ansätze ist falsch. Passen Sie den Ansatz daran an, wer die Fälle schreibt und wie viel benutzerdefinierte Logik jeder Fall benötigt.

Ein praktischer Workflow, der skaliert

So sieht es aus, sobald es Teil der Routine Ihres Teams ist.

Beginnen Sie eng. Wählen Sie einen Endpunkt, der Ihnen schon einmal Probleme bereitet hat. Schreiben Sie das einzelne Szenario in Apidog mit Variablenreferenzen in der Anfrage und dem erwarteten Ergebnis in den Assertions. Erstellen Sie eine CSV-Datei mit drei Zeilen: einen "Happy Path", einen bekannten Fehlerfall, einen Grenzfall. Führen Sie es in der App aus, bis alle drei Iterationen wie erwartet funktionieren.

Dann erweitern Sie die Daten, nicht den Test. Jedes Mal, wenn ein Fehlerbericht eingeht, fügen Sie die Eingabe, die ihn verursacht hat, als neue Zeile mit der korrekten erwarteten Ausgabe hinzu. Der Fehler wird zu einem permanenten Regressionsfall, und Sie haben nie einen neuen Test geschrieben, sondern eine Zeile zu einer Datei hinzugefügt. Innerhalb weniger Monate sammelt die Datei die tatsächlichen Unzulänglichkeiten an, denen Ihr Endpunkt in der Praxis begegnet.

Automatisieren Sie es schließlich. Fügen Sie den Befehl apidog run -d in CI ein, damit die gesamte Tabelle bei jedem Pull Request ausgeführt wird. Nun schlägt eine Änderung, die den abgelaufenen Codepfad unterbricht, den Build sofort nach dem Push fehl, mit einer benannten Iteration, die direkt auf die defekte Zeile verweist.

Der kumulative Vorteil ist die Wartung. Wenn sich die Antwortstruktur des Endpunkts ändert, korrigieren Sie die Assertion einmal und jeder Fall übernimmt die Korrektur. Wenn Sie fünfzig weitere Fälle benötigen, fügen Sie fünfzig Zeilen hinzu. Die Testlogik bleibt ein einziges, kleines, lesbares Element, egal wie breit Ihre Abdeckung wird.

Häufig gestellte Fragen

Was ist der Unterschied zwischen parametrisiertem Testen und datengesteuertem Testen? Sie beschreiben dieselbe Idee, und die Begriffe werden austauschbar verwendet. Beide bedeuten, einen Test wiederholt mit verschiedenen Eingaben und erwarteten Ausgaben auszuführen, die von außerhalb des Tests geliefert werden. „Parametrisiert“ betont den Parameterbindungsmechanismus; „datengesteuert“ betont die externe Datenquelle. In der Praxis behandeln Sie sie als Synonyme.

Sollte ich CSV oder JSON für meine Datendatei verwenden? Passen Sie das Format an die Struktur Ihrer Daten an. Flache, tabellarische Fälle, bei denen jede Zeile dieselben einfachen Spalten hat, passen zu CSV, und CSV ist für Nicht-Entwickler einfacher in einer Tabelle zu bearbeiten. Verschachtelte oder strukturierte Payloads, wie ein Anfragetext mit Arrays und Unterobjekten, passen zu JSON. Apidog liest beide als Iterationsdaten, also wählen Sie dasjenige, das Ihre Fälle ohne Verrenkungen darstellt.

Werden Hunderte von Iterationen meine Pipeline verlangsamen? Jede Zeile ist ein Durchlauf des Szenarios, sodass die Gesamtzeit mit der Zeilenanzahl multipliziert mit der Latenz pro Anfrage skaliert. Für die meisten API-Tests sind das Sekunden, nicht Minuten. Wenn ein großer Datensatz Ihren Build stark belastet, teilen Sie ihn auf: Führen Sie eine schnelle Smoke-Test-Teilmenge bei jedem Pull Request aus und die vollständige Tabelle in einem nächtlichen oder Pre-Release-Job. Dasselbe Szenario und dieselbe Datei treiben beide an; nur die Datenteilmenge ändert sich.

Wie halte ich Geheimnisse aus meinen Datendateien und der Testkonfiguration heraus? Halten Sie Anmeldeinformationen vollständig aus der Datendatei fern. Tokens und Passwörter gehören in Umgebungsvariablen oder den Geheimnisspeicher Ihres CI-Systems, referenziert als $APIDOG_ACCESS_TOKEN und ähnliche. Die Datendatei sollte Testeingaben und erwartete Ergebnisse enthalten, nicht Authentifizierungsmaterial. Jeder, der das Repository lesen kann, kann die CSV-Datei lesen, also behandeln Sie sie entsprechend.

Kann ich dasselbe parametrisierte Szenario gegen Staging und Produktion ausführen? Ja. Behalten Sie das Szenario und die Datendatei bei und wechseln Sie Umgebungen mit dem -e Flag. Verweisen Sie eine Pull-Request-Prüfung auf Staging und einen Post-Deploy-Smoke-Test auf Produktion unter Verwendung derselben Szenario-ID und derselben Daten, aber einer anderen Umgebungs-ID. Das ist der ganze Grund, warum Umgebung und Daten separate Eingaben sind.

Zusammenfassung

Parametrisiertes API-Testen verwandelt die Abdeckung von einer Copy-Paste-Aufgabe in eine Dateneingabeaufgabe. Sie schreiben den Test einmal, beschreiben jeden Fall als Zeile in einer CSV- oder JSON-Datei und lassen den Runner den Rest erledigen. Die Logik bleibt klein und lesbar, die Fälle bleiben für jeden im Team offen, und CI führt die gesamte Tabelle bei jeder Änderung aus.

Apidog bietet Ihnen den visuellen Szenario-Builder für die Erstellung, externe CSV- und JSON-Dateien für die Daten und den Befehl apidog run -d für die Headless-Ausführung in jedem CI-System. Erstellen Sie ein Szenario, weisen Sie es einer wachsenden Tabelle von Fällen zu, und Ihre Testabdeckung erweitert sich jedes Mal, wenn jemand eine Zeile hinzufügt. Laden Sie Apidog herunter und verwandeln Sie Ihren nächsten fehleranfälligen einmaligen Test in ein skalierbares, parametrisiertes Szenario.