Artillery est un outil de test de charge open-source basé sur Node.js qui génère un trafic à haute concurrence vers votre API à partir d'un simple script YAML. Vous définissez des phases de charge et des flux de requêtes, exécutez `artillery run script.yml`, et obtenez des pourcentages de latence, des taux de requêtes et des nombres d'erreurs. Ce guide vous expliquera comment installer Artillery v2, écrire un script de test réel, l'exécuter, capturer les résultats de la manière actuelle de la v2 et l'intégrer dans votre CI.
Ce qu'est Artillery et quand l'utiliser
Artillery génère des utilisateurs virtuels (UVs) qui sollicitent vos points de terminaison et mesure la capacité du système à supporter un trafic soutenu. Un utilisateur virtuel est un client simulé qui exécute un scénario, une requête après l'autre, tout comme un véritable appelant le ferait.
Vous utilisez Artillery lorsque vous avez besoin de réponses à des questions d'échelle. Comment la latence p95 se comporte-t-elle à 50 requêtes par seconde ? À quel taux d'arrivée les erreurs commencent-elles à apparaître ? L'API reste-t-elle stable pendant cinq minutes de charge soutenue, ou se dégrade-t-elle ?
Artillery est performant à cet égard car le test est déclaratif. Vous décrivez la forme de la charge en YAML au lieu de coder manuellement une boucle de concurrence. Il fonctionne partout où Node.js s'exécute, de sorte que le même script fonctionne sur votre ordinateur portable et dans votre CI.
Artillery est l'une des nombreuses options dans ce domaine. Si vous êtes encore en train de comparer les outils, le tour d'horizon des meilleurs outils de test de charge et cette comparaison de logiciels de test de charge couvrent les compromis entre k6, JMeter, Gatling et d'autres.
Installer Artillery (v2)
Le nom du package est exactement `artillery`, et la version majeure actuelle est v2. Installez-le globalement avec npm, puis vérifiez la version.
npm install -g artillery@latest
artillery version
Vous avez besoin d'une version LTS récente de Node.js. Artillery fonctionne sur Windows, macOS et Linux.
Si vous préférez ne rien installer globalement, exécutez-le à la demande avec `npx`.
npx artillery@latest run script.yml
Écrire un script de test Artillery
Un test Artillery est un fichier YAML avec deux sections de niveau supérieur. La section `config` définit la cible et le profil de charge. La section `scenarios` définit ce que fait chaque utilisateur virtuel.
Voici un script complet qui effectue un échauffement, atteint un pic, puis maintient une charge soutenue.
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
Comprendre la section config
`config.target` est l'hôte de base sur lequel toutes les requêtes s'exécutent. Chaque étape d'un scénario ajoute son `url` à cette base.
`config.phases` est un tableau de phases de charge qui s'exécutent dans l'ordre. Les clés que vous utiliserez le plus :
- `duration` : durée de la phase, en secondes ou sous forme de chaîne de caractères lisible par l'homme comme `"5m"`.
- `arrivalRate` : nombre de nouveaux utilisateurs virtuels qui démarrent chaque seconde.
- `rampTo` : augmente linéairement le taux d'arrivée de `arrivalRate` jusqu'à cette valeur sur toute la phase.
- `arrivalCount` : un nombre fixe d'UVs répartis sur la phase, au lieu d'un taux par seconde.
- `maxVusers` : une limite sur le nombre d'utilisateurs virtuels pouvant s'exécuter simultanément.
- `name` : une étiquette qui apparaît dans la sortie.
Un détail déroute souvent les utilisateurs. La `duration` d'une phase contrôle la durée pendant laquelle Artillery continue de générer des utilisateurs virtuels, et non la durée totale du test en temps réel. Si un UV démarre vers la fin d'une phase et que son scénario prend du temps, l'exécution se poursuit jusqu'à ce que cet utilisateur ait terminé.
Comprendre la section scenarios
`scenarios` est un tableau. Chaque scénario a un `flow`, qui est la liste ordonnée des étapes qu'un utilisateur virtuel exécute. Les clés facultatives incluent `name` et `weight`, où `weight` définit la probabilité relative qu'Artillery choisisse ce scénario pour un UV donné.
Les étapes de flux utilisent des clés de verbes HTTP : `get`, `post`, `put`, `delete` et `patch`. Chacune prend une `url`, et les corps de requête se trouvent sous `json`. La syntaxe à double accolade, `{{ productId }}`, extrait une variable.
Exécuter des requêtes à partir d'un fichier CSV
Le codage en dur des valeurs convient pour un test de fumée. Pour une charge réaliste, alimentez les données à partir d'un CSV avec `config.payload`. Chaque utilisateur virtuel choisit une ligne, et les noms de colonnes deviennent des variables.
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 }}"
Exécuter le test
La commande de base pointe Artillery vers votre script.
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
Quelques drapeaux méritent d'être connus. `--target` (ou `-t`) remplace `config.target` afin que vous puissiez pointer le même script vers la pré-production ou la production. `--environment` (ou `-e`) sélectionne un bloc nommé sous `config.environments`. `--config` (ou `-c`) charge la configuration à partir d'un fichier séparé. `--insecure` (ou `-k`) ignore la vérification TLS pour les certificats auto-signés dans les environnements de test.
Lire les résultats
Pendant l'exécution du test, Artillery affiche des métriques agrégées environ toutes les 10 secondes. Une fois terminé, vous obtenez un rapport récapitulatif. Les chiffres les plus importants :
- Taux de requêtes : requêtes par seconde réellement atteintes par l'exécution.
- Percentiles de latence : temps de réponse p50 (médiane), p95 et p99. Le p95 vous indique l'expérience des 5 % de requêtes les plus lentes, ce qui est généralement là que les problèmes apparaissent en premier.
- Comptes d'erreurs : requêtes échouées, délais d'attente et réponses non-2xx, regroupés par type.
Surveillez les latences de queue, pas seulement la moyenne. Une moyenne peut sembler saine tandis que la p99 grimpe tranquillement vers des délais de plusieurs secondes. Si des erreurs n'apparaissent que pendant la phase soutenue, vous avez probablement trouvé un point de saturation qui mérite d'être investigué. Pour un traitement plus approfondi des métriques à suivre et pourquoi, consultez ce guide de test de performance API.
Générer un rapport dans Artillery v2
La génération de rapports a changé entre les versions d'Artillery, c'est là que les tutoriels obsolètes peuvent vous induire en erreur. Les anciens guides vous indiquent d'exécuter `artillery run --output report.json`, puis `artillery report report.json` pour produire un fichier HTML. La première moitié fonctionne toujours. La seconde moitié ne fonctionne plus.
L'option `--output` écrit toujours un fichier de résultats JSON lisible par machine.
# Write machine-readable JSON results (still supported):
artillery run --output report.json script.yml
La commande `artillery report`, le générateur JSON vers HTML, a été supprimée de l'interface CLI d'Artillery. La documentation officielle indique qu'elle "n'est plus prise en charge et a été supprimée de l'interface CLI d'Artillery". Le code de génération de rapports HTML n'a pas été maintenu, a été déprécié, puis abandonné, sans aucun plan de le ramener. N'écrivez pas `artillery report report.json` ; cela ne fonctionnera pas sur la v2 actuelle.
Vous avez plutôt trois options actuelles.
Premièrement, analysez le JSON vous-même. C'est idéal pour la CI, où vous voulez affirmer par rapport à un seuil. Extrayez la latence agrégée p95 avec `jq` :
jq '.aggregate.summaries["http.response_time"].p95' report.json
Deuxièmement, utilisez Artillery Cloud pour un tableau de bord hébergé. C'est le remplacement officiel de l'ancien rapport HTML. Passez `--record` avec votre clé API.
artillery run --record --key $ARTILLERY_CLOUD_API_KEY script.yml
Troisièmement, poussez les métriques vers votre propre pile de surveillance avec le plugin `publish-metrics` ou OpenTelemetry, afin que la latence et les taux d'erreur atterrissent dans les mêmes tableaux de bord que vous utilisez déjà pour la production.
Exécuter Artillery en CI
Parce qu'Artillery est simplement un CLI Node.js, il s'intègre dans n'importe quel pipeline. Voici un workflow GitHub Actions qui installe Artillery, exécute le test et télécharge le rapport JSON en tant qu'artefact de build.
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
Cet exemple s'exécute sur un déclenchement manuel. Les tests de charge lourde sont généralement déclenchés à la demande ou selon un calendrier plutôt qu'à chaque commit, car ils prennent des minutes et consomment de la bande passante réelle. Une fois le rapport JSON existant, vous pouvez ajouter une étape `jq` qui échoue le job si le p95 dépasse votre budget.
Où Apidog s'insère : tests fonctionnels et gestion de l'intégration continue (CI)
Artillery répond à la question « l'API peut-elle survivre à ce niveau de trafic ? » C'est du test de charge et de performance. Une question différente se pose en parallèle : « l'API renvoie-t-elle toujours des réponses correctes après ce changement de code ? » C'est du test fonctionnel et de régression, et c'est là que Apidog intervient.
Apidog est une plateforme API tout-en-un pour la conception, le débogage, le mocking, la documentation et les tests automatisés. Ses scénarios de test regroupent les points de terminaison en étapes logiques avec des conditions comme if, for et foreach, afin que vous puissiez valider les corps de réponse, les codes d'état et les contrats. Vous exécutez ces scénarios en CI avec l'interface CLI Apidog pour contrôler les fusions après les changements de code.
Soyons clairs sur la limite. Apidog inclut une fonctionnalité de test de performance, mais elle est limitée à 100 utilisateurs virtuels maximum. C'est suffisant pour repérer les régressions évidentes, mais ce n'est pas un substitut à Artillery pour une concurrence élevée. Pour une charge distribuée et modélisée par code à grande échelle, Artillery est l'outil approprié. Ce même cadre honnête apparaît dans notre article sur les tests de charge d'API sans Python, et la mécanique de la fonctionnalité 100-UV d'Apidog est couverte dans les tests de performance API dans Apidog.
Alors, utilisez les deux. Testez la charge avec Artillery pour l'échelle. Effectuez des vérifications fonctionnelles et de régression en CI avec l'interface CLI Apidog pour détecter les comportements défectueux avant la mise en production.
L'interface CLI Apidog s'installe depuis npm, et `apidog run` n'accepte que des drapeaux.
# 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
Le drapeau `-t` est l'ID du scénario de test, `-e` est l'ID d'environnement requis, et `-r cli,junit` émet à la fois la sortie console et un rapport XML JUnit que les systèmes CI peuvent lire. Pour un guide pas à pas, consultez le tutoriel CLI Apidog, et pour des modèles de conception de pipeline, consultez ces bonnes pratiques CI/CD pour les tests d'API.
Vous souhaitez que des tests fonctionnels et contractuels contrôlent votre CI en parallèle de vos exécutions de charge Artillery ? Téléchargez Apidog gratuitement et construisez votre premier scénario de test.
Questions fréquemment posées
Qu'est-ce que le test de charge Artillery ?
Le test de charge Artillery est la pratique qui consiste à utiliser la boîte à outils open-source Artillery pour simuler de nombreux utilisateurs virtuels concurrents sollicitant votre API. Vous décrivez la forme de la charge et le flux de requêtes dans un script YAML, l'exécutez, et mesurez les percentiles de latence, les taux de requêtes et les erreurs pour voir comment votre système se comporte sous stress.
Artillery est-il gratuit et open source ?
Oui. L'interface CLI principale d'Artillery est gratuite et open source, distribuée sur npm en tant que package `artillery`. Il existe également une offre hébergée payante, Artillery Cloud, qui fournit un tableau de bord pour les résultats, mais vous pouvez exécuter des tests de charge complets localement et en CI sans elle.
Comment exécuter un test de charge Artillery ?
Installez-le avec `npm install -g artillery@latest`, écrivez un script YAML avec un bloc `config` (cible et phases) et un bloc `scenarios` (le flux de requêtes), puis exécutez `artillery run script.yml`. Artillery affiche les métriques en direct toutes les 10 secondes et un résumé à la fin.
Comment générer un rapport Artillery ?
Exécutez `artillery run --output report.json script.yml` pour écrire un fichier de résultats JSON. L'ancienne commande `artillery report` qui produisait du HTML a été supprimée de l'interface CLI. Au lieu de cela, analysez le JSON avec un outil comme `jq`, utilisez Artillery Cloud via `--record --key`, ou poussez les métriques avec le plugin publish-metrics ou OpenTelemetry.
Artillery vs k6 ou JMeter : lequel devriez-vous utiliser ?
Tous les trois gèrent la charge à grande échelle. Artillery utilise du YAML déclaratif et Node.js, ce qui convient aux équipes déjà dans l'écosystème JavaScript. k6 s'appuie sur des scripts JavaScript avec un modèle "code-first". JMeter est basé sur une interface graphique et Java avec une longue histoire de plugins. La comparaison Gatling vs JMeter couvre les compromis plus en détail. Choisissez celui dont le modèle de script correspond à votre équipe, puis associez-le à des tests CI fonctionnels pour une couverture complète.