GitLab CI/CD

Esta guía muestra cómo iniciar una prueba JMeter de LoadFocus desde un pipeline de GitLab CI/CD, esperar a que termine y hacer fallar el pipeline cuando no se cumple un umbral. Usa el LoadFocus API Client (loadfocus-api, instalado desde npm). Primero crea y guarda la prueba en LoadFocus, consulta Cómo ejecutar una nueva prueba de carga con Apache JMeter; el pipeline inicia esa prueba guardada por su nombre.

Pasos de Configuración

1. Almacenar Credenciales como Variables de GitLab CI/CD

Primero, almacena tus credenciales de API de LoadFocus como variables de GitLab CI/CD:

Ve a tu proyecto de GitLab
Navega a Settings > CI/CD > Variables
Agrega las siguientes variables:
- LOADFOCUS_API_KEY: Tu clave API de LoadFocus (marca como "Masked")
- LOADFOCUS_TEAM_ID: Tu ID de equipo de LoadFocus

Ambas están en la página Claves API de la configuración de tu cuenta de LoadFocus.

2. Crear un Pipeline de GitLab CI/CD

Crea o actualiza tu archivo .gitlab-ci.yml en tu repositorio:

stages:
  - build
  - test
  - performance
  - deploy

variables:
  NODE_VERSION: "20"

build:
  stage: build
  image: node:${NODE_VERSION}
  script:
    - npm install
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 week

test:
  stage: test
  image: node:${NODE_VERSION}
  script:
    - npm install
    - npm test

performance_test:
  stage: performance
  image: node:${NODE_VERSION}
  script:
    # Instalar Cliente API de JMeter de LoadFocus
    - npm install -g @loadfocus/loadfocus-api-client

    # Configurar Cliente API de LoadFocus
    - loadfocus-api config set --apikey $LOADFOCUS_API_KEY --teamid $LOADFOCUS_TEAM_ID

    # Ejecutar pruebas de rendimiento. --name es el nombre exacto de una prueba guardada en LoadFocus.
    - |
      loadfocus-api jmeter run-test \
        --name "My_JMeter_Test" \
        --thresholds "avgresponse<=200,errors==0,p95<=250" \
        --format json > performance_results.json
  artifacts:
    paths:
      - performance_results.json
    expire_in: 1 week
    when: always
  # Opcional: Solo ejecutar en ramas específicas
  only:
    - main
    - develop

deploy:
  stage: deploy
  script:
    - echo "Deploying application..."
  only:
    - main
  # Solo desplegar si todas las etapas anteriores tuvieron éxito
  when: on_success

run-test inicia la prueba guardada, espera a que termine y comprueba los umbrales. Si no se cumple algún umbral, o la ejecución falla, el comando termina con código 1 y el job falla, así que la etapa deploy no se ejecuta. Los umbrales se comprueban para cada etiqueta de petición por separado, así que basta una petición lenta para que la ejecución falle. errors es un recuento de peticiones fallidas, no un porcentaje. En los ejemplos siguientes, sustituye los nombres GitLab_... por el nombre exacto de tu prueba guardada.

