Exécuter des tests JMeter avec le client API LoadFocus

Ce guide explique comment utiliser le client API LoadFocus, à la fois via l'interface en ligne de commande (CLI) et en utilisant directement la bibliothèque JavaScript dans vos applications. Il exécute, par nom, des tests JMeter qui existent déjà dans votre compte LoadFocus. Vous avez besoin de votre clé API et de votre ID d'équipe, disponibles sur la page Clés API. Pour des configurations de pipeline prêtes à l'emploi, voir Intégration du client API JMeter avec les pipelines CI/CD.

Table des matières

Installation

Installation globale

npm install -g @loadfocus/loadfocus-api-client

Installation dans un projet local

npm install @loadfocus/loadfocus-api-client

Configuration

Avant d'utiliser le client API LoadFocus, vous devez configurer vos identifiants API.

Configuration CLI

# Definir la cle API et l'ID d'equipe
loadfocus-api config set --apikey YOUR_API_KEY --teamid YOUR_TEAM_ID


# Verifier la configuration
loadfocus-api config show

Configuration JavaScript

const { configManager } = require('@loadfocus/loadfocus-api-client');


// Definir la configuration
configManager.set({ apiKey: 'YOUR_API_KEY', teamId: 'YOUR_TEAM_ID' });


// Verifier la configuration
console.log(configManager.isConfigured()); // Devrait afficher true si la clé API et l'ID d'équipe sont définis

Interface en ligne de commande (CLI)

Le client API LoadFocus fournit une CLI complète pour interagir avec l'API LoadFocus.

Exécution de tests JMeter

Exécuter un test

# Executer un test par nom
loadfocus-api jmeter execute --name "My JMeter Test"

Exécuter un test et attendre la fin

# Executer un test et attendre la fin
loadfocus-api jmeter run-test --name "My JMeter Test"


# Executer un test avec des seuils
loadfocus-api jmeter run-test --name "My JMeter Test" --thresholds "avgresponse<=200,errors==0,p95<=250"


# Executer un test avec un delai d'attente et un intervalle d'interrogation personnalises (valeurs par défaut : 1800 et 10 secondes)
loadfocus-api jmeter run-test --name "My JMeter Test" --wait-timeout 1800 --poll-interval 15

Surveillance de l'état des tests

# Verifier l'etat d'un test par nom et ID
loadfocus-api jmeter status --name "My JMeter Test" --id 12345


# Obtenir la liste des executions de test recentes
loadfocus-api jmeter runs

Récupération des résultats

# Obtenir les resultats d'un test specifique
loadfocus-api jmeter results --name "My JMeter Test" --id 12345

Travail avec les seuils

La commande run-test vérifie chaque seuil pour chaque libellé (requête) du test et se termine avec le code de sortie 1 si un seuil échoue : un job CI échoue donc avec elle. Si vous ne passez pas --thresholds, elle utilise avgresponse<=100, soit un temps de réponse moyen de 100 ms ou moins.

# Executer un test avec plusieurs seuils
loadfocus-api jmeter run-test --name "My JMeter Test" --thresholds "avgresponse<=200,errors==0,p95<=250,hitspersec>=10"

Opérateurs de seuil pris en charge :

  • <= - Inférieur ou égal à
  • < - Inférieur à
  • >= - Supérieur ou égal à
  • > - Supérieur à
  • == (ou =) - Égal à
  • != - Différent de

Les métriques utilisables sont :

  • avgresponse, min, max, p95 et p99 : temps de réponse en millisecondes
  • errors : nombre d'erreurs
  • hitspersec : débit en requêtes par seconde
  • samples : nombre d'échantillons

Un nom de métrique absent de cette liste est ignoré sans erreur : vérifiez donc l'orthographe.

Formats de sortie

# Afficher le résultat final en JSON (des lignes de progression s'affichent avant)
loadfocus-api jmeter run-test --name "My JMeter Test" --format json


# Sortie formatee par defaut
loadfocus-api jmeter run-test --name "My JMeter Test"

Utilisation de la bibliothèque JavaScript

Le client API LoadFocus peut également être utilisé directement comme bibliothèque JavaScript dans vos applications.

Configuration de base

// Importer le client API LoadFocus
const loadfocus = require('@loadfocus/loadfocus-api-client');


// Acceder aux composants specifiques
const { createClient, configManager } = loadfocus;

Client JMeter

// Creer un client JMeter
const jmeterClient = loadfocus.createClient('jmeter');


// Ou avec une configuration explicite
const jmeterClient = loadfocus.createClient('jmeter', {
  apiKey: 'YOUR_API_KEY',
  teamId: 'YOUR_TEAM_ID'
});

Exécution de tests

