DEV Community

Cover image for k6 Lasttests: Ein praktischer Leitfaden für APIs
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

k6 Lasttests: Ein praktischer Leitfaden für APIs

Wenn Ihre API für einen Benutzer funktioniert, aber unter Last zusammenbricht, brauchen Sie reproduzierbare Lasttests. k6 ist dafür ein schlankes Tool: Sie schreiben Tests in JavaScript, führen sie lokal oder in CI aus und bewerten Latenz, Fehlerraten und Durchsatz. In diesem Leitfaden richten Sie k6 ein, schreiben ein erstes Skript, definieren Lastprofile und kombinieren k6 sinnvoll mit funktionalen API-Tests wie Ihrer normalen API-Leistungstestroutine. Für Details zu Optionen und Metriken lohnt sich zusätzlich die offizielle k6-Dokumentation.

Teste Apidog noch heute

Was ist k6?

k6 ist ein Open-Source-Lasttest-Tool, das von Grafana gewartet wird. Sie schreiben den Test als JavaScript-Datei, k6 führt ihn mit einer schnellen Go-Engine aus und erzeugt simulierten Traffic gegen Ihre Endpunkte.

k6 Übersicht

Der wichtige Punkt: k6 ist eine Last-Engine. Es ersetzt keinen API-Client, kein Dokumentationstool und kein funktionales Test-Framework. Es beantwortet vor allem diese Frage:

Wie verhält sich meine API unter anhaltender oder steigender Last?

Typische k6-Metriken sind:

  • Latenz-Perzentile wie p90, p95 und p99
  • Fehlerraten
  • Requests pro Sekunde
  • Anzahl virtueller Benutzer
  • bestandene oder fehlgeschlagene Checks
  • Thresholds als Pass/Fail-Regeln

Wichtige Begriffe:

  • Virtueller Benutzer (VU): ein simulierter Benutzer, der Ihr Skript wiederholt ausführt.
  • Iteration: ein vollständiger Durchlauf der Testfunktion.
  • Stage: ein Schritt in einem Lastprofil, z. B. Hochfahren von 10 auf 100 VUs.
  • Threshold: eine Pass/Fail-Regel für eine Metrik, z. B. p(95)<500.
  • Check: eine nicht-fatale Prüfung einer Antwort, z. B. Statuscode ist 200.

k6 installieren

k6 wird als einzelne Binärdatei ausgeliefert.

macOS mit Homebrew:

brew install k6
Enter fullscreen mode Exit fullscreen mode

Windows mit Chocolatey:

choco install k6
Enter fullscreen mode Exit fullscreen mode

Debian oder Ubuntu:

sudo gpg -k
sudo gpg --no-default-keyring --keyring /usr/share/keyrings/k6-archive-keyring.gpg \
  --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys C5AD17C747E3415A3642D57D77C6C491D6AC1D69

echo "deb [signed-by=/usr/share/keyrings/k6-archive-keyring.gpg] https://dl.k6.io/deb stable main" \
  | sudo tee /etc/apt/sources.list.d/k6.list

sudo apt-get update
sudo apt-get install k6
Enter fullscreen mode Exit fullscreen mode

Installation prüfen:

k6 version
Enter fullscreen mode Exit fullscreen mode

Wenn Sie k6 nicht lokal installieren möchten, können Sie auch das offizielle Docker-Image verwenden. Prüfen Sie dafür die aktuelle Installationsseite der k6-Dokumentation, da sich Paketdetails ändern können.

Erstes k6-Skript schreiben

Ein k6-Test ist ein JavaScript-Modul mit einer default-Funktion. k6 ruft diese Funktion pro Iteration und virtuellem Benutzer auf.

Erstellen Sie eine Datei script.js:

import http from 'k6/http';
import { check, sleep } from 'k6';

export default function () {
  const res = http.get('https://test-api.example.com/users');

  check(res, {
    'status is 200': (r) => r.status === 200,
    'body is not empty': (r) => r.body.length > 0,
  });

  sleep(1);
}
Enter fullscreen mode Exit fullscreen mode

Test starten:

