API de tests de charge

L'API de tests de charge permet à un script ou à un pipeline CI/CD de lancer un test de charge enregistré, de suivre l'exécution jusqu'à la fin et de lire ses résultats et son verdict réussi ou échoué. Elle fonctionne pour les tests cloud, les tests JMeter et les tests k6. Créez et enregistrez d'abord le test dans le tableau de bord : l'API exécute un test enregistré d'après son nom.

Authentification

Chaque requête a besoin de votre clé API et, si vous faites partie de plusieurs équipes, de l'id de l'équipe à laquelle appartient le test.

Clé API : copiez-la ou régénérez-la sur la page Clés API (Paramètres du compte > Clés API). La clé appartient à votre utilisateur et fonctionne dans toutes les équipes dont vous êtes membre. Traitez-la comme un mot de passe.
Id d'équipe : la page Équipe par défaut (Paramètres du compte > Équipe par défaut) affiche l'équipe utilisée par les appels API qui n'en indiquent aucune, avec son id, et vous permet de la changer. La page Developers de la Surveillance API affiche côte à côte votre clé API et l'id de votre équipe actuelle.

Envoyez la clé dans l'en-tête loadfocus-auth et l'id d'équipe dans l'en-tête team-id. Sans team-id, votre équipe par défaut est utilisée. Une clé erronée, ou une équipe dont vous n'êtes pas membre, reçoit 401. Un membre de l'équipe sans accès aux tests de charge reçoit 403, tout comme un membre en lecture seule qui tente de lancer ou d'arrêter une exécution ou de modifier les seuils. L'API accepte aussi la clé en paramètre de requête apikey, mais un en-tête la tient à l'écart des logs des serveurs et des proxys.

Ce que permet votre forfait

Les tests cloud peuvent être lancés via l'API avec tous les forfaits, Load Free compris.
Les tests JMeter et k6 demandent un forfait payant, ou un essai d'un forfait payant, pour lancer une exécution via l'API. Avec Load Free, la requête est refusée avec 400 et { "error": "Not available on the free plans. Please upgrade for API access." }. Dans le tableau de bord, les comptes Free peuvent toujours les exécuter dans les limites de Free.
Lister les tests, lire les états, les résultats et les verdicts, et définir les seuils fonctionnent avec tous les forfaits.
Le forfait qui compte est celui du propriétaire de l'équipe, comme dans le tableau de bord.

Les exécutions lancées via l'API comptent dans les mêmes limites d'exécutions que celles lancées depuis le tableau de bord. Elles ont aussi un plafond hebdomadaire par type de test : 10 exécutions avec Load Free, 5 pendant un essai (25 pendant un essai de Load Starter) et 25 avec Load Starter (voir Forfaits et limites). Une exécution refusée répond 400 avec la limite atteinte, par exemple { "error": "number-of-weekly-tests-exceeded", "window": "week", "current": 10, "maximum": 10, "retryAt": "2026-11-12T09:30:00.000Z" }, où retryAt indique quand la prochaine exécution est autorisée.

Limites de débit

Points d'accès JMeter et k6 : 100 requêtes par tranche de 15 minutes par clé API. Lancer et arrêter des exécutions dispose de son propre quota de 100 requêtes par tranche de 5 minutes par clé API.
Le point d'accès d'analyse des résultats des tests cloud : 100 requêtes par tranche de 15 minutes par clé API.
Chaque requête sous /api/ : 10 000 par tranche de 2 minutes par adresse IP.

Au-delà d'une limite, l'API répond 429. Interroger l'état d'une exécution toutes les 30 secondes reste largement en dessous.

Points d'accès

Tous les chemins commencent par https://loadfocus.com/api/v1/ suivi du type de test : loadtests pour les tests cloud, jmetertests pour les tests JMeter et k6tests pour les tests k6. Un test est désigné par testrunname, le nom sous lequel vous l'avez enregistré, et une exécution par testrunid, son numéro d'exécution (voir Qu'est-ce qu'un identifiant d'exécution de test ?). Encodez le nom pour l'URL quand il figure dans une chaîne de requête.

Action	Méthode et chemin	Paramètres	Types de test
Lister vos tests, chacun avec sa dernière exécution	`GET /api/v1/{type}/`	aucun	tous
Lancer une exécution d'un test enregistré	`POST /api/v1/{type}/newtest/execute`	`testrunname`	tous
Arrêter un test en cours	`POST /api/v1/{type}/stop`	`testrunname`, `testrunid`	JMeter, k6
Lire l'état d'une exécution	`GET /api/v1/{type}/state`	`testrunname`, `testrunid`	tous
Lire les résultats d'une exécution	`GET /api/v1/{type}/analysis`	`testrunname`, `testrunid`	tous
Lire le verdict d'une exécution	`GET /api/v1/{type}/verdict`	`testrunname`, `testrunid`	tous
Lire, définir ou effacer les seuils	`GET`, `PUT`, `DELETE /api/v1/{type}/thresholds`	`testrunname` ; pour `PUT`, les limites	tous

