k6-script-creation

k6-script-creation 是做什么的？

Genera pruebas de rendimiento con k6 que cualquier persona del equipo pueda ejecutar, entender y corregir, aunque no sepa k6. Para ello, cada script sigue una misma estructura, con nombres que indican qué es, credenciales fuera del código y un .md que lo explica paso a paso.

Prioridades del equipo: carga y estrés, tanto HTTP como k6 browser. El smoke es siempre el paso previo obligatorio.

Fuente de verdad: la documentación oficial

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

Archivos de referencia (lee 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, autenticación, 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-) + nombre descriptivo del flujo de negocio (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 documentación en español; identificadores de código en inglés.

Si el proyecto ya tiene una carpeta k6/, reutiliza config.js, flows y page objects existentes en lugar de duplicarlos, y respeta lo que ya exista.

Flujo de trabajo

1. Entender la solicitud

Extrae de lo que dijo el usuario:

• Tipo de prueba: carga, estrés u otro. Si dice "ver cuánto aguanta" o "llevarlo al límite", es estrés (o breakpoint si quiere el punto de quiebre exacto). Si dice "carga normal" o "un día típico", es carga.
• 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.

Pregunta 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, estrés = 2× la carga de carga) y cada supuesto queda escrito en la sección "Supuestos" del .md. Si el usuario no conoce sus números de carga, díselo: sin ellos, el test responde una pregunta distinta a la que le interesa.

2. Preparar la estructura

Crea 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 agrega 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). Contiene las solicitudes, checks, grupos numerados, tags name y think time. Si el flujo necesita login, exporta 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. Lee references/browser-patterns.md.
• Genera siempre también smoke-<flujo>.js si no existe. Es barato (reutiliza el flujo) y es el primer paso obligatorio antes de carga o estrés.
• Si piden estrés y no existe la prueba de carga del mismo flujo, genera ambos: la documentación oficial dice que el estrés se ejecuta después de la prueba de carga 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 valores por defecto de __ENV ni en console.log.
• La URL y el entorno, vía -e BASE_URL y -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 asíncronos, page.waitForTimeout() en lugar de sleep().
• Cada request con tag name estable ('GET /items/:id'), para que las URLs con IDs no disparen 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: explica cada término la primera vez (VU, iteración, p95, threshold), explica el por qué de cada número y usa los valores reales del script. Incluye el diagrama ASCII del perfil de carga, la tabla de checks y thresholds "en palabras", los comandos exactos para ejecutarlo (smoke primero) y los errores comunes. Luego, agrega el script al índice de k6/README.md.

5. Validar

• Ejecuta 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, dilo y deja el comando para que lo ejecuten.
• 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 carga, estrés, 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 ejecutar el smoke y luego la prueba solicitada.
• 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 la solicitud sea entender, corregir o mejorar un script:

1. Léelo completo y contrastalo con el estándar y con la documentación oficial (APIs antiguas, 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. Explica los problemas en lenguaje simple, ordenados por gravedad, y propón el cambio.
3. Al corregirlo, actualiza (o crea) su .md para que la documentación siga coincidiendo con el código.
4. Si el nombre no sigue el estándar, sugiere el renombre, pero no lo hagas sin confirmación, porque puede romper pipelines que lo invoquen.