Saltar a contenido

Pruebas de performance

Estas cinco skills cubren el camino completo de una prueba de carga: leer una colección de API (Postman o Bruno), generar los scripts de carga en k6 o JMeter, ejecutarlos perfil por perfil (smoke, load, stress, spike) y redactar el reporte final con los números de cada corrida. Cada skill hace una sola cosa y se comunica con la siguiente por la forma de sus datos: flujos y autenticación, scripts, carpetas de corrida, reporte.

Modo CI: sin preguntas

Ninguna de estas skills le hace preguntas a la persona que la invoca. Cada valor se resuelve en este orden: input explícito, después el bloque performance de qa-stack.yaml (junto con environment.base_url y paths.*) y, por último, un default documentado. Lo que se resuelve por default queda registrado. Solo lo que es imposible de inferir (por ejemplo, que no haya colección ni flujos) devuelve status: needs_input o blocked, con el detalle en missing. El bloque performance se describe en STACK.md del repositorio de las skills.

Límites que conviene tener presentes

  • La prueba de escrituras crea datos reales. lippia-neo-read-api-collection solo ejecuta lecturas; la excepción es la prueba de escrituras (POST/PUT/PATCH, y DELETE solo con include_mutations: all), que repite cada escritura con su cuerpo para detectar datos de un solo uso. Solo corre si include_mutations no es none, mutation_probe_iterations es mayor que 0 y el probe está habilitado; contra un host que no es local exige además performance.confirm_remote: true.
  • Nada se instala. El runner no instala k6, JMeter ni Java: si no los encuentra, devuelve blocked (k6) o refused (JMeter) y no corre nada.
  • Sin secretos en archivos. Ninguna skill escribe credenciales, tokens ni claves en scripts, reportes, logs o warnings: se enmascaran (********) y los valores llegan por el entorno del proceso o por archivos de datos que las skills nunca leen ni copian.
  • JMeter no mide iteraciones. Con JMeter, las iteraciones y todo lo derivado de ellas figuran como n/d en el reporte (no como 0 ni como una estimación).

lippia-neo-read-api-collection

Cuándo usarla

Cuando hay una colección Postman o Bruno y hace falta entender sus flujos, cómo se autentica (bearer, cookie de sesión, API key, basic o ninguna) y qué requests dependen de esa autenticación, antes de generar cualquier prueba. También para confirmar contra el ambiente cómo responde el login y qué responden los requests de lectura con esa sesión, y para saber qué valores guarda un request para los siguientes de su flujo. Propone flujos de test y escribe un reporte estructurado (api-collection-<nombre>.json). No genera scripts, no corre cargas y no escribe secretos. Prueba el login una sola vez y sin reintentos, para no bloquear la cuenta de prueba.

Ejemplo de invocación
{
  "input": {
    "collection": "collections/projects-api.postman_collection.json",
    "environment": "collections/local.postman_environment.json",
    "base_url": "http://localhost:8105",
    "probe": "yes",
    "include_mutations": "none"
  }
}
Input Tipo Descripción
— Requerido No tiene inputs obligatorios: lo que falta se completa desde qa-stack.yaml o por autodetección.
input.qa_stack_path Opcional Por defecto qa-stack.yaml.
input.collection / input.environment Opcional Colección Postman (.json) o carpeta Bruno (con .bru) y su environment. Si no vienen: performance.collection.* de qa-stack.yaml o autodetección.
input.base_url Opcional Pisa a la URL base del environment y de qa-stack.yaml.
input.probe Opcional yes (default) o no. Con no no se llama a nada.
input.include_mutations Opcional none / writes / all: qué métodos que modifican datos se prueban y entran a la carga. Si no viene: performance.mutations.include, luego writes.
input.mutation_probe_iterations Opcional Entero de 0 a 5: cuántas veces se repite cada escritura. Si no viene: performance.mutations.probe_iterations, luego 3.
input.login_request Opcional Nombre o ruta de un request de la colección; pisa la detección del login.
input.data_files / input.credential_env Opcional CSV con credenciales (de performance.data_dir, por defecto data/) o, si no hay, variables de entorno con las credenciales del probe.
input.output_dir Opcional Carpeta del reporte (si no: performance.scripts_dir, luego paths.reports_dir).

