Artillery ist ein Open-Source Node.js-Lasttest-Toolkit, das hochparallelen Traffic an Ihre API von einem einfachen YAML-Skript aus steuert. Sie definieren Lastphasen und Anfrageflüsse, führen artillery run script.yml aus und lesen dann Latenz-Perzentile, Anfrageraten und Fehlerzählungen ab. Dieser Leitfaden führt Sie durch die Installation von Artillery v2, das Schreiben eines echten Testskripts, dessen Ausführung, die Erfassung von Ergebnissen auf die aktuelle v2-Weise und die Integration in CI.
Was Artillery ist und wann Sie es verwenden sollten
Artillery generiert virtuelle Benutzer (VUs), die Ihre Endpunkte aufrufen und misst, wie das System unter anhaltendem Traffic standhält. Ein virtueller Benutzer ist ein simulierter Client, der ein Szenario durchläuft, eine Anfrage nach der anderen, genau wie ein echter Anrufer es tun würde.
Sie greifen zu Artillery, wenn Sie Antworten auf Skalierungsfragen benötigen. Wie verhält sich die p95-Latenz bei 50 Anfragen pro Sekunde? Bei welcher Ankunftsrate treten Fehler auf? Bleibt die API fünf Minuten lang unter anhaltender Last stabil, oder verschlechtert sie sich?
Artillery ist dafür gut geeignet, weil der Test deklarativ ist. Sie beschreiben die Lastform in YAML, anstatt eine Parallelitätsschleife manuell zu codieren. Es läuft überall dort, wo Node.js läuft, sodass dasselbe Skript auf Ihrem Laptop und in CI funktioniert.
Artillery ist eine von mehreren Optionen in diesem Bereich. Wenn Sie noch Tools vergleichen, behandeln die Übersicht der besten Lasttest-Tools und dieser Vergleich von Lasttest-Software die Kompromisse zwischen k6, JMeter, Gatling und anderen.
Artillery (v2) installieren
Der Paketname ist genau artillery, und die aktuelle Hauptversion ist v2. Installieren Sie es global mit npm und überprüfen Sie dann die Version.
npm install -g artillery@latest
artillery version
Sie benötigen eine aktuelle LTS-Version von Node.js. Artillery läuft unter Windows, macOS und Linux.
Wenn Sie nichts global installieren möchten, führen Sie es bei Bedarf mit npx aus.
npx artillery@latest run script.yml
Ein Artillery-Testskript schreiben
Ein Artillery-Test ist eine YAML-Datei mit zwei übergeordneten Abschnitten. Der config-Abschnitt definiert das Ziel und das Lastprofil. Der scenarios-Abschnitt definiert, was jeder virtuelle Benutzer tut.
Hier ist ein vollständiges Skript, das aufwärmt, auf den Höhepunkt ansteigt und dann eine anhaltende Last hält.
config:
target: "https://api.example.com"
phases:
- name: "Warm up"
duration: 60
arrivalRate: 5
- name: "Ramp to peak"
duration: 120
arrivalRate: 5
rampTo: 50
- name: "Sustained load"
duration: 300
arrivalRate: 50
maxVusers: 500
# Inline variables (or use a CSV via config.payload)
variables:
productId:
- "1001"
- "1002"
scenarios:
- name: "Browse and create order"
flow:
- get:
url: "/v1/products/{{ productId }}"
- post:
url: "/v1/orders"
json:
productId: "{{ productId }}"
quantity: 2
Den config-Abschnitt verstehen
config.target ist der Basishost, gegen den jede Anfrage ausgeführt wird. Jeder Schritt in einem Szenario hängt seine url an diese Basis an.
config.phases ist ein Array von Lastphasen, die der Reihe nach ausgeführt werden. Die Schlüssel, die Sie am häufigsten verwenden werden:
duration: wie lange die Phase dauert, in Sekunden oder als menschenlesbarer String wie"5m".arrivalRate: wie viele neue virtuelle Benutzer pro Sekunde starten.rampTo: skaliert die Ankunftsrate über die Phase linear vonarrivalRateauf diesen Wert.arrivalCount: eine feste Anzahl von VUs, die über die Phase verteilt sind, anstatt einer Rate pro Sekunde.maxVusers: eine Obergrenze, wie viele virtuelle Benutzer gleichzeitig ausgeführt werden können.name: eine Bezeichnung, die in der Ausgabe erscheint.
Ein Detail verwirrt oft. Die duration einer Phase steuert, wie lange Artillery virtuelle Benutzer erzeugt, nicht die gesamte Echtzeit des Tests. Wenn ein VU nahe dem Ende einer Phase startet und sein Szenario eine Weile dauert, läuft der Test weiter, bis dieser Benutzer abgeschlossen ist.
Den scenarios-Abschnitt verstehen
scenarios ist ein Array. Jedes Szenario hat einen flow, der die geordnete Liste der Schritte ist, die ein virtueller Benutzer ausführt. Optionale Schlüssel sind name und weight, wobei weight die relative Wahrscheinlichkeit festlegt, dass Artillery dieses Szenario für einen bestimmten VU auswählt.
Flow-Schritte verwenden HTTP-Verb-Schlüssel: get, post, put, delete und patch. Jeder nimmt eine url entgegen, und Anfragetexte stehen unter json. Die doppelte geschweifte Klammer-Syntax, {{ productId }}, zieht eine Variable heran.
Anfragen aus einer CSV-Datei steuern
Werte fest zu codieren ist für einen Smoke-Test in Ordnung. Für eine realistische Last füttern Sie Daten aus einer CSV-Datei mit config.payload. Jeder virtuelle Benutzer wählt eine Zeile, und die Spaltennamen werden zu Variablen.
config:
target: "https://api.example.com"
payload:
path: "./users.csv"
fields:
- "email"
- "password"
phases:
- duration: 120
arrivalRate: 20
scenarios:
- flow:
- post:
url: "/login"
json:
email: "{{ email }}"
password: "{{ password }}"
Den Test ausführen
Der grundlegende Befehl weist Artillery auf Ihr Skript.
artillery run script.yml
# Override target without editing the script:
artillery run --target https://staging.example.com script.yml
# Pass variables as JSON:
artillery run -v '{ "productId": ["1001","1002"] }' script.yml
Einige Flags sind wissenswert. --target (oder -t) überschreibt config.target, sodass Sie dasselbe Skript auf Staging oder Produktion zeigen können. --environment (oder -e) wählt einen benannten Block unter config.environments aus. --config (oder -c) lädt die Konfiguration aus einer separaten Datei. --insecure (oder -k) überspringt die TLS-Verifizierung für selbstsignierte Zertifikate in Testumgebungen.
Die Ergebnisse lesen
Während der Test läuft, gibt Artillery aggregierte Metriken ungefähr alle 10 Sekunden aus. Wenn er beendet ist, erhalten Sie einen Zusammenfassungsbericht. Die wichtigsten Zahlen:
- Anfragerate: Anfragen pro Sekunde, die der Lauf tatsächlich erreicht hat.
- Latenz-Perzentile: p50 (Median), p95 und p99 Antwortzeiten. Das p95 gibt Ihnen die Erfahrung der langsamsten 5 Prozent der Anfragen wieder, wo sich der Engpass normalerweise zuerst zeigt.
- Fehlerzählungen: Fehlgeschlagene Anfragen, Timeouts und Nicht-2xx-Antworten, nach Typ gruppiert.
Beobachten Sie die Tail-Latenzen, nicht nur den Durchschnitt. Ein Durchschnitt kann gesund aussehen, während p99 leise in den Mehrsekundenbereich ansteigt. Wenn Fehler nur während der anhaltenden Phase auftreten, haben Sie wahrscheinlich einen Sättigungspunkt gefunden, der einer Untersuchung wert ist. Eine tiefere Behandlung, welche Metriken verfolgt werden sollten und warum, finden Sie in diesem Leitfaden zum API-Performance-Testing.
Einen Bericht in Artillery v2 generieren
Das Reporting hat sich über die Artillery-Versionen hinweg geändert, daher können veraltete Tutorials hier in die Irre führen. Ältere Anleitungen besagen, dass Sie artillery run --output report.json und dann artillery report report.json ausführen sollen, um eine HTML-Datei zu erstellen. Die erste Hälfte funktioniert immer noch. Die zweite Hälfte jedoch nicht.
Das --output-Flag schreibt immer noch eine maschinenlesbare JSON-Ergebnisdatei.
# Write machine-readable JSON results (still supported):
artillery run --output report.json script.yml
Der Befehl artillery report, der JSON-zu-HTML-Generator, wurde aus der Artillery CLI entfernt. Die offiziellen Dokumente besagen, dass er „nicht mehr unterstützt wird und aus der Artillery CLI entfernt wurde.“ Der HTML-Reporting-Code wurde nicht mehr gepflegt, wurde als veraltet markiert und dann eingestellt, ohne Pläne, ihn wieder einzuführen. Schreiben Sie nicht artillery report report.json; es wird mit dem aktuellen v2 nicht funktionieren.
Stattdessen haben Sie drei aktuelle Optionen.
Erstens, parsen Sie das JSON selbst. Dies ist ideal für CI, wo Sie einen Schwellenwert prüfen möchten. Extrahieren Sie die aggregierte p95-Latenz mit jq:
jq '.aggregate.summaries["http.response_time"].p95' report.json
Zweitens, nutzen Sie Artillery Cloud für ein gehostetes Dashboard. Dies ist der offizielle Ersatz für den alten HTML-Bericht. Übergeben Sie --record mit Ihrem API-Schlüssel.
artillery run --record --key $ARTILLERY_CLOUD_API_KEY script.yml
Drittens, übermitteln Sie Metriken an Ihren eigenen Monitoring-Stack mit dem publish-metrics-Plugin oder OpenTelemetry, sodass Latenz- und Fehlerraten in denselben Dashboards landen, die Sie bereits für die Produktion verwenden.
Artillery in CI ausführen
Da Artillery nur eine Node.js CLI ist, passt es in jede Pipeline. Hier ist ein GitHub Actions Workflow, der Artillery installiert, den Test ausführt und den JSON-Bericht als Build-Artefakt hochlädt.
name: Load test
on: [workflow_dispatch]
jobs:
artillery:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: "lts/*"
- run: npm install -g artillery@latest
- run: artillery run --output report.json script.yml
- uses: actions/upload-artifact@v4
with:
name: artillery-report
path: report.json
Dieses Beispiel wird manuell ausgelöst. Umfangreiche Lasttests werden normalerweise bei Bedarf oder nach einem Zeitplan ausgelöst, und nicht bei jedem Commit, da sie Minuten dauern und erhebliche Bandbreite verbrauchen. Sobald der JSON-Bericht existiert, können Sie einen jq-Schritt hinzufügen, der den Job fehlschlagen lässt, wenn p95 Ihr Budget überschreitet.
Wo Apidog passt: Funktionale Tests und CI-Gating
Artillery beantwortet die Frage „Kann die API so viel Traffic überleben?“ Das ist Last- und Performance-Testing. Eine andere Frage läuft parallel dazu: „Liefert die API nach dieser Codeänderung immer noch korrekte Antworten?“ Das ist funktionales und Regressionstesting, und hier kommt Apidog ins Spiel.
Apidog ist eine All-in-One-API-Plattform für Design, Debugging, Mocking, Dokumentation und automatisiertes Testen. Seine Testszenarien gruppieren Endpunkte in logische Schritte mit Bedingungen wie if, for und foreach, sodass Sie Antwortkörper, Statuscodes und Verträge validieren können. Sie führen diese Szenarien in CI mit der Apidog CLI aus, um Merges nach Codeänderungen zu steuern.
Seien Sie sich der Grenze bewusst. Apidog enthält zwar eine Performance-Testing-Funktion, ist aber auf bis zu 100 virtuelle Benutzer begrenzt. Das reicht aus, um offensichtliche Regressionen zu erkennen, ist aber kein Ersatz für Artillery bei hoher Parallelität. Für verteilte, Code-modellierte Lasten in massivem Umfang ist Artillery das richtige Tool. Diese ehrliche Einschätzung findet sich auch in unserem Artikel über API-Lasttests ohne Python, und die Mechanik der 100-VU-Funktion von Apidog wird in API-Performance-Testing in Apidog behandelt.
Nutzen Sie also beides. Führen Sie Lasttests mit Artillery für die Skalierung durch. Führen Sie funktionale und Regressionstests in CI mit der Apidog CLI durch, um fehlerhaftes Verhalten zu erkennen, bevor es ausgeliefert wird.
Die Apidog CLI wird über npm installiert, und apidog run ist ausschließlich flag-basiert.
# Apidog CLI: functional/regression run in CI (flag-only, no positional file)
npm install -g apidog-cli
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t <TEST_SCENARIO_ID> \
-e <ENVIRONMENT_ID> \
-r cli,junit \
--out-dir ./apidog-reports
Das -t-Flag ist die Test-Szenario-ID, -e ist die erforderliche Umgebungs-ID, und -r cli,junit gibt sowohl Konsolenausgabe als auch einen JUnit-XML-Bericht aus, den CI-Systeme lesen können. Eine Schritt-für-Schritt-Anleitung finden Sie im Apidog CLI Tutorial, und für Pipeline-Designmuster sehen Sie sich diese CI/CD Best Practices für API-Tests an.
Möchten Sie funktionale und Vertrags-Tests, die Ihr CI zusammen mit Ihren Artillery-Lastläufen steuern? Laden Sie Apidog kostenlos herunter und erstellen Sie Ihr erstes Testszenario.
Häufig gestellte Fragen
Was ist Artillery-Lasttest?
Artillery-Lasttest ist die Praxis, das Open-Source-Toolkit Artillery zu verwenden, um viele gleichzeitige virtuelle Benutzer zu simulieren, die Ihre API aufrufen. Sie beschreiben die Lastform und den Anfragefluss in einem YAML-Skript, führen es aus und messen Latenz-Perzentile, Anfrageraten und Fehler, um zu sehen, wie sich Ihr System unter Stress verhält.
Ist Artillery kostenlos und Open Source?
Ja. Die Artillery CLI ist kostenlos und Open Source und wird über npm als artillery-Paket vertrieben. Es gibt auch ein kostenpflichtiges gehostetes Angebot, Artillery Cloud, das ein Dashboard für die Ergebnisse bietet, aber Sie können vollständige Lasttests lokal und in CI auch ohne es durchführen.
Wie führen Sie einen Artillery-Lasttest aus?
Installieren Sie es mit npm install -g artillery@latest, schreiben Sie ein YAML-Skript mit einem config-Block (Ziel und Phasen) und einem scenarios-Block (der Anfragefluss), und führen Sie dann artillery run script.yml aus. Artillery gibt alle 10 Sekunden Live-Metriken und am Ende eine Zusammenfassung aus.
Wie generieren Sie einen Artillery-Bericht?
Führen Sie artillery run --output report.json script.yml aus, um eine JSON-Ergebnisdatei zu schreiben. Der alte Befehl artillery report, der HTML erzeugte, wurde aus der CLI entfernt. Parsen Sie stattdessen das JSON mit einem Tool wie jq, verwenden Sie Artillery Cloud über --record --key oder übermitteln Sie Metriken mit dem publish-metrics- oder OpenTelemetry-Plugin.
Artillery vs. k6 oder JMeter: Was sollten Sie verwenden?
Alle drei bewältigen hochskalierte Lasten. Artillery verwendet deklaratives YAML und Node.js, was Teams im JavaScript-Ökosystem entgegenkommt. k6 skriptet in JavaScript mit einem Code-First-Modell. JMeter ist GUI-gesteuert und Java-basiert mit einer langen Plugin-Historie. Der Gatling vs. JMeter Vergleich behandelt die Kompromisse ausführlicher. Wählen Sie das Tool, dessen Skripting-Modell zu Ihrem Team passt, und kombinieren Sie es dann mit funktionalen CI-Tests für eine vollständige Abdeckung.