Configurar k6
Estado del adapter: ✅ Completo (performance). k6 es un valor válido de stack.test_framework: lippia-neo-bootstrap-stack lo detecta 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: k6 |
| Lenguaje | javascript (se fuerza) |
| Tipo de app | api (se fuerza) |
| Qué usa | k6 + 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 results/) |
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 |
|---|---|---|---|
| k6 | 0.49 o superior | Ejecutar los scripts de carga | k6 version |
| Node.js | Una versión vigente | Correr el generador y el runner de NEO (scripts .js) |
node --version |
NEOno instala k6. Si el runner no lo encuentra, se detiene con estadoblockedy te avisa que hay que instalarlo por fuera. Lo busca en elPATHy, en Windows, enC:\Program Files\k6\k6.exe.
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 scripts 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: k6
language: javascript
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 scripts
results_dir: results/ # donde se guardan las corridas
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
on_missing: block # block | warn
paths:
env_file: .env.tests
reports_dir: test-results/reports/
Todas las claves de performance tienen valor por defecto: lo que falte usa el que figura arriba. El bloque guarda solo rutas y parámetros no sensibles, nunca credenciales.
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 k6,
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 k6 si el repo tiene scripts que importan 'k6', k6 en package.json o performance/*.js, y fuerza app_type: api y language: javascript. 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 |
results_dir, cooldown_s, defaults.* y on_missing se escriben con sus valores por defecto sin preguntar; los podés editar a mano. paths.env_file queda en .env.tests (el archivo no se crea) y se agrega al .gitignore, junto con .claude y performance.results_dir.
4. Credenciales y datos
- Los secretos no se escriben en ningún script ni en
qa-stack.yaml. Los scripts los leen del entorno (__ENV). - 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 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. En CI llegan por el entorno del pipeline. - El valor de una variable de autenticación
basicse pasa comousuario:clavecrudo (el script lo codifica). Si lo pasás ya comoBasic <base64>, se codifica dos veces y todos los requests dan 4xx.
# .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.
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-k6-script los convierte en scripts. El código lo escribe un renderizador determinista: el mismo input produce siempre el mismo resultado, y los archivos generados no se editan a mano (se regenera).
performance/ ← performance.scripts_dir
├── lib/
│ ├── config.js # perfiles, modelo de carga, umbrales
│ ├── checks.js # estados esperados y métricas por estado
│ ├── auth.js # autenticación (si hay flujos con sesión o login medido)
│ └── data.js # lectura de CSV y pools (si hay CSV o login)
├── scenarios/
│ └── <escenario>.js # un archivo por flujo
├── smoke.js load.js stress.js spike.js # un script por perfil
├── render-input.json
├── generation-report.json # avisos, excluidos, decisiones, carga declarada, comandos
└── README.md # cómo validar y correr, variables, límites
Perfiles por defecto
| Perfil | Carga por defecto | Modelo |
|---|---|---|
smoke |
1 usuario virtual durante 30 s, un escenario por vez | Secuencial |
load |
Sube a 10 en 1 min, se mantiene 5 min y baja a 0 en 1 min | Cerrado (vus) |
stress |
Escalones de 10, 20, 30 y 40 (2 min cada uno) y baja a 0 | Abierto (arrival_rate) |
spike |
2 → 50 en 15 s, se mantiene 1 min, vuelve a 2 y baja a 0 | Abierto (arrival_rate) |
El valor de cada tramo es el total entre todos los escenarios, repartido según la mezcla (mix, parejo por defecto). time_scale multiplica todas las duraciones (mínimo 1 s por tramo) y no cambia los scripts, 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 (por ejemplo, una búsqueda) 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. - Cuando las filas del CSV se agotan en requests que escriben, el default (
skip_writes) omite esas escrituras;recyclereutiliza filas,abortcorta la corrida. - Una sesión que no se logra establecer nunca da verde: si el login de preparación falla, la corrida se aborta.
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 que existan las variables obligatorias de los scripts. Si falta alguna, rechaza la corrida (refused, código 2) sin lanzar k6.
Cada corrida queda en <results_dir>/<perfil>-<UTC yyyymmdd-HHmmss>/:
results/
├── runs.json
└── load-20260105-143000/
├── summary.json
├── load-load-check.json # resumen con carga declarada vs lograda, estados y latencias
├── console.utf8.txt # salida de k6, con los valores sensibles enmascarados
├── dashboard.html # no se genera en corridas muy cortas
└── run-meta.json
El exit code de k6 se clasifica así: 0 ok, 99 umbrales cruzados, 108 abortado, cualquier otro error. Un 99 o un 108 es un dato de la corrida: se reporta, no se reintenta.
Opciones del runner (se toman del input o de qa-stack.yaml; el input gana):
| Opción | Por defecto | Para qué |
|---|---|---|
profiles |
performance.profiles |
Qué perfiles correr |
base_url |
environment.base_url |
URL del ambiente bajo prueba |
time_scale |
performance.time_scale o 1 |
Escala de duraciones |
cooldown_s |
performance.cooldown_s |
Pausa entre perfiles |
script_dir / results_dir |
performance.scripts_dir / performance.results_dir |
Carpetas de scripts y de resultados |
reset_command |
ninguno | Comando que restablece el estado del sistema; corre antes de cada perfil (si falla, la corrida se detiene) |
max_duration |
sin tope | Tope por perfil (ej. 30m); si se excede, se corta y queda como error |
confirm_remote |
false |
Autorización explícita para correr stress o spike contra un host no local |
Cuidado con
stressyspike. Contra un host que no es local (localhost,127.0.0.1,::1) solo corren si quien invoca pasaconfirm_remote: true. Sin eso, el runner devuelveneeds_inputy no lanza nada.
Para escribir el informe final con las corridas (performance-report-<proyecto>-<UTC>.md en paths.reports_dir) está lippia-neo-write-performance-report; ver Skills de performance.
7. Checklist rápido
k6 version # 0.49 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 scripts los piden
grep -n "performance:" qa-stack.yaml
Si todo responde bien, pedile al asistente que lea la colección, genere los scripts y ejecute los perfiles.
8. Problemas comunes (y qué hacer)
| Lo que ves | Por qué puede pasar | Qué hacer |
|---|---|---|
Estado blocked por k6 |
k6 no está instalado o su versión es anterior a 0.49 | Instalar o actualizar k6 por fuera de NEO |
Estado refused (código 2), perfiles not_run |
Falta una variable obligatoria de los scripts | 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 en base64 | 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 de procesos k6 concurrentes | Hay otros k6 corriendo en la máquina | Detenerlos; invalidan la medición |
El generador devuelve conflict |
Un archivo en scripts_dir existe y no fue generado por NEO |
Mover o renombrar ese archivo |
Aviso de maxVUs insuficiente |
Pocos usuarios en el CSV para el pico del perfil | Agregar usuarios, bajar el pico, aceptar los descartes o fijar max_vus |
9. Limitaciones actuales
| Qué | Qué pasa con k6 | 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 |
| 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 para trabajar solo con lecturas, o probe_iterations: 0 |
| Ambientes remotos | stress y spike exigen confirm_remote |
Correr contra un ambiente local o autorizarlo explícitamente |
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 |
| Scripts generados | No se editan a mano | Cambiar el input o qa-stack.yaml y regenerar |