Salida

Campo Descripción
status read (colección leída, aunque no se haya probado) / needs_input (no hay colección, o hay login pero ninguna fuente aporta credenciales; con performance.on_missing: warn esto último queda read con un warning) / blocked (colección ilegible o de formato no soportado, o sin qa-stack.yaml con stack.test_framework k6/jmeter).
collection_name, source_kind, base_url Nombre, origen (postman / bruno) y URL base resuelta.
auth Una sola autenticación por colección: mode (bearer, cookie, api_key_header, api_key_query, basic, none) y sus datos.
login El request de login completo, con el campo de usuario y el de clave identificados (sin valores), o null si no hay.
flows Flujos con sus requests: needs_auth, captures, observed_status, expected_statuses, mutates, read_only_post, destructive, y covers_flows / requires_captures_from por flujo.
probe Si se probó y por qué sí o por qué no.
report_path Ruta del reporte escrito (nunca pisa uno existente: agrega fecha al nombre).
missing / warnings Lo imposible de inferir y los avisos (lo enmascarado, convenciones aplicadas).
Se encadena con

Consume una colección (con su environment y CSV de datos) y entrega el reporte con auth, login y flows: exactamente la forma de datos que esperan las skills que generan scripts de carga.


lippia-neo-generate-k6-script

Cuándo usarla

Cuando hay flujos HTTP ya estructurados (con o sin autenticación) y hace falta convertirlos en scripts de carga k6 ejecutables, uno por perfil (smoke, load, stress, spike), o regenerarlos tras cambiar perfiles, umbrales, mezcla de carga, autenticación, datos o flujos (se vuelve a renderizar: los archivos generados no se editan a mano). El código no lo escribe el agente: un renderizador determinista (mismo input, mismo output) lo genera y calcula la carga declarada. No parsea colecciones, no ejecuta la carga, no instala k6 y no interpreta resultados.

Ejemplo de invocación
{
  "input": {
    "flows_report": "performance/api-collection-projects-api.json",
    "profiles": ["smoke", "load"],
    "include_mutations": "none"
  }
}
Input Tipo Descripción
input.flows Requerido Array no vacío de flujos { name, kind: login \| flow, requires_login, requests }; cada request trae name, method y url (y opcionalmente headers, body, checks, captures, needs_auth, etc.). A lo sumo un flujo kind: login. Se puede reemplazar por input.flows_report.
input.flows_report Opcional Ruta a un JSON { base_url?, auth, login, flows }. Si no hay ni flows ni flows_report, busca el api-collection-*.json con status: read más reciente en performance.scripts_dir (o paths.reports_dir).
input.auth / input.login Opcional Autenticación (mode y sus datos) y request de login con cada campo marcado como user, pass o literal. Sin auth: none.
input.profiles Opcional Subconjunto de smoke, load, stress, spike (si no: performance.profiles, luego los cuatro).
input.profile_overrides, input.thresholds, input.mix, input.journeys, input.executor, input.pacing Opcional Etapas por perfil, umbrales, reparto de carga entre escenarios, flujos de negocio, modelo de carga (vus / arrival_rate / sequential) y pausa entre iteraciones.
input.checks, input.unique_fields, input.on_exhaust Opcional Validaciones por request, campos del body que deben ser únicos y qué hacer cuando se agotan las filas del CSV (skip_writes por defecto, recycle, abort, synthesize).
input.include_mutations / include_destructive / include_probe_failed / include_write_without_body Opcional Qué requests entran a la carga. Por defecto se excluyen los destructivos (DELETE), los que una prueba previa vio fallar y los de un host distinto al del ambiente.
input.data_files, input.variables, input.max_vus, input.base_url, input.output_dir, input.qa_stack_path Opcional CSV de datos (solo se describen sus columnas, nunca se leen los valores), valores no sensibles de placeholders, tope de VUs del modelo abierto, URL base, carpeta de salida y ruta de qa-stack.yaml.

