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 |
NEOno instala JMeter ni Java. Durante el bootstrap, la skill busca el ejecutable sin preguntarte y guarda su ruta enperformance.tool_path. Si no lo encuentra, o falta Java, dejatool_path: nully te avisa qué falta; no se detiene ni instala nada.
Dónde busca el ejecutable:
- El bootstrap:
jmeteren elPATH,JMETER_HOME/biny las carpetasapache-jmeter-*/jmeter*enC:\,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 conjmeter -vyjava -version. - El runner, en este orden: la ruta indicada como input (
jmeter_path), elPATH,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.yamlno figuraresults_dir, el runner usatarget/con JMeter (con k6 usaríaresults/). El bootstrap escribe el default del template (results/) cuando no lo preguntás: si queréstarget/, 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-stacksolo te pregunta el framework y el CI (si no los detecta),base_urly el bloqueperformance. 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.NEOsolo 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, formatoNOMBRE=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
basicse pasa comousuario:clavecrudo (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 conall. Un POST que es una consulta de solo lectura se trata como lectura. - Quedan fuera (con motivo en
generation-report.jsony 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
stressyspike. Contra un host que no es local solo corren si quien invoca pasaconfirm_remote: true. Sin eso, el runner devuelveneeds_inputy 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 |