Praktische Anleitung für QA‑Ingenieure, die ein einziges, wartbares k6‑Test‑Asset benötigen, um schnelle Smoke‑Checks, funktionale Verifikation und realistische Performance‑Validierung in CI zu ermöglichen.


1. Warum ein einzelnes Skript drei Gates bedienen kann

Continuous‑Integration‑Pipelines enthalten oft drei unterschiedliche Qualitäts‑Gates:

GateZielTypische CI‑Einschränkungen
SmokeÜberprüfen Sie, ob der Dienst läuft und die kritischste Anfrage eine sinnvolle Antwort zurückgibt.Ausführung in weniger als einer Sekunde, 1‑2 VUs, keine Last.
FunktionalFühren Sie eine geschäftskritische End‑zu‑End‑Reise aus und prüfen Sie funktionale Verträge.Kleine, deterministische Last (z. B. 5 VUs, ein paar Iterationen).
LeistungModellieren Sie realistischen Datenverkehr, erfassen Sie Latenz‑Perzentile und setzen Sie SLA‑Schwellenwerte durch.Hunderte von VUs, Ramp‑up‑Phasen, längere Dauer.

Historisch hielten Teams separate Skripte für jedes Gate, was zu duplizierten Anforderungsdefinitionen, divergenter Datenverarbeitung und Abweichungen in der Geschäftslogik führt.

k6 v2.3.0 führte zwei CLI‑Flags ein, die ein einzelnes Skript für alle drei Gates nutzbar machen:

Da Checks (Assertions) und Thresholds (Pass/Fail‑Kriterien) innerhalb des Skripts definiert sind, kann derselbe Code unter verschiedenen Lastprofilen ausgeführt werden und dennoch den passenden CI‑Exit‑Code erzeugen.

> Offizielle Anmerkung – Checks zeichnen nur Erfolg/Misserfolg auf; sie verursachen niemals einen von Null verschiedenen Exit‑Code. Thresholds sind der Mechanismus, der einen Lauf im CI fehlschlagen lässt. (Grafana k6 v2.3.0 Release Notes)

Der Rest dieses Leitfadens zeigt, wie man ein wiederverwendbares Skript strukturiert, wie man es für jedes Gate aufruft und welche Fallstricke zu beachten sind.


2. Wiederverwendbare Skript‑Anatomie

Unten ist ein minimales, aber vollständiges Beispiel, das das empfohlene Layout demonstriert. Das Skript befindet sich in tests/k6/api-test.js.

import http from "k6/http";
import { check, sleep } from "k6";
import { Trend, Rate } from "k6/metrics";

/* ---------- 1. Global configuration ---------- */
export const options = {
  // Scenarios are defined once; the CLI picks which one to run.
  scenarios: {
    // 1️⃣ Smoke – single iteration, single VU
    smoke: {
      executor: "per-vu-iterations",
      exec: "journey",
      vus: 1,
      iterations: 1,
    },

    // 2️⃣ Functional – small deterministic load
    functional: {
      executor: "per-vu-iterations",
      exec: "journey",
      vus: 5,
      iterations: 3,
    },

    // 3️⃣ Performance – realistic ramp‑up
    performance: {
      executor: "ramping-vus",
      exec: "journey",
      startVUs: 10,
      stages: [
        { duration: "30s", target: 50 },
        { duration: "2m", target: 200 },
        { duration: "30s", target: 0 },
      ],
    },
  },

  // Global thresholds that apply to *all* scenarios unless overridden later.
  thresholds: {
    // Every business check must pass for smoke and functional CI gates.
    checks: ["rate==1"],

    // Basic health – any HTTP error fails the pipeline.
    http_req_failed: ["rate<0.01"],

    // Latency SLA – only enforced for the performance scenario.
    "http_req_duration{scenario:performance}": ["p(95)<800"],
  },

  // Tags help you filter results later (e.g., in Grafana dashboards).
  tags: {
    component: "orders-api",
    team: "payments",
  },
};