k6 run script.js
Enter fullscreen mode Exit fullscreen mode

Standardmäßig führt k6 einen virtuellen Benutzer für eine Iteration aus.

Das sleep(1) simuliert eine kurze Denkzeit zwischen Aktionen. Ohne sleep() sendet jeder VU Anfragen so schnell wie möglich. Das ist für reine Durchsatztests nützlich, aber oft weniger realistisch für Benutzerverhalten.

Die check()-Aufrufe sind weiche Assertions. Wenn ein Check fehlschlägt, läuft der Test weiter. Dadurch sehen Sie unter Last nicht nur, dass etwas fehlschlägt, sondern auch wie stark.

VUs, Dauer und Lastprofile konfigurieren

Für echte Lasttests definieren Sie ein options-Objekt.

Ein einfacher Test mit fester Last:

export const options = {
  vus: 50,
  duration: '30s',
};
Enter fullscreen mode Exit fullscreen mode

Das führt 50 virtuelle Benutzer für 30 Sekunden aus.

Praktischer ist meist ein stufenweises Profil:

export const options = {
  stages: [
    { duration: '1m', target: 100 }, // Hochfahren auf 100 VUs
    { duration: '3m', target: 100 }, // Last halten
    { duration: '1m', target: 0 },   // Herunterfahren
  ],
};
Enter fullscreen mode Exit fullscreen mode

Damit simulieren Sie typischen Traffic-Verlauf:

  1. Last steigt an.
  2. Last bleibt stabil.
  3. Last fällt ab.

Thresholds als Performance-Budget nutzen

Thresholds machen k6 besonders nützlich für CI/CD. Sie definieren Grenzwerte, bei deren Überschreitung der Test fehlschlägt.

Beispiel:

export const options = {
  stages: [
    { duration: '1m', target: 100 },
    { duration: '3m', target: 100 },
    { duration: '1m', target: 0 },
  ],
  thresholds: {
    http_req_duration: ['p(95)<500'], // 95% der Requests unter 500 ms
    http_req_failed: ['rate<0.01'],   // weniger als 1% Fehler
  },
};
Enter fullscreen mode Exit fullscreen mode

Wenn ein Threshold fehlschlägt, beendet k6 den Prozess mit einem Exit-Code ungleich 0. Dadurch kann Ihre Pipeline den Build bei Performance-Regressionen stoppen.

Typische Lastprofile:

Profil Ziel Was es zeigt
Smoke-Test Kleine Last Prüft, ob das Skript korrekt läuft
Load-Test Erwarteter Normalbetrieb Zeigt, ob die API Alltagslast trägt
Stress-Test Last über dem erwarteten Peak Zeigt, ab wann das System versagt
Spike-Test Plötzlicher Lastanstieg Zeigt Verhalten bei Traffic-Spitzen
Soak-Test Moderate Last über Stunden Findet Speicherlecks und langsame Degradation

Starten Sie pragmatisch:

  1. Smoke-Test schreiben.
  2. Load-Test mit realistischem Traffic ausführen.
  3. Thresholds für p95-Latenz und Fehlerrate setzen.
  4. Erst danach Stress-, Spike- oder Soak-Tests ergänzen.

Die Grundlagen hinter diesen Profilen gelten unabhängig vom Tool. Einen breiteren Überblick finden Sie in den Grundlagen der Performance-Tests.

Beispiel: GET- und POST-Requests testen

Viele APIs brauchen Authentifizierung, Header und Payloads. Ein realistischeres k6-Skript kann so aussehen:

import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
  vus: 20,
  duration: '1m',
  thresholds: {
    http_req_duration: ['p(95)<500'],
    http_req_failed: ['rate<0.01'],
  },
};

