Si votre API fonctionne pour un seul utilisateur mais ralentit ou échoue sous trafic, ajoutez des tests de charge à votre workflow. k6 est un outil simple pour simuler des utilisateurs virtuels, mesurer la latence, suivre les erreurs et définir des seuils de réussite/échec. Dans ce guide, vous allez installer k6, écrire un premier script, configurer des profils de charge et lire les résultats pour intégrer ces contrôles à vos tests de performance d'API. Les exemples suivent les principes de la documentation officielle de k6.
Qu'est-ce que k6 ?
k6 est un outil de test de charge open-source, maintenu par Grafana. Vous écrivez vos scénarios en JavaScript, puis k6 les exécute avec un moteur Go optimisé pour générer une charge importante depuis une seule machine.
k6 sert à une tâche précise : générer une charge soutenue et reproductible, puis mesurer comment votre système répond. Il rapporte notamment :
- les centiles de latence ;
- le débit en requêtes par seconde ;
- le taux d'erreur ;
- les assertions réussies ou échouées ;
- les seuils de performance qui font échouer le test si nécessaire.
k6 n'est pas un client API complet, un outil de documentation ou un framework de test fonctionnel. C'est un moteur de charge.
Termes à connaître avant d'écrire un script :
| Terme | Signification |
|---|---|
| VU, ou utilisateur virtuel | Utilisateur simulé qui exécute votre script en boucle |
| Itération | Exécution complète de la fonction de test par un VU |
| Stage | Étape d'un profil de charge, utilisée pour augmenter ou réduire les VU |
| Threshold, ou seuil | Règle de réussite/échec sur une métrique |
| Check, ou vérification | Assertion non bloquante sur une réponse HTTP |
Installation de k6
k6 est distribué sous forme de binaire. L'installation est rapide.
Sur macOS avec Homebrew :
brew install k6
Sur Windows avec Chocolatey :
choco install k6
Sur Debian ou 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
Vérifiez l'installation :
k6 version
Vous pouvez aussi utiliser l'image Docker officielle si vous ne voulez rien installer localement. Consultez la documentation k6 pour les commandes à jour, car les instructions d'installation peuvent évoluer.
Écrire un premier script k6
Un test k6 est un module JavaScript avec une fonction default. k6 appelle cette fonction à chaque itération, pour chaque utilisateur virtuel.
Créez un fichier 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);
}
Lancez le test :
k6 run script.js
Par défaut, k6 exécute un VU pour une itération. Le sleep(1) ajoute une pause d'une seconde entre les itérations. C'est utile pour simuler un comportement utilisateur plus réaliste.
Sans sleep(), chaque VU boucle aussi vite que possible. Ce mode peut servir à tester le débit maximal, mais il représente rarement un trafic utilisateur réel.
Les appels check() sont des assertions souples. Si une vérification échoue, le test continue. Cela permet de mesurer la dégradation du système au lieu d'arrêter l'exécution à la première erreur.
Configurer les VU, les stages et les seuils
Pour contrôler la charge, exportez un objet options.
Exemple avec un nombre fixe d'utilisateurs virtuels :
export const options = {
vus: 50,
duration: '30s',
};
Ce test exécute 50 VU pendant 30 secondes.
Pour un scénario plus réaliste, utilisez des stages :
export const options = {
stages: [
{ duration: '1m', target: 100 }, // montée à 100 VU
{ duration: '3m', target: 100 }, // maintien à 100 VU
{ duration: '1m', target: 0 }, // descente à 0 VU
],
thresholds: {
http_req_duration: ['p(95)<500'], // 95 % des requêtes sous 500 ms
http_req_failed: ['rate<0.01'], // moins de 1 % d'erreurs
},
};
Les seuils rendent k6 utile en CI/CD. Si un seuil échoue, k6 termine avec un code de sortie non nul. Votre pipeline peut donc échouer automatiquement si la latence ou le taux d'erreur dépasse votre budget de performance.
Profils de charge courants :
| Profil | Objectif | Ce que cela vérifie |
|---|---|---|
| Smoke | Petite charge | Le script fonctionne correctement |
| Charge | Trafic normal attendu | L'API tient-elle le trafic quotidien |
| Stress | Charge au-delà du pic attendu | Où l'API commence à échouer |
| Spike | Hausse soudaine du trafic | L'API absorbe-t-elle une pointe brutale |
| Soak | Charge modérée sur plusieurs heures | Fuites mémoire ou dégradation progressive |
Commencez simple :
- écrivez un test smoke ;
- ajoutez un test de charge normale ;
- mesurez vos métriques de référence ;
- ajoutez ensuite les scénarios stress, spike ou soak si nécessaire.
Pour replacer ces profils dans une stratégie plus large, les fondamentaux des tests de performance s'appliquent à k6 comme aux autres outils.
Lire les résultats k6
À la fin d'une exécution, k6 affiche un résumé dans le terminal.
Les métriques les plus importantes :
| Métrique | Utilité |
|---|---|
http_req_duration |
Temps total de requête, avec moyenne, min, max, médiane, p90 et p95 |
http_req_failed |
Proportion de requêtes échouées |
http_reqs |
Nombre total de requêtes et requêtes par seconde |
iterations |
Nombre d'itérations complètes exécutées |
vus / vus_max
|
VU actifs et maximum atteint |
checks |
Taux de réussite des assertions check()
|
Priorisez les centiles plutôt que la moyenne.
Une moyenne de 200 ms peut sembler correcte, mais un p99 à 4 secondes signifie qu'un utilisateur sur cent attend quatre secondes. Cette latence de queue est souvent celle qui provoque les abandons.
Pour une analyse plus avancée, k6 peut exporter les résultats vers :
- JSON ;
- CSV ;
- Grafana ;
- Prometheus.
Pour un test ponctuel, le résumé terminal suffit souvent. Pour un suivi continu ou une analyse en équipe, envoyez les métriques vers un tableau de bord.
Où utiliser k6 et où utiliser Apidog
k6 répond à une question précise :
Comment mon système se comporte-t-il sous une charge soutenue ?
Il ne remplace pas les tests fonctionnels ou contractuels. Il ne vérifie pas en profondeur si chaque endpoint renvoie les bonnes données, respecte son contrat ou gère correctement l'authentification.
Répartissez les responsabilités :
| Besoin | Outil adapté | Question traitée |
|---|---|---|
| Charge soutenue, centiles à grande échelle | k6 | L'API reste-t-elle rapide sous trafic |
| Correction fonctionnelle, contrat, authentification | Apidog | L'API renvoie-t-elle ce qui est attendu |
| Régression à chaque commit | Apidog avec apidog run
|
Un endpoint a-t-il été cassé |
| Budget de performance en CI | Seuils k6 | La latence ou les erreurs dépassent-elles une limite |
Apidog couvre la partie justesse fonctionnelle. Vous pouvez concevoir ou importer une API, créer des scénarios de test avec assertions, puis les exécuter en CI avec apidog run.
Le guide CLI d'Apidog montre comment intégrer ces tests dans un pipeline. Apidog propose aussi des fonctionnalités de test de performance plus légères pour des vérifications rapides, décrites dans le guide des tests de performance API dans Apidog. Ce n'est toutefois pas un générateur de charge de la même catégorie que k6.
Un workflow pratique :
- À chaque commit, exécutez les tests fonctionnels et contractuels avec Apidog.
- Avant une release ou selon un planning régulier, exécutez les tests de charge k6 sur un environnement de staging.
- Faites échouer le pipeline si les assertions fonctionnelles ou les seuils de performance échouent.
Vous obtenez ainsi deux portes de validation : une pour la justesse, une pour la performance.
Si vous comparez plusieurs moteurs de charge, k6 se situe à côté de JMeter, Gatling et Locust. Le récapitulatif des outils de test de charge et cette comparaison des alternatives à Locust peuvent vous aider si le langage de script ou l'échelle influencent votre choix.
Questions fréquentes
Est-ce que k6 est gratuit ?
Oui. k6 est open source sous licence AGPL. Le binaire peut être exécuté localement gratuitement, sans limite d'utilisateurs virtuels autre que les capacités de votre machine.
Grafana propose aussi k6 Cloud, un service payant pour exécuter de grands tests distribués et stocker les résultats, mais il n'est pas obligatoire. Pour comparer avec d'autres options gratuites, consultez l'aperçu des outils de test de charge.
Faut-il connaître JavaScript pour utiliser k6 ?
Oui, mais un niveau de base suffit. La plupart des scripts k6 utilisent :
- une fonction
default; - quelques appels
http.get()ouhttp.post(); - des
check(); - un objet
options.
Il n'y a pas d'étape de compilation ni de framework complexe à apprendre.
Quelle est la différence entre k6 et Apidog pour les tests de performance ?
k6 est un générateur de charge dédié. Il est conçu pour produire un trafic lourd et soutenu, puis mesurer les centiles et les erreurs à grande échelle.
Apidog est une plateforme API orientée conception, tests fonctionnels, tests de contrat et documentation, avec des fonctionnalités de performance plus légères pour des vérifications rapides.
Utilisez k6 pour la charge réelle et les budgets de performance en CI. Utilisez Apidog pour vérifier la justesse, le contrat et les régressions fonctionnelles.
Puis-je exécuter k6 en CI/CD ?
Oui. C'est même l'un de ses usages les plus utiles.
Exemple minimal d'étape CI :
k6 run script.js
Ajoutez des seuils dans le script :
export const options = {
thresholds: {
http_req_duration: ['p(95)<500'],
http_req_failed: ['rate<0.01'],
},
};
Si un seuil échoue, k6 renvoie un code non nul. Votre pipeline peut alors bloquer la build ou la release.
Associez cette étape à des tests fonctionnels avec apidog run pour vérifier à la fois la justesse et la performance.
Conclusion
k6 fournit une manière scriptable et reproductible de tester une API sous charge. Le workflow est direct :
- installez k6 ;
- écrivez un script JavaScript ;
- configurez les VU et les stages ;
- ajoutez des seuils ;
- analysez les centiles et le taux d'erreur ;
- exécutez le tout en CI/CD.
Gardez les tests de charge séparés des tests fonctionnels. Ils répondent à des questions différentes, mais les deux sont nécessaires pour livrer une API fiable.
Pour la partie justesse, Apidog vous aide à concevoir, tester, simuler et documenter votre API, puis à exécuter vos tests fonctionnels en CI avec apidog run.
Top comments (0)