Saltar a contenido

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

NEO no instala k6. Si el runner no lo encuentra, se detiene con estado blocked y te avisa que hay que instalarlo por fuera. Lo busca en el PATH y, en Windows, en C:\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-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 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. NEO solo 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, formato NOMBRE=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 basic se pasa como usuario:clave crudo (el script lo codifica). Si lo pasás ya como Basic <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 con all. 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.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.
  • Cuando las filas del CSV se agotan en requests que escriben, el default (skip_writes) omite esas escrituras; recycle reutiliza filas, abort corta 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 stress y spike. Contra un host que no es local (localhost, 127.0.0.1, ::1) 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 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