async function executeTest() {
  try {
    const result = await jmeterClient.execute({
      testrunname: 'My JMeter Test'
    });


    console.log('Test execution started:', result);
    return result.testrunid; // Retourner l'ID du test pour une utilisation ulterieure
  } catch (error) {
    console.error('Error executing test:', error);
  }
}

Surveillance de l'état des tests

async function checkTestStatus(testName, testId) {
  try {
    const status = await jmeterClient.getStatus({
      testrunname: testName,
      testrunid: testId
    });


    console.log('Test status:', status);
    return status.state; // Retourner l'etat actuel
  } catch (error) {
    console.error('Error checking test status:', error);
  }
}

Récupération des résultats

async function getTestResults(testName, testId) {
  try {
    // Obtenir les labels disponibles pour le test
    const labels = await jmeterClient.getLabels({
      testrunname: testName,
      testrunid: testId
    });


    console.log('Test labels:', labels);


    // Obtenir les resultats pour chaque label
    const allResults = [];
    for (const item of labels) {
      const labelResults = await jmeterClient.getResults({
        testrunname: testName,
        testrunid: testId,
        filter: item.label
      });


      allResults.push({
        label: item.label,
        results: labelResults
      });
    }


    console.log('Test results:', allResults);
    return allResults;
  } catch (error) {
    console.error('Error retrieving test results:', error);
  }
}

Exemple complet

Voici un exemple complet qui exécute un test, attend la fin et récupère les résultats :

const { createClient, configManager } = require('@loadfocus/loadfocus-api-client');


// Configurer
configManager.set({ apiKey: 'YOUR_API_KEY', teamId: 'YOUR_TEAM_ID' });


// Creer le client
const jmeterClient = createClient('jmeter');


async function runCompleteTest() {
  try {
    // Executer le test
    console.log('Executing test...');
    const executeResult = await jmeterClient.execute({
      testrunname: 'My JMeter Test'
    });


    const testId = executeResult.testrunid;
    console.log(`Test execution started with ID: ${testId}`);


    // Attendre la fin
    console.log('Waiting for test to complete...');
    let completed = false;
    while (!completed) {
      const status = await jmeterClient.getStatus({
        testrunname: 'My JMeter Test',
        testrunid: testId
      });


      console.log(`Current state: ${status.state}`);


      if (status.state === 'finished') {
        completed = true;
      } else if (['aborted', 'finished_failed_to_run', 'finished_failed_timeout'].includes(status.state)) {
        throw new Error(`Test ended with state: ${status.state}`);
      } else {
        // Attendre avant de verifier a nouveau
        await new Promise(resolve => setTimeout(resolve, 10000));
      }
    }


    // Obtenir les resultats
    console.log('Getting test results...');
    const labels = await jmeterClient.getLabels({
      testrunname: 'My JMeter Test',
      testrunid: testId
    });


    const allResults = [];
    for (const item of labels) {
      const labelResults = await jmeterClient.getResults({
        testrunname: 'My JMeter Test',
        testrunid: testId,
        filter: item.label
      });


      allResults.push({
        label: item.label,
        results: labelResults
      });
    }


    console.log('Test results:', JSON.stringify(allResults, null, 2));
    return allResults;
  } catch (error) {
    console.error('Error running test:', error);
  }
}


// Executer le test
runCompleteTest();

Utilisation avancée

Gestion des erreurs

Le client API LoadFocus fournit des informations détaillées sur les erreurs :

try {
  const result = await jmeterClient.execute({
    testrunname: 'My JMeter Test'
  });
} catch (error) {
  if (error.status) {
    // La requete a ete effectuee et le serveur a repondu avec un code d'etat
    // en dehors de la plage 2xx
    console.error('API Error:', error.status, error.data);
  } else if (error.request) {
    // La requete a ete effectuee mais aucune reponse n'a ete recue
    console.error('Network Error:', error.request);
  } else {
    // Quelque chose s'est passe lors de la configuration de la requete qui a declenche une erreur
    console.error('Request Error:', error.message);
  }
}

Dépannage

Problèmes courants

  1. Erreurs d'authentification :

    • Assurez-vous que votre clé API et votre ID d'équipe sont correctement configurés
    • Vérifiez que votre clé API dispose des autorisations nécessaires

  2. Échecs d'exécution de tests :

    • Vérifiez que le nom du test existe dans votre compte LoadFocus
    • Vérifiez si vous avez atteint la limite de tests simultanés de votre compte

  3. Problèmes de délai d'attente :

    • Pour les tests de longue durée, augmentez le paramètre --wait-timeout (1800 secondes par défaut)

  4. Problèmes de récupération des résultats :

    • Assurez-vous que le test est terminé avant de récupérer les résultats
    • Vérifiez que l'ID du test est correct

Pour une aide supplémentaire, veuillez contacter le support.

Précédent
Analyse des fichiers de log JMeter
Suivant
Intégration du client API JMeter avec les pipelines CI/CD