/* ---------- 2. Environment‑aware data ---------- */
// Base URL can be overridden per environment (CI, local, staging, prod).
const BASE_URL = __ENV.BASE_URL || "https://api.dev.example.com";

// A tiny data‑fixture that is safe to reuse across VUs.
const testUser = {
  id: __ENV.TEST_USER_ID || "user‑123",
  token: __ENV.TEST_USER_TOKEN || "dummy-token",
};

/* ---------- 3. Custom metrics (optional) ---------- */
const latencyTrend = new Trend("order_latency");
const errorRate = new Rate("order_error");

/* ---------- 4. The reusable journey ---------- */
export function journey() {
  // 1️⃣ Authenticate (example – token already supplied)
  const authHeaders = {
    headers: { Authorization: `Bearer ${testUser.token}` },
  };

  // 2️⃣ Create an order (deterministic payload)
  const payload = JSON.stringify({
    userId: testUser.id,
    items: [{ sku: "SKU‑001", qty: 1 }],
    // This traceable marker avoids collisions; safe cleanup is still required.
    testRunId: `${__VU}-${__ITER}-${Date.now()}`,
  });

  const res = http.post(`${BASE_URL}/orders`, payload, authHeaders);
  const ok = check(res, {
    "status is 201": (r) => r.status === 201,
    "order id returned": (r) => !!r.json("orderId"),
  });

  // Record custom metrics.
  latencyTrend.add(res.timings.duration);
  errorRate.add(!ok);

  // Simulate think‑time – important for realistic performance runs.
  sleep(0.5);
}

/* ---------- 5. Scenario‑specific thresholds (optional) ---------- */
// The `options` object can be mutated at runtime, but keeping them static
// makes the script easier to audit. If you need a tighter SLA for a
// functional gate, you can add a conditional block like:
//
// if (__ENV.GATE === "functional") {
//   options.thresholds["http_req_duration{scenario:functional}"] = ["p(95)<500"];
// }

Wesentliche Erkenntnisse aus dem Skript

AspektWie es die drei Gates unterstützt
Benannte Abläufe (journey)Eine Funktion wird von jedem Szenario über exec referenziert.
Umgebungsabhängige Daten__ENV-Variablen ermöglichen es CI, die korrekte Basis-URL und sichere Test-Anmeldeinformationen einzufügen, ohne sie hart zu codieren.
Deterministische Prüfungencheck-Anweisungen prüfen Geschäftsregeln; sie werden bei jedem Durchlauf aufgezeichnet, brechen jedoch nie den CI-Job ab.
Szenario‑spezifische Lastprofilescenarios-Objekt definiert drei unabhängige Workloads; das CLI-Flag --scenario wählt aus, welcher ausgeführt werden soll.
MarkierungenGlobale Markierungen (component, team) und szenario‑spezifische Markierungen (scenario:performance) ermöglichen eine feinkörnige Berichterstattung.
SchwellenwerteGlobale Gesundheitsgrenzwerte (http_req_failed) gelten für alle Gates; die Latenz‑SLA ist nur auf das Performance‑Szenario beschränkt.

3. Ausführen des Skripts in CI

3.1 Befehlszeilen‑Spickzettel

GateBefehlWas es tut
Smokek6 run --once --scenario smoke tests/k6/api-test.jsFührt das journey einmal mit einem einzelnen VU aus; schnelles Feedback, keine Last.
Funktionalk6 run --scenario functional tests/k6/api-test.jsFührt 5 VUs aus, jeweils 3 Iterationen – genug, um Race Conditions aufzudecken und gleichzeitig deterministisch zu bleiben.
Leistungk6 run --scenario performance tests/k6/api-test.jsFührt das Ramp‑up‑Profil aus, das im performance‑Szenario definiert ist; Schwellenwerte für die p95‑Latenz führen zu einem Nicht‑Null‑Exit‑Code, wenn sie überschritten werden.

