Ejecutar pruebas JMeter con el cliente API de LoadFocus

Esta guía explica cómo usar el Cliente API de LoadFocus, tanto a través de la interfaz de línea de comandos (CLI) como usando directamente la biblioteca JavaScript en tus aplicaciones. Ejecuta pruebas JMeter que ya existen en tu cuenta de LoadFocus, por nombre. Necesitas tu clave API y tu ID de equipo de la página de claves API. Para configuraciones de pipeline ya preparadas, consulta Integrar el cliente API de JMeter con pipelines de CI/CD.

Tabla de Contenidos

• Instalación
• Configuración
• Interfaz de Línea de Comandos (CLI)
  • Ejecución de Pruebas JMeter
  • Monitoreo de Estado de Pruebas
  • Recuperación de Resultados
  • Trabajo con Umbrales
  • Formatos de Salida
• Uso de la Biblioteca JavaScript
  • Configuración Básica
  • Cliente JMeter
  • Ejecución de Pruebas
  • Monitoreo de Estado de Pruebas
  • Recuperación de Resultados
  • Ejemplo Completo
• Uso Avanzado
  • Manejo de Errores
• Solución de Problemas

Instalación

Instalación Global

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

Instalación en Proyecto Local

npm install @loadfocus/loadfocus-api-client

Configuración

Antes de usar el Cliente API de LoadFocus, necesitas configurar tus credenciales de API.

Configuración CLI

# Establecer clave API e ID de equipo
loadfocus-api config set --apikey YOUR_API_KEY --teamid YOUR_TEAM_ID

# Verificar configuración
loadfocus-api config show

Configuración JavaScript

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

// Establecer configuración
configManager.set({ apiKey: 'YOUR_API_KEY', teamId: 'YOUR_TEAM_ID' });

// Verificar configuración
console.log(configManager.isConfigured()); // Debería imprimir true si la clave API y el ID de equipo están establecidos

Interfaz de Línea de Comandos (CLI)

El Cliente API de LoadFocus proporciona un CLI completo para interactuar con la API de LoadFocus.

Ejecución de Pruebas JMeter

Ejecutar una Prueba

# Ejecutar una prueba por nombre
loadfocus-api jmeter execute --name "My JMeter Test"

Ejecutar una Prueba y Esperar a que Complete

# Ejecutar una prueba y esperar a que complete
loadfocus-api jmeter run-test --name "My JMeter Test"

# Ejecutar una prueba con umbrales
loadfocus-api jmeter run-test --name "My JMeter Test" --thresholds "avgresponse<=200,errors==0,p95<=250"

# Ejecutar una prueba con timeout y intervalo de consulta personalizados (valores por defecto: 1800 y 10 segundos)
loadfocus-api jmeter run-test --name "My JMeter Test" --wait-timeout 1800 --poll-interval 15

Monitoreo de Estado de Pruebas

# Verificar estado de una prueba por nombre e ID
loadfocus-api jmeter status --name "My JMeter Test" --id 12345

# Obtener una lista de ejecuciones de prueba recientes
loadfocus-api jmeter runs

Recuperación de Resultados

# Obtener resultados para una prueba específica
loadfocus-api jmeter results --name "My JMeter Test" --id 12345

Trabajo con Umbrales

El comando run-test comprueba cada umbral con cada etiqueta (petición) de la prueba y termina con el código de salida 1 si algún umbral falla, así que un trabajo de CI falla con él. Si no pasas --thresholds, usa avgresponse<=100, es decir, un tiempo de respuesta medio de 100 ms o menos.

# Ejecutar una prueba con múltiples umbrales
loadfocus-api jmeter run-test --name "My JMeter Test" --thresholds "avgresponse<=200,errors==0,p95<=250,hitspersec>=10"

Operadores de umbral soportados:

• <= - Menor o igual que
• < - Menor que
• >= - Mayor o igual que
• > - Mayor que
• == (o =) - Igual a
• != - No igual a

Las métricas que puedes usar son:

• avgresponse, min, max, p95 y p99: tiempos de respuesta en milisegundos
• errors: número de errores
• hitspersec: rendimiento en peticiones por segundo
• samples: número de muestras

Un nombre de métrica que no esté en esta lista se omite sin error, así que revisa la ortografía.

Formatos de Salida

# Imprimir el resultado final como JSON (antes se imprimen líneas de progreso)
loadfocus-api jmeter run-test --name "My JMeter Test" --format json

# Salida con formato legible por defecto
loadfocus-api jmeter run-test --name "My JMeter Test"

Uso de la Biblioteca JavaScript

El Cliente API de LoadFocus también puede usarse directamente como una biblioteca JavaScript en tus aplicaciones.

Configuración Básica

// Importar el Cliente API de LoadFocus
const loadfocus = require('@loadfocus/loadfocus-api-client');

// Acceder a componentes específicos
const { createClient, configManager } = loadfocus;

Cliente JMeter

// Crear un cliente JMeter
const jmeterClient = loadfocus.createClient('jmeter');

// O con configuración explícita
const jmeterClient = loadfocus.createClient('jmeter', {
  apiKey: 'YOUR_API_KEY',
  teamId: 'YOUR_TEAM_ID'
});

Ejecución de Pruebas

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

    console.log('Test execution started:', result);
    return result.testrunid;
  } catch (error) {
    console.error('Error executing test:', error);
  }
}

Monitoreo de Estado de Pruebas

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

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

Recuperación de Resultados

async function getTestResults(testName, testId) {
  try {
    const labels = await jmeterClient.getLabels({
      testrunname: testName,
      testrunid: testId
    });

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

    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);
  }
}

Ejemplo Completo

Aquí hay un ejemplo completo que ejecuta una prueba, espera a que complete y recupera los resultados:

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

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

// Crear cliente
const jmeterClient = createClient('jmeter');

async function runCompleteTest() {
  try {
    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}`);

    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 {
        await new Promise(resolve => setTimeout(resolve, 10000));
      }
    }

    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);
  }
}

runCompleteTest();

Uso Avanzado

Manejo de Errores

El Cliente API de LoadFocus proporciona información detallada de errores:

try {
  const result = await jmeterClient.execute({
    testrunname: 'My JMeter Test'
  });
} catch (error) {
  if (error.status) {
    console.error('API Error:', error.status, error.data);
  } else if (error.request) {
    console.error('Network Error:', error.request);
  } else {
    console.error('Request Error:', error.message);
  }
}

Solución de Problemas

Problemas Comunes

1. Errores de Autenticación:

   • Asegúrate de que tu clave API e ID de equipo estén correctamente configurados
   • Verifica que tu clave API tenga los permisos necesarios

2. Fallos en la Ejecución de Pruebas:

   • Verifica que el nombre de la prueba exista en tu cuenta de LoadFocus
   • Comprueba si has alcanzado el límite de pruebas concurrentes de tu cuenta

3. Problemas de Timeout:

   • Para pruebas de larga duración, aumenta el parámetro --wait-timeout (1800 segundos por defecto)

4. Problemas de Recuperación de Resultados:

   • Asegúrate de que la prueba haya completado antes de recuperar resultados
   • Verifica que el ID de la prueba sea correcto

Para ayuda adicional, contacta soporte.