Salida

Campo Descripción
status generated (renderizado y validado) / needs_input (faltan flujos y no hay otra fuente) / blocked (sin Node, input inválido o referencias rotas, conflicto con archivos existentes sin marcador, o un dato imposible de inferir).
files, generation_report Archivos escritos y ruta de generation-report.json (avisos, excluidos, decisiones, carga declarada y comandos).
profiles, flows_count Perfiles generados y escenarios incluidos.
env_vars, required_env Variables de entorno que leen los scripts (solo nombres) y las que no tienen default y hay que pasar para correr.
data_mapping, missing_data Cómo se usa cada columna de los CSV y los datos que algún flujo necesita y nadie aporta.
excluded_requests, request_body_missing Requests que no entraron a la carga (con su motivo) y escrituras sin cuerpo.
declared_load Carga declarada por perfil, calculada por el renderizador. En modelo cerrado es una estimación.
decisions, defaults_applied Decisiones tomadas y de dónde salieron (input, qa-stack o default).
validate_command, run_command Comandos para validar sin generar carga (k6 inspect) y para correr un perfil.
warnings Avisos del renderizador y de la skill. Si k6 no está disponible, el aviso no_validado: k6 no disponible va primero.

Reglas de seguridad de los scripts generados

Los headers de auth, campos de nombre sensible y URLs con credenciales se reemplazan por placeholders que se resuelven contra el entorno, sin valor por defecto. Una sesión que no se establece nunca da verde: con bearer o cookie, un login de preparación fallido aborta la corrida.

Se encadena con

Consume flujos, autenticación y login con la forma { base_url?, auth, login, flows }, y entrega la carpeta de scripts (<perfil>.js) junto con generation-report.json, que usan la ejecución y el reporte para conocer la carga declarada y las variables obligatorias.


lippia-neo-generate-jmeter-script

Cuándo usarla

Lo mismo que la skill de k6, pero para JMeter: cuando hay flujos HTTP estructurados y hace falta convertirlos en planes de carga .jmx ejecutables, uno por perfil, o regenerarlos tras un cambio. El XML lo escribe un renderizador determinista. Valida cada .jmx con un chequeo estructural propio y, solo si JMeter está disponible, con JMeter. No parsea colecciones, no ejecuta la carga, no instala JMeter y no interpreta resultados.

Ejemplo de invocación
{
  "input": {
    "flows_report": "performance/api-collection-projects-api.json",
    "profiles": ["smoke", "load"]
  }
}
Input Tipo Descripción
input.flows Requerido Igual que en k6: array no vacío de flujos con sus requests (se puede reemplazar por input.flows_report).
input.flows_report, input.auth, input.login, input.profiles, input.profile_overrides, input.mix, input.journeys, input.executor, input.checks, input.unique_fields, input.on_exhaust, input.pacing, input.data_files, input.variables, input.max_vus, input.base_url, input.output_dir, input.qa_stack_path Opcional Mismo significado y misma precedencia (input, qa-stack.yaml, default) que en la skill de k6.
input.include_mutations / include_destructive / include_probe_failed / include_write_without_body Opcional Igual que en k6.
input.thresholds Opcional Umbrales (http_req_failed, http_req_duration, throttled, server_errors, conflicts). checks y dropped_iterations no existen en JMeter y se ignoran con un warning. Los umbrales no son assertions del plan: se escriben en generation-report.json y se evalúan sobre los resultados.

Salida

Igual que en k6 (status, files, generation_report, declared_load, data_mapping, excluded_requests, decisions, validate_command, run_command, warnings), con estas diferencias:

Campo Descripción
tool Siempre jmeter.
declared_load basis es siempre estimate: con JMeter core ni el modelo abierto es exacto.
validation { structural: ok \| failed \| not_run, jmeter: ok \| failed \| not_available }. El chequeo estructural es obligatorio; el de JMeter, solo si está disponible.
status blocked también si falla el chequeo estructural.

Límites propios de JMeter

