k6-script-creation

¿Qué hace k6-script-creation?

Esta skill genera pruebas de performance con k6 que cualquier persona del equipo pueda correr, entender y corregir, aunque no sepa k6. Para eso, cada script sale con la misma estructura, con nombres que dicen qué es, con credenciales fuera del código y con un .md que lo explica parte por parte.

Prioridades del equipo: load y stress, tanto HTTP como k6 browser. El smoke es siempre el paso previo.

Fuente de verdad: la doc oficial

Todo lo que se escriba tiene que coincidir con https://grafana.com/docs/k6/latest/ (k6 v2.x). Las referencias de esta skill resumen esa doc. Si algo no está cubierto, o tenés la mínima duda sobre una API, una opción o una métrica, consultá la página oficial (mapa en references/official-docs.md) en vez de confiar en la memoria. Muchos ejemplos de internet usan APIs viejas (k6/experimental/browser, browser sincrónico, browser_web_vital_fid) que en v2 ya no funcionan.

Archivos de referencia (leé solo lo que necesites)

Archivo	Cuándo leerlo
references/test-types.md	Siempre: elegir tipo de prueba, perfil de stages y executor
references/thresholds-checks.md	Siempre: thresholds estándar y cómo escribir checks
references/http-patterns.md	Tests de API: ciclo de vida, auth, secretos, correlación, datos
references/browser-patterns.md	Tests con k6 browser o híbridos
references/doc-template.md	Al escribir el .md explicativo
references/official-docs.md	Para buscar la página oficial de un tema
assets/lib/config.js	Copiar tal cual a k6/lib/config.js
assets/templates/*	Base para flows, tests, README, .secrets.example

Estándar de estructura en el proyecto

k6/
├── tests/
│   ├── api/        <tipo>-<flujo>.js            ej. load-checkout.js, stress-search-products.js
│   └── browser/    <tipo>-<flujo>-browser.js    ej. load-login-browser.js
├── lib/
│   ├── config.js   (copiado de assets/lib/config.js)
│   ├── flows/      <flujo>.js — los pasos del usuario, reutilizados por todos los tipos
│   └── pages/      <pagina>-page.js — page objects (solo browser, si el flujo tiene varias páginas)
├── data/           datos de prueba JSON/CSV (nunca credenciales)
├── docs/           <mismo-nombre-que-el-script>.md
├── .secrets.example
└── README.md       (de assets/templates/k6-README.md, con el índice de scripts)

Nombres: kebab-case, prefijo de tipo (smoke-, load-, stress-, spike-, soak-, breakpoint-) + flujo de negocio descriptivo (checkout, search-products, no test1 ni api). Los de browser llevan sufijo -browser. El .md tiene exactamente el mismo nombre que el script.

Idioma: comentarios y docs en español; identificadores de código en inglés.

Si el proyecto ya tiene una carpeta k6/, reutilizá config.js, flows y page objects existentes en vez de duplicarlos, y respetá lo que ya esté.

Flujo de trabajo

1. Entender el pedido

Extraé de lo que dijo el usuario:

• Tipo de prueba: load, stress u otro. Si dice "ver cuánto aguanta" o "llevarlo al límite", es stress (o breakpoint si quiere el punto de quiebre exacto). Si dice "carga normal" o "un día típico", es load.
• API, browser o híbrido.
• Endpoints o pantallas y orden del flujo, cómo se autentica y qué valida cada paso.
• Carga (usuarios concurrentes o req/s), duración y SLA (ej. p95 < 500 ms).
• Entorno objetivo.

Preguntá solo lo que bloquea y no se puede suponer razonablemente: la URL o los endpoints si no los dio, y siempre si el objetivo es producción cuando no está claro. Lo demás se supone con los valores por defecto de las referencias (SLA 500 ms, think time 1–3 s, stress = 2× la carga de load) y cada supuesto queda escrito en la sección "Supuestos" del .md. Si el usuario no conoce sus números de carga, decíselo: sin ellos, el test responde una pregunta distinta a la que le interesa.

2. Preparar la estructura

Creá lo que falte de k6/: lib/config.js (copia exacta de assets/lib/config.js), .secrets.example con las claves que use el script, README.md desde la plantilla, y agregá al .gitignore del proyecto:

k6/.secrets
k6/screenshots/

3. Escribir el flujo y los tests

• Flujo en k6/lib/flows/<flujo>.js (base: assets/templates/flow-api.js). Tiene los requests, checks, groups numerados, tags name y think time. Si el flujo necesita login, exportá una función login() que se llama desde setup().
• Test en k6/tests/api/<tipo>-<flujo>.js (base: assets/templates/test-api.js). Solo define options (escenario + thresholds), setup() y default(), que llama al flujo. Los stages y thresholds van explícitos en el archivo, con un comentario por línea.
• Browser en k6/tests/browser/<tipo>-<flujo>-browser.js (base: assets/templates/test-browser.js). Por defecto, híbrido: carga HTTP más pocos VUs de browser. Leé references/browser-patterns.md.
• Generá siempre también smoke-<flujo>.js si no existe. Es barato (reutiliza el flujo) y es el primer paso obligatorio antes de load o stress.
• Si piden stress y no existe el load del mismo flujo, generá ambos: la doc oficial dice que el stress se corre después del load y reutiliza su script.

Reglas que no se negocian, porque protegen al equipo y a los sistemas:

• Credenciales, tokens y API keys solo vía k6/secrets (await secrets.get('NOMBRE')) con --secret-source=file=k6/.secrets. Nunca en el código, en data/, en defaults de __ENV ni en console.log.
• La URL y el entorno, vía -e BASE_URL / -e TARGET_ENV leídos desde lib/config.js. Nunca hardcodeados.
• No quites ni debilites la protección de producción de config.js.
• Imports de jslib con versión exacta (ver official-docs.md).
• Browser: k6/browser, funciones async, options.browser.type: 'chromium' en el escenario, page.close() en finally, check de k6-utils para checks async, page.waitForTimeout() en vez de sleep().
• Cada request con tag name estable ('GET /items/:id'), para que las URLs con IDs no exploten la cantidad de métricas.

4. Escribir el .md explicativo

Uno por script en k6/docs/<nombre>.md, siguiendo todas las secciones de references/doc-template.md. Quien lo lea no es experto: explicá cada término la primera vez (VU, iteración, p95, threshold), explicá el por qué de cada número y usá los valores reales del script. Incluí el diagrama ASCII del perfil de carga, la tabla de checks y thresholds "en palabras", los comandos exactos para correrlo (smoke primero) y los errores comunes. Después, agregá el script al índice de k6/README.md.

5. Validar

• Corré k6 inspect -e BASE_URL=https://example.test -e TARGET_ENV=staging <script> sobre cada script nuevo. Detecta errores de sintaxis, imports rotos y opciones inválidas sin generar carga. Si k6 no está instalado, decilo y dejá el comando para que lo corran.
• Una ejecución real solo con permiso explícito del usuario y como smoke (pocos VUs y pocos segundos) contra un entorno que no sea producción. Nunca lances load, stress, spike, soak ni breakpoint por tu cuenta: generan carga real sobre sistemas compartidos.

6. Responder

Respuesta corta:

• Lista de archivos creados o modificados.
• El comando para correr el smoke y después la prueba pedida.
• Supuestos principales (los mismos que en el .md).
• Qué validaste y qué no (por ejemplo, "pasa k6 inspect; no se ejecutó contra la API").

Revisar o corregir un script existente

Cuando el pedido es entender, corregir o mejorar un script:

1. Leelo completo y contrastalo con el estándar y con la doc oficial (APIs viejas, browser sin await, falta de page.close, credenciales en el código, sin thresholds, sin tags name, sin think time, perfiles tipo "montaña rusa").
2. Explicá los problemas en lenguaje simple, ordenados por gravedad, y proponé el cambio.
3. Al corregirlo, actualizá (o creá) su .md para que la documentación siga coincidiendo con el código.
4. Si el nombre no sigue el estándar, sugerí el renombre, pero no lo hagas sin confirmación, porque puede romper pipelines que lo invocan.