Alle drei Befehle können in separaten CI‑Jobs oder -Stages platziert werden. Die gleiche Skriptdatei ist versionskontrolliert, sodass jede Änderung an Anfragetexten, Headern oder Authentifizierung automatisch über alle Gates hinweg übernommen wird.

3.2 Beispiel CI-Matrix (GitHub Actions)

name: API Qualitätsprüfungen
on:
  push:
    branches: [main]

jobs:
  smoke:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install k6
        uses: grafana/setup-k6-action@v1
      - name: Smoke test
        env:
          BASE_URL: ${{ secrets.STAGING_URL }}
          TEST_USER_ID: ${{ secrets.TEST_USER_ID }}
          TEST_USER_TOKEN: ${{ secrets.TEST_USER_TOKEN }}
        run: k6 run --once --scenario smoke tests/k6/api-test.js

  functional:
    needs: smoke
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install k6
        uses: grafana/setup-k6-action@v1
      - name: Functional test
        env:
          BASE_URL: ${{ secrets.STAGING_URL }}
          TEST_USER_ID: ${{ secrets.TEST_USER_ID }}
          TEST_USER_TOKEN: ${{ secrets.TEST_USER_TOKEN }}
        run: k6 run --scenario functional tests/k6/api-test.js

  performance:
    needs: functional
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install k6
        uses: grafana/setup-k6-action@v1
      - name: Performance test
        env:
          BASE_URL: ${{ secrets.PERFORMANCE_ENV_URL }}
          TEST_USER_ID: ${{ secrets.PERF_USER_ID }}
          TEST_USER_TOKEN: ${{ secrets.PERF_USER_TOKEN }}
        run: k6 run --scenario performance tests/k6/api-test.js

Hinweis: Der gleiche Skriptpfad (tests/k6/api-test.js) erscheint in jedem Job. Nur die Umgebungsvariablen und das --scenario-Flag unterscheiden sich.


4. Risiken & Minderungsstrategien

RisikoBeschreibungMinderung
Destruktive TestdatenLasttests können Bestellungen, Benutzer oder andere Entitäten erzeugen, die eine gemeinsam genutzte Umgebung verschmutzen.Verwenden Sie einen dedizierten Nicht‑Produktions‑Load‑Test‑Mandanten, erzeugen Sie nachvollziehbare Lauf‑Identifikatoren und überprüfen Sie die Bereinigung nach dem Lauf.
Versteckter Zustand zwischen SzenarienWeil --once weiterhin die vollständige Szenario‑Funktion ausführt, kann jeder globale veränderbare Zustand (z. B. Modul‑Ebene‑Variablen) aus einem vorherigen Lauf lecken.Bewahren Sie alle veränderbaren Daten innerhalb der journey‑Funktion auf oder setzen Sie globale Variablen explizit am Anfang des Skripts zurück.
Schwellenwert‑DriftIm Laufe der Zeit können Teams die Schwellenwerte lockern, um die CI‑Grün‑Anzeige zu erhalten, wodurch die SLA‑Garantie erodiert wird.Speichern Sie Schwellenwerte im Code‑Review (wie gezeigt) und setzen Sie vor jeder Veröffentlichung eine „Schwellenwert‑Audit“‑Checkliste durch.
Teil‑Szenario‑Schwellenwert‑VerhaltenEin Schwellenwert, der auf ein bestimmtes Szenario ({scenario:performance}) beschränkt ist, wird ignoriert, wenn das Smoke‑Szenario ausgeführt wird, wodurch möglicherweise ein Regression verborgen bleibt.Definiere Baseline-Gesundheitsschwellen (z. B. http_req_failed), die für jedes Szenario gelten; füge szenario‑spezifische SLAs nur dort hinzu, wo sie sinnvoll sind.
Übermäßige Abhängigkeit von AutomatisierungPrüfungen bestätigen die Form der Antwort, ersetzen jedoch nicht das explorative Testen von Randfällen.Kombiniere die CI‑Gates mit einem manuellen „explorativen Sprint“, der dieselben Abläufe mit Ad‑hoc‑Daten und UI‑Inspektion ausführt.