JMeter no parte el CSV de credenciales en grupos de usuarios separados: si hay login medido y flujos con sesión sobre el mismo CSV, se informa credential_pools_not_disjoint y la decisión queda en manos de quien invoca. Los umbrales no se calculan dentro del plan sino sobre los resultados.

Se encadena con

Mismo contrato de entrada que la skill de k6; entrega la carpeta de planes (scripts/<perfil>.jmx, user.properties, README) y generation-report.json.


lippia-neo-run-performance-test

Cuándo usarla

Cuando hay un directorio con scripts k6 (<perfil>.js) o JMeter (scripts/<perfil>.jmx) por perfil y hace falta ejecutarlos contra un ambiente dejando evidencia reproducible de cada corrida, o repetir una corrida (por ejemplo con otra time_scale) o correr varios perfiles de a uno reiniciando el estado del sistema bajo prueba antes de cada uno. Los perfiles corren siempre de a uno y en secuencia, con una pausa entre ellos. No modifica scripts ni datos, no interpreta resultados, no instala k6 ni JMeter y no ejecuta nada fuera de la herramienta y del reset_command indicado.

Ejemplo de invocación
{
  "input": {
    "tool": "k6",
    "profiles": ["smoke", "load"],
    "base_url": "http://localhost:8105",
    "env_var_names": ["LOGIN_USER", "LOGIN_PASSWORD"],
    "time_scale": 0.1
  }
}
Input Tipo Descripción
— Requerido No tiene inputs obligatorios: lo que falta se completa desde qa-stack.yaml.
input.tool Opcional k6 o jmeter. Por defecto jmeter si stack.test_framework es jmeter; si no, k6.
input.jmeter_path Opcional Ruta explícita al ejecutable de JMeter (sin ella: PATH, JMETER_HOME, rutas estándar y performance.tool_path).
input.project_dir, input.script_dir, input.results_dir Opcional Carpeta del proyecto, de los scripts (performance.scripts_dir) y de las corridas (performance.results_dir; por defecto results en k6 y target en JMeter).
input.profiles Opcional smoke, load, stress, spike (por defecto performance.profiles).
input.base_url Opcional URL base del ambiente (por defecto environment.base_url). Solo se informa su host.
input.env_var_names, input.env_file, input.required_env Opcional NOMBRES de las variables a inyectar (el valor sale del entorno del proceso o de un archivo fuera del repo) y variables obligatorias del script.
input.time_scale, input.cooldown_s, input.max_duration Opcional Escala de duraciones, pausa entre perfiles y tope de duración por perfil.
input.reset_command / input.reset_args Opcional Comando que restablece el estado del sistema bajo prueba; corre antes de cada perfil.
input.on_concurrent Opcional warn (default) o abort si ya hay otros procesos de la herramienta en la máquina.
input.confirm_remote Opcional Autorización explícita para correr stress o spike contra un host no local.
input.run_id Opcional Prefijo del identificador de cada corrida.

Salida

Campo Descripción
status completed (se intentaron todos los perfiles, aunque alguno termine con umbrales cruzados) / partial (se detuvo antes: falló el reset_command o hay procesos concurrentes con on_concurrent: abort) / refused (faltan variables obligatorias o JMeter no se encontró; no se gastó ninguna corrida) / needs_input (falta una entrada o la confirmación para un host remoto) / blocked (sin Node o k6 no instalado o con versión anterior a 0.49).
tool, tool_version Herramienta usada y su versión.
runs Por perfil: run_dir, exit_code, exit_meaning (ok, thresholds_crossed, aborted, error, skipped, not_run), timed_out, horarios y qué archivos quedaron.
missing / warnings Lo imposible de inferir y los avisos (procesos concurrentes, archivos esperados que faltan, corrida escalada).

Cada corrida queda en <results_dir>/<perfil>-<UTC yyyymmdd-HHmmss>/ con <perfil>-load-check.json, console.utf8.txt, run-meta.json y, según la herramienta, summary.json y dashboard.html (k6) o results.jtl y dashboard/ (JMeter). En JMeter el load-check se convierte del JTL.

Autorización para hosts remotos