Lancer une exécution : pour les tests cloud, envoyez testrunname dans la chaîne de requête ; pour les tests JMeter et k6, en champ de formulaire. La réponse ne contient pas le numéro de la nouvelle exécution, attribué quelques secondes plus tard. Notez le dernier testrunid du test dans la liste avant de le lancer, puis relisez la liste jusqu'à ce qu'un numéro plus élevé apparaisse. Pour marquer l'exécution avec la version que vous déployez, attendez que son numéro d'exécution apparaisse, puis envoyez testrunname, testrunid, label et éventuellement url en champs de formulaire à POST /api/test/{general|jmeter|k6}/run-annotation (general pour les tests cloud), avec les mêmes en-têtes. releaseTag et releaseUrl dans la requête de lancement ne s'appliquent que si la requête contient aussi un testrunid. Voir Étiquettes de version et annotations d'exécution. JMeter et k6 acceptent aussi POST /api/v1/{type}/execute, qu'utilise le client API LoadFocus.
Arrêter : envoyez testrunname et testrunid en champs de formulaire. Un test cloud ne peut pas être arrêté via l'API ; arrêtez-le depuis le tableau de bord.
État : state vaut running pendant le test et finished quand il est terminé. aborted, error, failed et finished_failed_to_run signifient que l'exécution s'est terminée sans résultats.
Résultats : l'API d'analyse des résultats décrit le document : percentiles, Apdex, types d'erreur, chiffres par requête et par région.
Verdict et seuils : Seuils de réussite/échec décrit les limites et le verdict. Ne lisez le verdict qu'une fois l'état à finished. Un test sans seuils activés renvoie verdict: "none".

Exemples

Lancer un test k6 enregistré, puis un test cloud enregistré :

curl -X POST "https://loadfocus.com/api/v1/k6tests/newtest/execute" \
  -H "loadfocus-auth: YOUR_API_KEY" -H "team-id: YOUR_TEAM_ID" \
  --data-urlencode "testrunname=checkout-flow"

curl -X POST "https://loadfocus.com/api/v1/loadtests/newtest/execute?testrunname=checkout-flow" \
  -H "loadfocus-auth: YOUR_API_KEY" -H "team-id: YOUR_TEAM_ID"

Lire le verdict de l'exécution 12 du test k6 :

curl "https://loadfocus.com/api/v1/k6tests/verdict?testrunname=checkout-flow&testrunid=12" \
  -H "loadfocus-auth: YOUR_API_KEY" -H "team-id: YOUR_TEAM_ID"

Lancer un test depuis GitHub Actions

Ce workflow lance un test k6 enregistré, attend la fin de l'exécution et fait échouer le job quand le verdict est un échec. Enregistrez votre clé API et votre id d'équipe comme secrets du dépôt LOADFOCUS_API_KEY et LOADFOCUS_TEAM_ID, et définissez d'abord les seuils de réussite/échec du test, sinon rien ne peut le faire échouer. Pour un test cloud, remplacez k6tests par loadtests, et pour un test JMeter par jmetertests.

name: Load test
on:
  workflow_dispatch:

jobs:
  load-test:
    runs-on: ubuntu-latest
    steps:
      - name: Run the saved test and check its verdict
        shell: bash
        env:
          KEY: ${{ secrets.LOADFOCUS_API_KEY }}
          TEAM: ${{ secrets.LOADFOCUS_TEAM_ID }}
          API: https://loadfocus.com/api/v1/k6tests
          TEST: checkout-flow
        run: |
          H=(-sS -H "loadfocus-auth: $KEY" -H "team-id: $TEAM")
          Q=$(jq -rn --arg t "$TEST" '$t|@uri')
          latest() {
            curl "${H[@]}" --fail-with-body "$API/" |
              jq -r --arg t "$TEST" '[.[] | select(.testrunname == $t) | .testrunid | tonumber] | max // 0'
          }

          before=$(latest)
          curl "${H[@]}" --fail-with-body -X POST "$API/newtest/execute?testrunname=$Q" \
            --data-urlencode "testrunname=$TEST"
          echo

          # Le numéro d'exécution est attribué quelques secondes après la requête de lancement.
          id=$before
          for i in $(seq 30); do
            sleep 10
            id=$(latest)
            [ "$id" -gt "$before" ] && break
          done
          [ "$id" -gt "$before" ] || { echo "The run did not start"; exit 1; }

          # Attendre jusqu'à 30 minutes la fin de l'exécution.
          state=""
          for i in $(seq 60); do
            state=$(curl "${H[@]}" --fail-with-body "$API/state?testrunname=$Q&testrunid=$id" | jq -r '.state // .teststate // empty')
            echo "Run $id: ${state:-starting}"
            case "$state" in
              finished) break ;;
              aborted|error|failed|finished_failed_to_run) exit 1 ;;
            esac
            sleep 30
          done
          [ "$state" = finished ] || { echo "Timed out"; exit 1; }

          curl "${H[@]}" --fail-with-body "$API/verdict?testrunname=$Q&testrunid=$id" > verdict.json
          jq '{verdict, checks}' verdict.json
          jq -e '.verdict != "fail" and (.enabled == false or (.metricsAvailable and ((.unevaluated // []) | length == 0)))' verdict.json

La dernière ligne fait aussi échouer le job quand des seuils sont activés mais n'ont pas pu être vérifiés, par exemple parce que l'exécution n'a enregistré aucune métrique : une exécution cassée ne passe donc jamais au vert.

Le client API LoadFocus

Le paquet npm @loadfocus/loadfocus-api-client (commande loadfocus-api) ne prend en charge que les tests JMeter. Il lance un test JMeter enregistré, attend qu'il se termine et compare les résultats aux limites que vous passez en ligne de commande (--thresholds). Il n'a aucune commande pour les tests k6 ou cloud : pour ceux-là, appelez l'API directement comme ci-dessus.

Pipelines JMeter prêts à l'emploi avec le client :