Saltar a contenido

Configurar JMeter

Estado del adapter: ✅ Completo (performance). JMeter es un valor válido de stack.test_framework: lippia-neo-bootstrap-stack lo detecta, ubica el ejecutable y lo configura, y las skills de performance generan, ejecutan y reportan las pruebas de carga. No es un framework de suite funcional: no usa lippia-neo-generate-test-suite, lippia-neo-run-and-heal ni lippia-neo-bootstrap-ci (ver sección 9).

Valor en qa-stack.yaml test_framework: jmeter
Lenguaje java (se fuerza)
Tipo de app api (se fuerza)
Qué usa Apache JMeter 5.6 (core, sin plugins) + una colección de API (Postman o Bruno) + CSV con datos de prueba
Perfiles de carga smoke, load, stress, spike
Configuración Bloque performance de qa-stack.yaml
Carpeta de scripts performance.scripts_dir (por defecto performance/)
Carpeta de resultados performance.results_dir (por defecto target/ con JMeter)

Las skills que lo usan están descriptas en Skills de performance. Corren sin hacer preguntas: todo lo que necesitan lo toman del input o de qa-stack.yaml.


1. Qué necesitás instalado

Herramienta Versión Para qué Cómo verificarlo
Apache JMeter 5.x (los planes apuntan a 5.6, con Groovy incluido en la distribución estándar) Ejecutar los planes .jmx jmeter -v
Java 8 o superior JMeter lo necesita para arrancar java -version
Node.js Una versión vigente Correr el generador y el runner de NEO (scripts .js) node --version

NEO no instala JMeter ni Java. Durante el bootstrap, la skill busca el ejecutable sin preguntarte y guarda su ruta en performance.tool_path. Si no lo encuentra, o falta Java, deja tool_path: null y te avisa qué falta; no se detiene ni instala nada.

Dónde busca el ejecutable:

  • El bootstrap: jmeter en el PATH, JMETER_HOME/bin y las carpetas apache-jmeter-* / jmeter* en C:\, C:\Program Files, C:\Program Files (x86), C:\tools (Windows) o /opt, /usr/local, /usr/share, /opt/homebrew/Cellar (Linux/macOS), tomando la versión más alta. Lo confirma con jmeter -v y java -version.
  • El runner, en este orden: la ruta indicada como input (jmeter_path), el PATH, JMETER_HOME, las rutas estándar (C:\apache-jmeter-*\bin, C:\Program Files\apache-jmeter-*\bin, /opt/apache-jmeter-*/bin) y, como último recurso, performance.tool_path.

Además necesitás, como insumos del proyecto:

Insumo Para qué Dónde va
Colección de API (Postman .json o carpeta Bruno) De ahí salen los endpoints, el login y los flujos performance.collection.path (o se autodetecta)
Environment de la colección (opcional) Valores no sensibles de las variables performance.collection.environment_path (o se autodetecta junto a la colección)
CSV con usuarios/credenciales y datos de prueba Los planes los leen al ejecutar performance.data_dir (por defecto data/)
Secretos (tokens, claves) Se pasan al ejecutar Solo en paths.env_file (por defecto .env.tests) o en variables de entorno del proceso

2. qa-stack.yaml de ejemplo

stack:
  test_framework: jmeter
  language: java
  app_type: api
  pipeline_provider: gitlab

environment:
  base_url: https://api-staging.miapp.com

performance:
  collection:
    path: doc/                  # archivo o carpeta de la colección · null = autodetectar
    format: auto                # auto | postman | bruno
    environment_path: null      # null = autodetectar junto a la colección
  data_dir: data/               # CSV con credenciales/datos de prueba
  scripts_dir: performance/     # donde se generan los planes
  results_dir: target/          # donde se guardan las corridas con JMeter
  profiles: [smoke, load, stress, spike]
  time_scale: 1                 # multiplicador de duraciones (corrida rápida: 0.05)
  cooldown_s: null              # pausa entre perfiles · null = 30 s x time_scale (mín. 1 s)
  mutations:
    include: writes             # none | writes | all
    probe_iterations: 3         # 0 a 5
  tool_path: C:/jmeter/bin/jmeter.bat   # lo escribe el bootstrap · null = PATH / JMETER_HOME
  on_missing: block             # block | warn

paths:
  env_file: .env.tests
  reports_dir: test-results/reports/