Wenn einer der oben genannten Risiken schwer zu kontrollieren wird, erwäge, das Skript aufzuteilen:

Das Aufteilen erhöht den Wartungsaufwand, isoliert jedoch destruktive Aktionen und macht die CI-Absicht klarer.


5. Prüfliste überprüfen, bevor ein k6‑Skript zusammengeführt wird

  1. Scenario definitions – jedes Gate hat ein eindeutiges Szenario mit passendem Executor und VU‑Anzahl.
  2. Environment variables – keine fest codierten URLs oder Anmeldedaten; alle Geheimnisse werden über __ENV injiziert.
  3. Controlled test data – verwendet einen nachvollziehbaren Lauf‑Identifier, einen dedizierten Nicht‑Produktions‑Mandanten und verifizierte Bereinigung.
  4. Checks vs thresholds – jede geschäftliche Assertion befindet sich in check; jede CI‑Gate‑Pass/Fail‑Regel befindet sich in thresholds.
  5. Tagging – globale Tags sind vorhanden; szenario‑spezifische Tags werden zum Filtern von Dashboards verwendet.
  6. Idempotency – der zu testende API‑Endpunkt kann sicher wiederholt aufgerufen werden, ohne Nebenwirkungen, die spätere Durchläufe beeinflussen.
  7. Documentation – der Skriptkopf listet den Zweck jedes Szenarios und die SLA‑Nummern, die er durchsetzt.

Wenn ein Element fehlschlägt, pausieren Sie den Merge und beheben die Lücke.


6. Menschlich gesteuerte Release‑Entscheidung

Selbst bei automatisierten Gates muss ein Mensch entscheiden, ob ein Build gefördert werden soll:

EntscheidungspunktWas der Tester sucht
Smoke greenDienst erreichbar, Grundvertrag erfüllt.
Funktional grünAlle funktionalen Prüfungen bestehen über mehrere VUs hinweg; es wurden keine flüchtigen Fehler beobachtet.
Performance‑Schwellenwertep95‑Latenz unter SLA, Fehlerrate unter 1 %.
BeobachtbarkeitGrafana‑Dashboards zeigen keine unerwarteten Spitzen; Protokolle enthalten keine versteckten 5xx‑Fehler.
RisikobewertungKeine destruktiven Daten zurückgelassen; Aufräumen erfolgreich; Testumgebung spiegelt die Produktion wider.
Stakeholder‑FreigabeProduct Owner bestätigt, dass die getestete Journey die aktuelle geschäftliche Priorität ist.

Erst nachdem das Team gemeinsam das Obige bestätigt hat, wird die Veröffentlichung fortgesetzt. Automatisierung liefert die Daten; das Urteil liefert den Kontext.


7. Wo Automatisierung hilft

Automatisierung ist kein Allheilmittel, aber sie glänzt bei:

Diese Vorteile ergänzen, statt zu ersetzen, exploratives Testen, Usability‑Reviews und Sicherheitsbewertungen.


8. Fazit

k6 v2.3.0’s --once und --scenario Flags geben QA‑Teams einen pragmatischen Weg zu einem Skript, drei Qualitäts‑Gates. Durch die Trennung von checks (funktionale Assertions) von thresholds (CI‑gate pass/fail) und durch die Definition klarer Szenario‑Profile erhalten Sie:

Der Ansatz erfordert weiterhin diszipliniertes Testdesign, wachsame Risikominimierung und eine abschließende menschliche Release‑Entscheidung. In Kombination mit durchdachtem explorativem Testen — insbesondere für KI‑gesteuerte Features — liefert dieses Muster eine ausgewogene, skalierbare Qualitäts‑Gate‑Strategie für moderne Software‑Lieferpipelines.


Quellen

https://github.com/grafana/k6/releases/tag/v2.3.0

https://grafana.com/docs/k6/latest/using-k6/scenarios/

https://grafana.com/docs/k6/latest/using-k6/thresholds/

https://grafana.com/docs/k6/latest/using-k6/k6-options/reference/