New Project Bootstrap
Esta guía está pensada para entender qué hace el asistente de IA cuando ejecuta este playbook. La idea es que puedas leerla, entender qué pasa en cada paso, y saber qué información tenés que darle al asistente para que el trabajo salga bien.
En resumen
- Para qué sirve: dejar un proyecto nuevo listo para hacer QA automatizado, sin que nadie tenga que configurar nada a mano.
- Cuándo usarlo: cuando el proyecto todavía no tiene
qa-stack.yaml(proyecto nuevo, o uno viejo que se quiere empezar a automatizar). - Qué necesitás: acceso al repositorio, la URL de la app (con versión y sistema operativo del ambiente) y una historia de usuario chica de referencia.
- Qué te llevás: la "ficha técnica" del proyecto (
qa-stack.yaml), el pipeline de pruebas armado y una primera prueba piloto ejecutada de punta a punta, con su reporte. - Pasos: 3 — averiguar con qué está armado el proyecto, armar el pipeline y ejecutar una prueba piloto.
¿Qué es un playbook? (si es la primera vez que usás uno)
Pensalo como una receta de cocina para el asistente de IA. Vos le decís "quiero hacer esto" (por ejemplo, "quiero preparar un proyecto nuevo para hacer QA") y el playbook es la receta que el asistente sigue paso a paso, en orden, sin saltarse nada, para que el resultado sea siempre el mismo sin importar quién lo pida.
Cada paso de la receta usa una herramienta puntual (en la jerga técnica se las llama "skills"), algo así como un utensilio de cocina: uno sirve para pelar, otro para cortar, otro para hornear. Vos no necesitás saber cómo funciona cada utensilio por dentro — solo necesitás saber qué ingrediente hay que poner en cada paso (por ejemplo, la URL de la aplicación, o el nombre de una historia de usuario) para que el plato final salga bien.
Un playbook = una guía ordenada de pasos. Una skill = la herramienta puntual que ejecuta cada paso. Interactuás con el playbook — el asistente se encarga de usar la herramienta correcta en cada momento.
1. ¿Qué hace este playbook?
Es el punto de partida para dejar un proyecto nuevo listo para hacer QA automatizado, sin que nadie tenga que configurar nada a mano.
Hoy, cuando llega un proyecto nuevo (una app, un sitio web, una API), alguien tiene que:
- Averiguar con qué herramientas está armado ese proyecto.
- Generar o impactar cambios en los tests para que estos se ejecuten automáticamente cada vez que se sube código nuevo.
- Comprobar que todo eso realmente funciona, ejecutando una primera prueba.
Ese trabajo, hecho a mano, puede tardar horas o días y depende de tener a alguien técnico disponible. Este playbook hace esas tres cosas de forma automática, conversando con vos para lo que no puede averiguar solo (por ejemplo, la URL del ambiente de pruebas).
Al terminar, el proyecto queda con:
- Una "ficha técnica" guardada que describe cómo está armado (para no tener que volver a preguntar).
- Una configuración de pasos (pipeline) que ejecuta las pruebas solo cada vez que alguien sube cambios.
- Una primera prueba real ejecutada de punta a punta, que confirma que todo el circuito funciona.
2. ¿Cuándo tengo que usar este playbook?
Usalo cuando estés frente a alguna de estas situaciones:
| Situación | Ejemplo de negocio |
|---|---|
| Un proyecto totalmente nuevo, que nunca tuvo QA automatizado | El equipo acaba de arrancar el desarrollo de una tienda online nueva y todavía no hay ni una sola prueba automática en ejecución. |
| Un proyecto viejo que se quiere "poner al día" | Existe desde hace 2 años una app de turnos médicos, pero las pruebas siempre se hicieron a mano y se quiere empezar a automatizar. |
| Se quiere arrancar de cero con todo el combo (archivo con el stack tecnológico del repositorio + pipeline preparado para ejecutar las pruebas CI + primera prueba tomando de referencia Jira, Confluence, Azure DevOps o historias de usuario) | Se decide estandarizar cómo se hace QA en todos los proyectos nuevos de la empresa. |
Importante
Si el proyecto ya tiene un archivo con el stack tecnológico del repositorio (el archivo qa-stack.yaml) y un pipeline preparado para ejecutar las pruebas funcionando, NO es necesario ejecutar este playbook — para el trabajo del día a día (probar una nueva funcionalidad, un bug, un cambio de UI) existen otros playbooks más específicos, como Feature New End to End o Frontend UI Change PR.
3. Ejemplo guía: "TechStore", una tienda online con carrito de compras
Vamos a seguir un caso de negocio de ejemplo: TechStore, una tienda online de electrónica con carrito de compras (agregar productos, ver el carrito, pagar). Es el mismo tipo de aplicación que cualquiera reconoce por haber comprado alguna vez online.
Supongamos que el equipo de desarrollo terminó la primera versión de TechStore y te pide: "necesitamos que QA empiece a probar esto de forma automática desde ya". Ese es exactamente el escenario para el que se usa este playbook.
A lo largo de los pasos siguientes vamos a ver qué le responderías al asistente en cada pregunta, usando TechStore como ejemplo.
3.1 Antes de arrancar: lo que necesitás tener a mano
No hace falta saber programar, pero sí tener a mano estos tres datos:
| Dato | Ejemplo con TechStore |
|---|---|
| Acceso al proyecto (que el asistente pueda leer los archivos del código) | El repositorio de TechStore ya clonado o accesible |
| La URL de la aplicación, en qué versión está y en qué sistema operativo ejecuta el ambiente de pruebas | https://techstore-staging.com, versión 2.4.1, Windows 11 |
| Una historia de usuario de referencia, chica y simple, para hacer la primera prueba | Por ejemplo: "Como cliente quiero poder agregar un producto al carrito de compras", guardada como archivo .md en la carpeta de historias del proyecto (por defecto user-stories/) |
Si no tenés una historia de usuario a mano, no es un problema: se puede escribir una mínima solo para validar que el circuito funciona (no tiene que ser la prueba más completa del sistema).
Playbook original
El playbook general se encuentra en el repositorio NEO-releases.
3.2 Paso a paso
¡Aclaración!
Este es un ejemplo, vos debés seguir el playbook original.
Paso 1 de 3 — Averiguar con qué está armado el proyecto
Skill que se usa: lippia-neo-bootstrap-stack
Qué pasa: el asistente revisa los archivos del proyecto (como quien mira una caja para ver qué contiene) y trata de inferir con qué herramienta de testing se trabaja, en qué lenguaje está escrito el proyecto, si es una aplicación con pantallas, una API o ambas, y en qué plataforma se ejecutan las pruebas automáticas cuando alguien sube código. Todo lo que no puede adivinar, te lo pregunta directamente a vos.
Si el proyecto es de performance (k6 o JMeter)
Con k6 o jmeter el asistente hace un perfil recortado: no pregunta lo de UI/E2E (login, versión y sistema operativo, historias, bugs, carpetas de artefactos, herramienta de gestión ni .mcp.json), solo la URL y la configuración de carga.
Qué te va a preguntar seguro (porque no lo puede adivinar solo):
- La URL de la aplicación bajo prueba →
https://techstore-staging.com - La versión de la app y el sistema operativo del ambiente →
2.4.1,Windows 11 - Si la aplicación requiere login para entrar (y de qué tipo: usuario y contraseña, cuenta de Google, token, o ninguno) → en TechStore, por ejemplo, "sí, usuario y contraseña"
- Dónde viven las historias de usuario (¿en un archivo local, en Jira, en Azure DevOps?) → "local, en la carpeta
user-stories/" - A dónde se reportan los bugs (¿quedan solo como archivos locales, o se cargan en Jira, Azure DevOps, GitHub o GitLab?) y, si es en una herramienta, en qué proyecto → "en Jira, proyecto
TS". Aunque se carguen en una herramienta, los bugs siempre quedan primero como archivo en la carpeta local (por defectobug-reports/) - En qué carpeta guardar cada cosa que se va generando. Pregunta las 5 de a una, aunque la respuesta parezca obvia: planes de prueba, pruebas automáticas (por defecto
tests/<herramienta>/, ej.tests/playwright/), reportes, ejecuciones guiadas por un plan, y sesiones exploratorias (por defectoexploration/) → si no tenés preferencia, alcanza con aceptar lo que te propone - De dónde sacar las credenciales para las pruebas (por defecto, un archivo
.env.tests). Si el archivo no existe, te ofrece crearlo vacío, con los nombres de los datos que hay que completar — así las pruebas nunca tienen contraseñas escritas a mano → "sí, crealo" - Como última pregunta, a qué herramienta de gestión de pruebas se exportan los casos de prueba: Xray, QMetry o ninguna. Si elegís una, te pide el proyecto y sus credenciales, que se guardan solo en el archivo de credenciales, nunca en la ficha técnica → "ninguna por ahora"
Lo que puede llegar a preguntarte, según el proyecto:
- Si el proyecto usa Lippia y no encuentra su archivo de configuración (
config.properties), te pregunta dónde está. - Si el proyecto es una API (o tiene pantallas y API), busca el documento que describe la API (
openapi.yaml/swagger.json) y, si no lo encuentra, te pide su URL.
Qué te queda al final de este paso: una especie de "carnet de identidad" del proyecto, guardado en un archivo (qa-stack.yaml), que el resto de los playbooks van a leer automáticamente de ahora en adelante — así nunca más hay que volver a responder estas preguntas. Además deja:
| Archivo | Para qué sirve |
|---|---|
qa-stack.yaml |
La ficha técnica del proyecto |
.env.tests |
Las credenciales de prueba (no se sube al repositorio) |
.mcp.json |
La conexión con el navegador que usa el asistente para recorrer la app y, si elegiste Jira, Azure DevOps, GitHub o GitLab, la conexión con esa herramienta (no se sube al repositorio) |
Checkpoint — Revisá la ficha técnica
Confirmá que qa-stack.yaml existe y que tiene completos los datos del stack (herramienta de testing, lenguaje, tipo de app, plataforma del pipeline y tipo de login) y del ambiente (URL, versión y sistema operativo), que quedó definida la herramienta de gestión de pruebas (o "ninguna"), y que existe .mcp.json. Si el proyecto es una API, también tiene que figurar el documento de la API.
Importante
Si la herramienta de testing que detecta todavía no tiene soporte completo (hoy, Pytest), el asistente te va a avisar que algunos pasos de la prueba piloto (generar y ejecutar las pruebas automáticas) no van a poder ejecutarse hasta que se termine de dar soporte a esa herramienta. No es un error tuyo — es una limitación conocida que hay que tener en cuenta antes de seguir. Playwright, Cypress y Lippia ya están soportadas.
Reiniciá el entorno después de este paso
Cuando se crea o actualiza .mcp.json, hay que reiniciar el entorno (por ejemplo, recargar VS Code) para que el asistente cargue esas conexiones. Es necesario para la exploración del Paso 3 y, si elegiste una herramienta en la nube, para leer historias o cargar bugs ahí.
Paso 2 de 3 — Armar el pipeline que ejecuta las pruebas solo
Skill que se usa: lippia-neo-ci-bootstrap
Qué pasa: con la descripción del stack tecnológico del Paso 1, el asistente escribe la configuración de un pipeline automático que, de ahora en adelante, va a ejecutar las pruebas de TechStore cada vez que alguien suba un cambio de código — sin que nadie tenga que acordarse de hacerlo a mano.
Es como poner un guardia de seguridad en la puerta: cada vez que entra algo nuevo (un cambio de código), el guardia lo revisa automáticamente antes de dejarlo pasar.
Qué te queda al final de este paso: los archivos de configuración del pipeline (el nombre exacto depende de dónde vive el código de TechStore — GitHub, GitLab o Bitbucket) que el equipo de desarrollo va a subir junto con el resto del código. Las tareas del pipeline quedan agrupadas en una carpeta propia (neo-ci-jobs/), y el archivo principal del pipeline solo las "llama":
| Dónde vive el código | Archivo principal del pipeline | Carpeta con las tareas |
|---|---|---|
| GitHub | .github/workflows/qa.yml (si ya existía, no se toca y se crea .github/workflows/neo-ci-jobs.yml) |
.github/workflows/neo-ci-jobs/ |
| GitLab | .gitlab-ci.yml (si ya existía, solo se le agrega una línea que incluye las tareas nuevas) |
.gitlab/neo-ci-jobs/ |
| Bitbucket | bitbucket-pipelines.yml (si ya existía, el asistente te propone cómo combinarlo y te pide confirmación) |
.bitbucket/neo-ci-jobs/ |
Las tareas siguen siempre la misma cadena: preparar el ambiente → ejecutar el plan de QA que corresponda (por ejemplo, el de funcionalidades nuevas) → publicar el reporte.
Lo que este paso NO hace
Este paso solo escribe la configuración del pipeline. Todavía no lo pone a ejecutar pruebas reales — eso pasa en el Paso 3. Además, una vez subido, el pipeline se ejecuta solo en los Pull Requests / Merge Requests que tengan la etiqueta configurada para cada plan (por ejemplo, feature), y el equipo técnico tiene que cargar las claves y variables que pide la documentación del pipeline.
Paso 3 de 3 — Prueba piloto: confirmar que todo el circuito funciona
Skill que se usa: lippia-neo-meta-run-user-story-e2e
Qué pasa: el asistente toma la historia de usuario que preparaste ("agregar un producto al carrito") y ejecuta, de punta a punta, el circuito completo de QA:
- Lee la historia de usuario.
- Arma un plan de prueba a partir de ella con sus correspondientes criterios de aceptación.
- Ejecuta el plan en la aplicación real y reporta fallas.
- Genera las pruebas automáticas correspondientes.
- Las ejecuta — y si alguna falla, intenta repararla sola (hasta 3 intentos).
- Escribe un reporte final con el resultado sobre la automatización.
Con TechStore, esto significa que el asistente realmente entra a la tienda online, agrega un producto al carrito, y confirma que el carrito lo refleja correctamente — y deja ese comportamiento convertido en una prueba automática reutilizable.
Esto no es una regresión completa del sistema
Es solo una prueba piloto para confirmar que el "cableado" quedó bien conectado: que se puede leer, planificar, probar, generar, ejecutar y reportar sin que nada se rompa en el camino.
Cómo saber si salió bien:
| Resultado | Qué significa |
|---|---|
| ✅ La prueba pasó o falló, pero se ejecutó de punta a punta | El circuito funciona correctamente (que una prueba falle no es un error del playbook — puede ser un bug real de la app) |
| ✅ Se generó un reporte con el resultado | Podés abrirlo y leer el detalle (en la carpeta de reportes, por defecto test-results/reports/) |
| ✅ Se generó al menos un archivo de prueba automática | Ya queda algo reutilizable para el futuro |
| ⚠️ Quedaron pruebas que no se pudieron reparar | Quedan documentadas en el resumen; no impiden dar por terminada la puesta en marcha |
| ❌ El proceso quedó "bloqueado" sin poder ejecutar nada | Ahí sí hay que avisar al equipo técnico — la herramienta de testing detectada en el Paso 1 puede no estar soportada todavía |
3.3 ¿Qué me queda al finalizar los tres pasos?
| Qué obtenés | Para qué te sirve |
|---|---|
Un archivo con el stack tecnológico del proyecto guardado (qa-stack.yaml) |
Nunca más hay que volver a responder las preguntas de configuración |
El archivo de credenciales (.env.tests) y la configuración de conexiones (.mcp.json) |
Las pruebas y el asistente tienen de dónde sacar los accesos, sin escribirlos a mano |
| Un pipeline de pruebas automáticas configurado | Cada cambio de código en TechStore dispara pruebas solo |
| Un plan de prueba de la historia piloto | Documentación de qué se probó y cómo (en la carpeta de planes, por ejemplo test-plans/) |
| El reporte de la ejecución guiada por el plan | Evidencia de lo que se recorrió en la app (por defecto en execution/) |
| Una prueba automática ya generada y ejecutando | Punto de partida para seguir sumando pruebas (por defecto en tests/<herramienta>/) |
| Un reporte de resultados | Evidencia de que el setup quedó validado |
A partir de acá, TechStore ya "entró" al ecosistema de QA automatizado: para seguir probando nuevas funcionalidades, bugs o cambios, se usan otros playbooks más específicos (por ejemplo, uno para features nuevas, otro para bugs, otro para cambios de UI) — este playbook ya cumplió su función de dejar la base lista.
4. Problemas comunes (y qué hacer)
| Lo que ves | Por qué puede pasar | Qué hacer |
|---|---|---|
| El asistente no logra armar el archivo del stack tecnológico del proyecto | El proyecto no tiene los archivos típicos que permiten adivinar la configuración | Respondé las preguntas que te haga directamente, sin problema |
| El pipeline quedó armado pero las tareas no ejecutan | El Pull Request / Merge Request no tiene la etiqueta del plan (por ejemplo, feature), o faltan claves y variables del pipeline |
Agregá la etiqueta y avisale al equipo técnico para que cargue las claves que pide la documentación del pipeline |
| La prueba piloto queda "bloqueada" sin poder ejecutar | La herramienta de testing detectada todavía no tiene soporte completo | Es un tema para el equipo técnico, no algo que puedas resolver solo/a |
| El asistente no puede abrir la aplicación para recorrerla | No se reinició el entorno después del Paso 1, y todavía no cargó la conexión con el navegador | Reiniciá el entorno (por ejemplo, recargá VS Code) y volvé a ejecutar el Paso 3 |
| Las pruebas fallan y no se pueden reparar solas | Puede ser que la aplicación no esté levantada, o que la URL/credenciales estén mal | Verificá que la URL de TechStore esté accesible y que las credenciales sean correctas |
| Las pruebas fallan en el login | Los valores del archivo de credenciales (.env.tests, creado en el Paso 1) están vacíos o incompletos |
Completá los valores reales en .env.tests (nunca se escriben a mano dentro de las pruebas) y volvé a ejecutar las pruebas |
5. Resumen visual del flujo
flowchart TD
A([🏗️ Proyecto nuevo sin QA automatizado<br/>ej: TechStore recién armado]) --> B
B["<b>Paso 1</b> — Averiguar con qué<br/>está armado el proyecto"] --> C
C["<b>Paso 2</b> — Armar el pipeline<br/>que ejecuta las pruebas solo"] --> D
D["<b>Paso 3</b> — Prueba piloto de punta a punta<br/>ej: agregar producto al carrito"] --> E{¿Ejecutó de<br/>punta a punta?}
E -->|Sí, pasó o falló| F([✅ Proyecto listo para<br/>darle continuidad])
E -->|Quedó bloqueado| G([⚠️ Avisar al equipo técnico:<br/>herramienta sin soporte])