export default function () {
  const headers = {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${__ENV.API_TOKEN}`,
  };

  const payload = JSON.stringify({
    name: `Test User ${__VU}-${__ITER}`,
    email: `user-${__VU}-${__ITER}@example.com`,
  });

  const createRes = http.post('https://test-api.example.com/users', payload, {
    headers,
  });

  check(createRes, {
    'create status is 201': (r) => r.status === 201,
  });

  const listRes = http.get('https://test-api.example.com/users', {
    headers,
  });

  check(listRes, {
    'list status is 200': (r) => r.status === 200,
    'list body is not empty': (r) => r.body.length > 0,
  });

  sleep(1);
}
Enter fullscreen mode Exit fullscreen mode

Ausführen mit Umgebungsvariable:

API_TOKEN=your-token k6 run script.js
Enter fullscreen mode Exit fullscreen mode

So vermeiden Sie harte Tokens im Skript und können denselben Test in lokalen Umgebungen und CI verwenden.

k6-Ergebnisse lesen

Nach einem Lauf gibt k6 eine Zusammenfassung im Terminal aus. Achten Sie besonders auf diese Metriken:

  • http_req_duration: Gesamtdauer eines Requests inklusive Durchschnitt, Median, p90 und p95.
  • http_req_failed: Anteil fehlgeschlagener Requests.
  • http_reqs: Gesamtzahl der Requests und Requests pro Sekunde.
  • iterations: Anzahl vollständiger Skriptdurchläufe.
  • vus / vus_max: aktive und maximale virtuelle Benutzer.
  • checks: Erfolgsrate Ihrer check()-Prüfungen.

Lesen Sie vor allem Perzentile, nicht nur Durchschnittswerte.

Ein Durchschnitt von 200 ms kann gut aussehen, während p99 bei 4 Sekunden liegt. Das bedeutet: Ein relevanter Teil der Benutzer erlebt sehr langsame Antworten. Genau diese langen Ausreißer sind für reale Nutzererfahrung entscheidend.

Für schnelle Tests reicht die Terminalausgabe. Für wiederholte oder längere Läufe können Sie Ergebnisse als JSON oder CSV exportieren oder mit Grafana und Prometheus visualisieren.

k6 in CI/CD ausführen

Ein einfacher CI-Schritt kann so aussehen:

k6 run script.js
Enter fullscreen mode Exit fullscreen mode

Sinnvoller ist ein separates Skript für CI, z. B. load-test.js, das gegen Staging läuft und klare Thresholds enthält:

export const options = {
  stages: [
    { duration: '30s', target: 20 },
    { duration: '2m', target: 20 },
    { duration: '30s', target: 0 },
  ],
  thresholds: {
    http_req_duration: ['p(95)<500'],
    http_req_failed: ['rate<0.01'],
  },
};
Enter fullscreen mode Exit fullscreen mode

Beispiel für eine Pipeline-Logik:

k6 run load-test.js
Enter fullscreen mode Exit fullscreen mode

Wenn p95 über 500 ms steigt oder mehr als 1% der Requests fehlschlagen, schlägt der CI-Job fehl.

Praktische Empfehlung:

  • Führen Sie kleine Smoke-Lasttests häufiger aus.
  • Führen Sie größere Load- oder Stress-Tests geplant oder vor Releases aus.
  • Testen Sie gegen Staging, nicht gegen lokale Entwicklungsumgebungen.
  • Verwenden Sie realistische Testdaten und realistische Wartezeiten.
  • Setzen Sie Thresholds nicht willkürlich, sondern anhand bekannter SLOs oder Baseline-Messungen.

Wo k6 passt und wo Apidog passt

k6 beantwortet Performance-Fragen:

Bleibt meine API unter Traffic schnell und stabil?

Es prüft aber nicht umfassend, ob Ihre API fachlich korrekte Daten zurückgibt, dem Vertrag entspricht oder Authentifizierung über alle Endpunkte korrekt funktioniert. Dafür brauchen Sie funktionale Tests und Vertragstests.

Anliegen Am besten behandelt durch Was es beantwortet
Anhaltende hohe Last und Perzentile im großen Maßstab k6 Bleibt die API unter Traffic schnell?
Funktionale Korrektheit, Vertrag, Authentifizierung Apidog Gibt die API das Richtige zurück?
Regression bei jedem Commit Apidog mit apidog run Hat eine Änderung einen Endpunkt beschädigt?
Performance-Budgets in CI k6-Thresholds Überschreiten Latenz oder Fehlerquote definierte Grenzen?

Apidog kümmert sich um die API-Korrektheit. Sie entwerfen oder importieren Ihre API, erstellen Testszenarien mit visuellen Assertions und führen diese in CI mit apidog run aus.

Der Apidog CLI-Leitfaden zeigt, wie Sie funktionale Tests in eine Pipeline integrieren. Apidog enthält außerdem leichtere Performance-Testfunktionen für schnelle Überprüfungen, wie im Walkthrough API Performance Testing in Apidog beschrieben. Es ist aber kein Lastgenerator der k6-Klasse und soll k6 nicht ersetzen.

Ein sinnvoller Workflow:

  1. Bei jedem Commit: funktionale Tests und Vertragstests mit Apidog ausführen.
  2. Vor Releases oder nach Zeitplan: k6-Lasttest gegen Staging ausführen.
  3. CI bricht ab, wenn funktionale Tests oder Performance-Thresholds fehlschlagen.

So trennen Sie Korrektheit und Lastverhalten sauber, prüfen aber beides automatisiert.

Wenn Sie Lasttest-Tools vergleichen, steht k6 neben JMeter, Gatling und Locust. Die Übersicht über Lasttest-Tools und der Locust-Alternativvergleich helfen bei der Einordnung.

Häufig gestellte Fragen

Ist k6 kostenlos?

Ja. k6 ist Open Source unter der AGPL-Lizenz. Sie können die Binärdatei lokal kostenlos ausführen. Die Grenze ist praktisch Ihre eigene Hardware. Grafana bietet zusätzlich k6 Cloud als kostenpflichtigen Dienst für verteilte Tests und gespeicherte Ergebnisse an, aber das Kern-Tool funktioniert ohne Cloud-Dienst. Weitere Optionen finden Sie in der Übersicht über Lasttest-Tools.

Muss ich JavaScript kennen, um k6 zu verwenden?

Sie brauchen grundlegendes JavaScript. Die meisten k6-Skripte bestehen aus:

  • http.get() oder http.post()
  • check()-Prüfungen
  • einem options-Objekt
  • optionalen Wartezeiten mit sleep()

Es gibt keinen Build-Schritt und kein zusätzliches Framework.

Was ist der Unterschied zwischen k6 und Apidog für Performance-Tests?

k6 ist ein dedizierter Lastgenerator für anhaltenden Traffic, Perzentile und Thresholds. Apidog ist eine API-Plattform für Design, Dokumentation, funktionale Tests und Vertragstests mit leichteren Performance-Checks. Verwenden Sie k6 für echte Lasttests und Performance-Budgets. Verwenden Sie Apidog für Korrektheit, Vertragsvalidierung und Regressionstests bei jedem Commit.

Kann ich k6 in CI/CD ausführen?

Ja. Führen Sie k6 run script.js als Pipeline-Schritt aus. Wenn ein Threshold fehlschlägt, liefert k6 einen Exit-Code ungleich 0, wodurch der Build fehlschlagen kann. Typische Thresholds sind p95-Latenz und Fehlerrate.

Sollte ich Lasttests gegen Production ausführen?

Nur mit klarer Planung, Limits und Monitoring. Für regelmäßige CI-Tests ist Staging meist sicherer. Production-Tests können sinnvoll sein, wenn Sie reale Infrastruktur validieren wollen, müssen aber kontrolliert, angekündigt und begrenzt sein.

Fazit

k6 macht API-Lasttests einfach reproduzierbar: Binärdatei installieren, JavaScript-Skript schreiben, VUs und Stages definieren, Thresholds setzen und Perzentile auswerten. Damit können Sie Performance-Budgets wie Code behandeln und Regressionen in CI erkennen.

Trennen Sie Lasttests von funktionalen Tests. k6 misst Verhalten unter Traffic. Apidog prüft API-Korrektheit, Verträge und Regressionen. Zusammen ergeben beide einen praktischen Workflow: korrekte API bei jedem Commit, belastbare API vor dem Release.

Top comments (0)