Todas las claves de performance tienen valor por defecto. El bloque guarda solo rutas y parámetros no sensibles, nunca credenciales. tool_path se escribe con barras / para evitar escapes en el YAML.

Si en tu qa-stack.yaml no figura results_dir, el runner usa target/ con JMeter (con k6 usaría results/). El bootstrap escribe el default del template (results/) cuando no lo preguntás: si querés target/, definilo a mano.

Otras claves opcionales del bloque, todas con null por defecto: defaults.login_weight, defaults.on_exhaust (skip_writes | recycle | abort | synthesize), defaults.think_seconds y defaults.mix.

Con JMeter, lippia-neo-bootstrap-stack solo te pregunta el framework y el CI (si no los detecta), base_url y el bloque performance. No pregunta autenticación, sistema operativo, versión, historias de usuario, bugs ni herramienta de gestión, y no crea .mcp.json.


3. Cómo se configura (lippia-neo-bootstrap-stack)

Pedile al asistente:

Configurá el proyecto para QA con lippia-neo-bootstrap-stack

La skill detecta JMeter si el repo tiene archivos *.jmx, y fuerza app_type: api y language: java. También busca colecciones (*.postman_collection.json o carpetas Bruno con bruno.json / *.bru) bajo doc/, docs/, collections/, postman/, api/ o la raíz, y te las ofrece. Te pregunta de a una:

Pregunta Clave Opciones
Colección de API performance.collection.path Las candidatas detectadas, otra ruta o null (autodetectar al usarla)
Carpeta de datos performance.data_dir data/ (default) u otra
Carpeta de scripts performance.scripts_dir performance/ (default) u otra
Perfiles performance.profiles Los 4 (default) o un subconjunto
Duración performance.time_scale 1 (default, duración real), 0.05 (corrida corta, solo para comprobar que anda) u otro número
Métodos que modifican datos performance.mutations.include none (solo lecturas), writes (default: POST/PUT/PATCH) o all (incluye DELETE)
Prueba previa de escrituras performance.mutations.probe_iterations 3 repeticiones (default), de 1 a 5, o 0 para no probar

cooldown_s, defaults.* y on_missing se escriben con sus valores por defecto sin preguntar. paths.env_file queda en .env.tests (el archivo no se crea) y se agrega al .gitignore, junto con .claude y performance.results_dir. Al final, el resumen muestra la ruta y versión de JMeter detectadas (o "no encontrado" con el aviso).


4. Credenciales y datos

  • Los secretos no se escriben en ningún plan ni en qa-stack.yaml. Los planes los leen con ${__P(NOMBRE,${__env(NOMBRE)})}: por parámetro o por variable de entorno.
  • Los usuarios y contraseñas de prueba van en CSV dentro de performance.data_dir. NEO solo lee el encabezado, el separador y la cantidad de filas; nunca copia ni muestra los valores. Los planes leen los CSV desde esa carpeta, sin copiarlos.
  • Los demás secretos (token, API key, etc.) van en paths.env_file (por defecto .env.tests, formato NOMBRE=valor, fuera de git) o como variables de entorno del proceso. El runner los pasa a JMeter por el entorno del proceso y los enmascara en la salida.
  • El valor de una variable de autenticación basic se pasa como usuario:clave crudo (el plan lo codifica en base64).
# .env.tests (fuera de git)
API_KEY=<TOKEN>

Autenticaciones que reconoce: bearer, cookie, api_key_header, api_key_query, basic y none. El request de login sale de la colección. Los separadores de CSV auto no se pueden resolver en JMeter: se usa , con un aviso.


5. Qué genera NEO

lippia-neo-read-api-collection lee la colección, prueba el login (un solo intento) y las lecturas, y propone los flujos. Luego lippia-neo-generate-jmeter-script los convierte en planes. El XML lo escribe un renderizador determinista: el mismo input produce siempre el mismo resultado, y los archivos generados no se editan a mano (se regenera). La generación valida la estructura de cada .jmx sin necesitar JMeter; si JMeter no está disponible, la salida lleva no_validado: jmeter no disponible.

performance/                   ← performance.scripts_dir
├── scripts/
│   └── smoke.jmx  load.jmx  stress.jmx  spike.jmx   # un plan por perfil
├── config/
│   └── user.properties        # base_url, time_scale, data_dir y defaults no sensibles (nunca secretos)
├── render-input.json
├── generation-report.json     # avisos, excluidos, decisiones, carga declarada, umbrales, comandos
└── README.md                  # cómo validar y correr, parámetros, límites

