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-collectionsolo ejecuta lecturas; la excepción es la prueba de escrituras (POST/PUT/PATCH, y DELETE solo coninclude_mutations: all), que repite cada escritura con su cuerpo para detectar datos de un solo uso. Solo corre siinclude_mutationsno esnone,mutation_probe_iterationses mayor que 0 y el probe está habilitado; contra un host que no es local exige ademásperformance.confirm_remote: true. - Nada se instala. El runner no instala k6, JMeter ni Java: si no los encuentra, devuelve
blocked(k6) orefused(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/den 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.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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.