Si el host de base_url no es local y entre los perfiles hay stress o spike, solo corre con confirm_remote: true en el input. Sin él devuelve needs_input con missing: ["confirm_remote"] y no lanza nada. Un código de salida 99 (umbrales cruzados) o 108 (abortada) es un dato de la corrida: se reporta, no se reintenta ni se maquilla.

Se encadena con

Consume una carpeta de scripts por perfil (con su generation-report.json, de donde saca las variables obligatorias) y entrega carpetas de corrida con la evidencia cruda (run-meta.json, <perfil>-load-check.json, resultados de la herramienta) más runs.json en results_dir.


lippia-neo-write-performance-report

Cuándo usarla

Cuando existen una o más carpetas de corrida y hace falta un informe final legible por un PO o un dev lead; cuando hay corridas de varios perfiles y se quiere una tabla comparativa de carga ofrecida contra latencia para detectar inflexión; o cuando una corrida terminó con umbrales cruzados (99), abortada (108) o sin ejecutar iteraciones y hay que explicarla con sus causas medibles. Un script determinista extrae solo hechos a report-data.json y el reporte se redacta únicamente con esos números. No ejecuta pruebas, no modifica scripts ni resultados y no inventa métricas. El reporte es igual con k6 o con JMeter.

Ejemplo de invocación
{
  "input": {
    "project": "projects-api",
    "environment": { "simulated": false, "notes": "ambiente de QA compartido" },
    "format": "md"
  }
}
Input Tipo Descripción
— Requerido No tiene inputs obligatorios: lo que falta se completa desde qa-stack.yaml.
input.run_dirs Opcional Array de carpetas de corrida. Si no viene: todas las corridas de la última invocación en performance.results_dir.
input.generation_report Opcional Ruta o objeto con la carga declarada (sin escalar). Por defecto <performance.scripts_dir>/generation-report.json; si falta declared_load, se declara como dato faltante.
input.environment Opcional { simulated, notes }, declarado por quien pide la prueba (por ejemplo, que el servicio bajo prueba es un simulador). La skill nunca lo deduce: sin dato queda como entrada faltante.
input.project Opcional Nombre del proyecto para el nombre del archivo (por defecto, la carpeta de qa-stack.yaml).
input.reports_dir Opcional Carpeta de salida (por defecto paths.reports_dir, luego test-results/reports/).
input.format Opcional md (default) o md+html.
input.qa_stack_path Opcional Por defecto qa-stack.yaml.

Salida

Campo Descripción
report_path, report_data_path El reporte .md y su archivo de datos, con nombre único por ejecución (nunca pisa uno existente).
overall_status conclusive / conclusive_with_limits (hay limitaciones que no bloquean: entorno simulado, generador en el mismo host, corrida escalada, corrida única) / non_conclusive (por ejemplo corrida abortada sin carga, sesión no establecida, requests que devuelven siempre 4xx, generador saturado o limitación de tasa que invalida la carga ofrecida) / blocked (sin Node, ruta inexistente o ninguna corrida con datos).
runs, flags Corridas con su código de salida y los flags presentes.
bottleneck_declared true solo si hay evidencia citada; si no, el reporte dice "no se alcanzó el punto de saturación".
missing_inputs, missing, warnings Entradas faltantes, lo imposible de inferir (por ejemplo, ninguna corrida) y avisos (incluido lo enmascarado).

Cómo se redacta

Todo número sale del archivo de datos, con su valor y unidad; un dato ausente se escribe "sin dato". El 429 es control de tasa y el 409 un conflicto de estado: ninguno se presenta como falla del sistema ni como saturación. Un problema del generador de carga nunca se atribuye al sistema bajo prueba, y un exit 99 o 108 nunca se maquilla. Con JMeter, las iteraciones y la carga ofrecida figuran como n/d y la carga se describe por requests por segundo servidos.

Se encadena con

Consume carpetas de corrida (resultados de la herramienta, <perfil>-load-check.json y run-meta.json) y, opcionalmente, el generation-report.json con la carga declarada; entrega el reporte final y su archivo de datos en reports_dir.