Cada plan arranca con un grupo de preparación que verifica los parámetros obligatorios (sin imprimir valores) y luego tiene uno o más Thread Groups por escenario. La etiqueta de cada request es <flujo>/<request>; el login medido es login/<nombre> y la sesión de preparación, setup/<nombre>.

Perfiles por defecto

Perfil Carga por defecto Cómo se arma en JMeter
smoke 1 usuario durante 30 s, un escenario por vez Un Thread Group por flujo con 1 hilo, cada uno en su ventana
load Sube a 10 en 1 min, se mantiene 5 min y baja a 0 en 1 min Hilos con rampa inicial; el resto de los tramos, escalones
stress Escalones de 10, 20, 30 y 40 (2 min cada uno) y baja a 0 Tasa constante por tramo con Constant Throughput Timer
spike 2 → 50 en 15 s, se mantiene 1 min, vuelve a 2 y baja a 0 Tasa constante por tramo con Constant Throughput Timer

El valor de cada tramo es el total entre todos los escenarios, repartido según la mezcla (mix, parejo por defecto). time_scale multiplica las duraciones (mínimo 1 s) y no cambia los planes, solo la corrida.

Qué se incluye y qué queda afuera de la carga

  • Las escrituras (POST/PUT/PATCH) entran según mutations.include; los DELETE solo con all. Un POST que es una consulta de solo lectura se trata como lectura.
  • Quedan fuera (con motivo en generation-report.json y en los avisos): requests destructivos, de otro host, que fallaron en la prueba previa, que dependen de valores capturados que ninguna cadena provee, o escrituras sin cuerpo.
  • Una sesión que no se logra establecer nunca da verde: si el login de preparación falla, la corrida se detiene.

Prueba previa de escrituras

Si mutations.include no es none y probe_iterations es mayor que 0, lippia-neo-read-api-collection repite cada escritura (hasta 5 veces, con su cuerpo) para detectar datos de un solo uso. Esa prueba crea datos reales en el ambiente. Contra un host que no es local solo corre con performance.confirm_remote: true. No prueba el login ni los requests que dependen de valores capturados, y solo envía cuerpos JSON.


6. Cómo lo ejecuta lippia-neo-run-performance-test

El runner (scripts/run-profile.js) corre los perfiles de a uno y en secuencia, nunca en paralelo, con una pausa entre ellos (cooldown_s; si es null, 30 s x time_scale, mínimo 1 s). Antes de lanzar nada valida las variables obligatorias de los planes. Si falta alguna, rechaza la corrida (refused, código 2) sin lanzar JMeter. Si no encuentra JMeter (o no responde jmeter -v, por ejemplo sin Java), también rechaza (refused, código 3), sin preguntar ni descargar nada.

Por cada perfil lanza JMeter en modo no gráfico y deja la corrida en <results_dir>/<perfil>-<UTC yyyymmdd-HHmmss>/:

target/
├── runs.json
└── load-20260105-143000/
    ├── results.jtl
    ├── dashboard/               # dashboard HTML de JMeter (index.html)
    ├── jmeter.log
    ├── load-load-check.json     # resumen convertido del JTL: estados, latencias, umbrales
    ├── console.utf8.txt         # salida, con los valores sensibles enmascarados
    └── run-meta.json

JMeter sale con código 0 aunque haya muestras fallidas. Por eso el runner convierte results.jtl a <perfil>-load-check.json (la misma forma que con k6), evalúa ahí los umbrales y clasifica 99 (umbrales cruzados) si alguno se cruzó. Un exit distinto de 0 de JMeter es error. Los umbrales por defecto (error por request, p95) no están en el plan: se evalúan al convertir el JTL.

Opciones del runner (se toman del input o de qa-stack.yaml; el input gana): profiles, base_url, time_scale, cooldown_s, script_dir, results_dir, reset_command (restablece el estado del sistema antes de cada perfil; si falla, la corrida se detiene), max_duration y confirm_remote. Funcionan igual que con k6 (ver Configurar k6); además jmeter_path indica una ruta explícita al ejecutable. performance.data_dir se pasa a JMeter como ruta absoluta.