El archivo de salida empieza con algunas líneas de progreso antes del objeto JSON. Para obtener un JSON limpio, conserva solo las líneas desde la primera que contiene únicamente {: sed -n '/^{$/,$p' performance_results.json > results.json.

3. Ver Resultados de Pruebas

Después de que el pipeline se ejecute:

Ve a tu proyecto de GitLab
Navega a CI/CD > Pipelines
Encuentra tu pipeline y haz clic en él
Ve al job "performance_test"
Haz clic en "Browse" en la barra lateral derecha para ver los artefactos
Descarga y visualiza el archivo performance_results.json

Configuración Avanzada

Pruebas Específicas por Entorno

Ejecuta diferentes pruebas de rendimiento para diferentes entornos:

.performance_test_template: &performance_test_definition
  stage: performance
  image: node:${NODE_VERSION}
  script:
    - npm install -g @loadfocus/loadfocus-api-client
    - loadfocus-api config set --apikey $LOADFOCUS_API_KEY --teamid $LOADFOCUS_TEAM_ID
    - |
      loadfocus-api jmeter run-test \
        --name "${TEST_NAME}" \
        --thresholds "${THRESHOLDS}" \
        --format json > performance_results.json
  artifacts:
    paths:
      - performance_results.json
    expire_in: 1 week
    when: always

performance_test_develop:
  <<: *performance_test_definition
  variables:
    TEST_NAME: "API_Test_Develop"
    THRESHOLDS: "avgresponse<=300,errors==0,p95<=500"
  only:
    - develop

performance_test_staging:
  <<: *performance_test_definition
  variables:
    TEST_NAME: "API_Test_Staging"
    THRESHOLDS: "avgresponse<=250,errors==0,p95<=350"
  only:
    - staging

performance_test_production:
  <<: *performance_test_definition
  variables:
    TEST_NAME: "API_Test_Production"
    THRESHOLDS: "avgresponse<=200,errors==0,p95<=250"
  only:
    - main

Pruebas en Paralelo

Ejecuta múltiples pruebas de rendimiento en paralelo:

performance_test_api:
  stage: performance
  image: node:${NODE_VERSION}
  script:
    - npm install -g @loadfocus/loadfocus-api-client
    - loadfocus-api config set --apikey $LOADFOCUS_API_KEY --teamid $LOADFOCUS_TEAM_ID
    - |
      loadfocus-api jmeter run-test \
        --name "API_Performance_Test" \
        --thresholds "avgresponse<=150,errors==0" \
        --format json > api_performance_results.json
  artifacts:
    paths:
      - api_performance_results.json
    expire_in: 1 week

performance_test_ui:
  stage: performance
  image: node:${NODE_VERSION}
  script:
    - npm install -g @loadfocus/loadfocus-api-client
    - loadfocus-api config set --apikey $LOADFOCUS_API_KEY --teamid $LOADFOCUS_TEAM_ID
    - |
      loadfocus-api jmeter run-test \
        --name "UI_Performance_Test" \
        --thresholds "avgresponse<=300,errors==0" \
        --format json > ui_performance_results.json
  artifacts:
    paths:
      - ui_performance_results.json
    expire_in: 1 week

Los jobs de la misma etapa se ejecutan en paralelo, y cada prueba que inician cuenta para el límite de pruebas en paralelo de tu plan. Para ejecutar estas pruebas con un temporizador en lugar de en cada push, crea una programación de pipeline en GitLab:

Ve a tu proyecto de GitLab
Navega a CI/CD > Schedules
Haz clic en "New schedule"
Configura un horario (por ejemplo, todos los días a medianoche)

Integración con Funcionalidades de GitLab

Widgets de Merge Request

Muestra los resultados de pruebas de rendimiento en merge requests usando la funcionalidad de informes JUnit de GitLab:

performance_test:
  stage: performance
  image: node:${NODE_VERSION}
  script:
    # Ejecutar prueba de rendimiento
    - npm install -g @loadfocus/loadfocus-api-client
    - loadfocus-api config set --apikey $LOADFOCUS_API_KEY --teamid $LOADFOCUS_TEAM_ID
    - |
      loadfocus-api jmeter run-test \
        --name "GitLab_${CI_PROJECT_NAME}_${CI_COMMIT_REF_NAME}" \
        --thresholds "avgresponse<=200,errors==0,p95<=250" \
        --format json > performance_results.json

    # Convertir a formato JUnit (usando un script personalizado)
    - node convert-to-junit.js performance_results.json junit-report.xml
  artifacts:
    reports:
      junit: junit-report.xml
    paths:
      - performance_results.json
    expire_in: 1 week

Métricas de GitLab

Usa la funcionalidad de métricas de GitLab para rastrear el rendimiento a lo largo del tiempo:

performance_test:
  stage: performance
  image: node:${NODE_VERSION}
  script:
    # Ejecutar prueba de rendimiento
    - npm install -g @loadfocus/loadfocus-api-client
    - loadfocus-api config set --apikey $LOADFOCUS_API_KEY --teamid $LOADFOCUS_TEAM_ID
    - |
      loadfocus-api jmeter run-test \
        --name "GitLab_${CI_PROJECT_NAME}_${CI_COMMIT_REF_NAME}" \
        --thresholds "avgresponse<=200,errors==0,p95<=250" \
        --format json > performance_results.json

    # Extraer métricas e informarlas a GitLab
    - |
      # Analizar JSON y extraer métricas
      RESPONSE_TIME=$(sed -n '/^{$/,$p' performance_results.json | jq '.labels[0].metrics.avgresponse')
      ERROR_RATE=$(sed -n '/^{$/,$p' performance_results.json | jq '.labels[0].metrics.errors')

      # Informar métricas
      echo "performance_avg_response_time ${RESPONSE_TIME}" >> metrics.txt
      echo "performance_error_rate ${ERROR_RATE}" >> metrics.txt
  artifacts:
    reports:
      metrics: metrics.txt
    paths:
      - performance_results.json
    expire_in: 1 week

Entornos de GitLab

Asocia pruebas de rendimiento con entornos específicos:

performance_test_staging:
  stage: performance
  image: node:${NODE_VERSION}
  environment:
    name: staging
  script:
    - npm install -g @loadfocus/loadfocus-api-client
    - loadfocus-api config set --apikey $LOADFOCUS_API_KEY --teamid $LOADFOCUS_TEAM_ID
    - |
      loadfocus-api jmeter run-test \
        --name "Staging_Performance_Test" \
        --thresholds "avgresponse<=250,errors==0" \
        --format json > performance_results.json
  artifacts:
    paths:
      - performance_results.json
    expire_in: 1 week
  only:
    - staging

Consejos para la Integración con GitLab CI/CD

Caché: Almacena en caché las dependencias de npm para acelerar las ejecuciones del pipeline:

performance_test:
  stage: performance
  image: node:${NODE_VERSION}
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - node_modules/
  script:
    - npm install -g @loadfocus/loadfocus-api-client
    # Resto del script...

Configuración de Tiempo de Espera: Establece tiempos de espera para pruebas de rendimiento de larga duración:

performance_test:
  stage: performance
  image: node:${NODE_VERSION}
  timeout: 2h  # Establecer un tiempo de espera de 2 horas
  script:
    # Script de prueba de rendimiento...

Disparadores Manuales: Permite que las pruebas de rendimiento se disparen manualmente:

performance_test:
  stage: performance
  image: node:${NODE_VERSION}
  script:
    # Script de prueba de rendimiento...
  when: manual

Configuración Dinámica de Pruebas: Usa variables predefinidas de GitLab para configurar pruebas dinámicamente:

performance_test:
  stage: performance
  image: node:${NODE_VERSION}
  script:
    - |
      # Establecer umbrales según la rama
      if [ "$CI_COMMIT_REF_NAME" = "main" ]; then
        THRESHOLDS="avgresponse<=200,errors==0,p95<=250"
      else
        THRESHOLDS="avgresponse<=300,errors==0,p95<=500"
      fi

      loadfocus-api jmeter run-test \
        --name "GitLab_${CI_PROJECT_NAME}_${CI_COMMIT_REF_NAME}" \
        --thresholds "$THRESHOLDS" \
        --format json > performance_results.json

Notificaciones: Envía notificaciones cuando fallen las pruebas de rendimiento:

performance_test:
  stage: performance
  image: node:${NODE_VERSION}
  script:
    # Script de prueba de rendimiento...
  after_script:
    - |
      if [ "$CI_JOB_STATUS" = "failed" ]; then
        # Enviar notificación usando curl, API de GitLab u otro método
        curl -X POST -H "Content-Type: application/json" \
          -d "{\"text\":\"Performance test failed for ${CI_PROJECT_NAME}\"}" \
          $WEBHOOK_URL
      fi

Para más información, consulta la documentación de GitLab CI/CD y la documentación del Cliente API de LoadFocus.