Cuidado con stress y spike. Contra un host que no es local solo corren si quien invoca pasa confirm_remote: true. Sin eso, el runner devuelve needs_input y no lanza nada.

Para escribir el informe final (performance-report-<proyecto>-<UTC>.md en paths.reports_dir) está lippia-neo-write-performance-report; ver Skills de performance.


7. Checklist rápido

jmeter -v                     # JMeter 5.x
java -version                 # Java 8 o superior
node --version
ls doc/                       # la colección (o la ruta de performance.collection.path)
ls data/*.csv                 # CSV de usuarios / datos
ls .env.tests                 # secretos, si los planes los piden
grep -n "tool_path" qa-stack.yaml

Si todo responde bien, pedile al asistente que lea la colección, genere los planes y ejecute los perfiles.


8. Problemas comunes (y qué hacer)

Lo que ves Por qué puede pasar Qué hacer
Estado refused con código 3 JMeter no se encontró o no responde a jmeter -v (por ejemplo, falta Java) Instalar JMeter y Java por fuera de NEO, o indicar la ruta con jmeter_path / performance.tool_path
tool_path: null y un aviso tras el bootstrap No se encontró JMeter o Java Instalarlos y volver a ejecutar el bootstrap, o escribir tool_path a mano
Estado refused (código 2), perfiles not_run Falta una variable obligatoria de los planes Definirla en paths.env_file o en el entorno del proceso; el mensaje nombra cuáles faltan
Estado needs_input con confirm_remote en missing Se pidió stress o spike contra un host remoto sin autorización Pasar confirm_remote: true solo si corresponde
Estado needs_input con flows en missing No hay reporte de lectura de la colección ni flujos de entrada Ejecutar primero lippia-neo-read-api-collection
blocked por Node node --version falla Instalar Node.js
Todos los requests dan 4xx con auth basic El valor se pasó ya codificado Pasar usuario:clave crudo
Exit 99 en un perfil Se cruzó algún umbral Es un resultado de la prueba: revisar el load-check.json o el informe
Aviso credential_pools_not_disjoint El login medido y las sesiones comparten usuarios Usar un CSV de credenciales aparte o measure_login: false
El generador devuelve conflict Un archivo en scripts_dir existe y no fue generado por NEO Mover o renombrar ese archivo

9. Limitaciones actuales

Qué Qué pasa con JMeter Alternativa
Jobs de CI (lippia-neo-bootstrap-ci) No genera un job de performance: se detiene con framework_not_supported_by_this_skill Armar el job a mano y ejecutar el runner de lippia-neo-run-performance-test; en CI los secretos van por el entorno
Skills de suite funcional (lippia-neo-generate-test-suite, lippia-neo-run-and-heal) Abortan con framework_not_supported_by_this_skill Usar las skills de performance
Iteraciones JMeter no las mide: iteraciones, iteraciones descartadas, datos reciclados/omitidos y capturas faltantes quedan como n/d en el reporte Interpretar la carga por requests y por tasa de muestras
Rampas Un Thread Group solo rampa de 0 a N: las rampas descendentes y entre valores no nulos son escalones al promedio del tramo, y cada hilo nuevo repite su login Usar k6 si necesitás rampas graduales (JMeter core, sin plugins)
Modelo abierto (stress, spike) La tasa se aproxima con Constant Throughput Timer y un tope de hilos; si el sistema se satura, la tasa lograda baja sin aviso de descartes Contrastar contra la carga lograda en el reporte
Pools de credenciales El login medido y las sesiones por hilo comparten usuarios (no se parte el CSV) CSV de credenciales aparte o measure_login: false
Renovación de sesión Solo por vencimiento (expires_in_seconds), no ante un 401; al renovar puede tomarse otro usuario del pool. No se verifica la cookie de sesión, solo el status del login Definir expires_in_seconds correcto en la autenticación
Selección de escenarios en la corrida No existe FLOWS con JMeter Regenerar con otro mix o una lista menor de flujos
Umbrales checks y dropped_iterations No existen en JMeter y se ignoran con un aviso —
Cuerpos formdata Se envían urlencoded, sin archivos —
Prueba de escrituras Crea datos reales en el ambiente y solo envía cuerpos JSON; no prueba requests que dependen de valores capturados mutations.include: none o probe_iterations: 0
Parser de qa-stack.yaml Lector mínimo: no soporta anclas, multilínea ni listas de mapas Escribir el bloque performance con mapas y listas simples