Requisitos y puesta en marcha de NEO
Esta guía está pensada para cualquier persona, sin conocimientos técnicos ni de programación, que necesite dejar su computadora lista para trabajar con NEO. Al terminar de leerla vas a poder responder:
- ¿Qué necesito tener instalado en mi computadora para poder usar
NEO? - ¿Cómo hago para que mi asistente de IA "vea" las skills de este proyecto y cómo las uso una vez disponibles?
- ¿Cómo dejo configurado Playwright, el motor que usan las skills para manejar el navegador?
¡IMPORTANTE! Esta guía es de instalación y puesta en marcha (se hace una sola vez por computadora, o cada vez que empezás en un proyecto nuevo). Para entender qué es una skill o un playbook, o cómo elegir entre los distintos modelos de trabajo, mirá las guías
Playbooks vs SkillsyModelos.
1. La idea en una sola frase
NEOno es un programa que se instala y listo — es una carpeta con instrucciones escritas ("skills") que un asistente de IA compatible (Claude Code, Codex o GitHub Copilot), dentro de un editor llamado VSCode, sabe leer y ejecutar. Para que funcione necesitás tres cosas: el editor (VSCode), el asistente (Claude Code, Codex o Copilot) y las herramientas que las skills usan por detrás (Node.js, Playwright, y opcionalmente Java/Maven).
Con eso instalado una sola vez, todo lo demás (leer una historia, armar un plan de pruebas, generar y ejecutar tests) se lo pedís a tu asistente en lenguaje natural.
2. Stack técnico necesario — de un vistazo
Esta tabla resume todo lo que hace falta tener instalado. Los puntos 3 a 5 explican, paso a paso, cómo conseguir cada cosa.
| Necesitás | ¿Para qué sirve? | ¿Es obligatorio? |
|---|---|---|
| Una computadora con Windows, Mac o Linux | Donde ejecuta todo lo demás | Sí |
| VSCode (Visual Studio Code) | El editor donde vas a trabajar junto con tu asistente de IA | Sí |
| La extensión/CLI de tu asistente de IA (ver tabla en 2.1) | El asistente que lee y ejecuta las skills | Sí |
| Una cuenta habilitada para ese asistente (ver tabla en 2.1) | Sin login, el asistente no puede responderte nada | Sí |
| Git | Para descargar (clonar) el repositorio de NEO (NEO-releases) y el repositorio de pruebas |
Sí |
| Node.js + npm | El motor que ejecuta Playwright (el framework de tests más usado en este proyecto) | Sí, si el proyecto usa Playwright |
| Playwright + sus navegadores | Es quien realmente "maneja" el navegador para explorar la app y ejecutar los tests | Sí, si el proyecto usa Playwright |
| Conexión a internet / VPN de la empresa | Para bajar el repo, los navegadores de Playwright y conectar con Jira/Azure DevOps si corresponde | Sí |
| Java (JDK 8+) y Apache Maven | Solo si el proyecto usa Lippia (Java + Cucumber) en vez de Playwright |
No — solo para stack Lippia |
| Google Chrome instalado | Solo si el proyecto usa Lippia (necesita un Chrome real del sistema, no alcanza con el que descarga Playwright) |
No — solo para stack Lippia |
El resto de esta guía asume el caso más común: un proyecto que usa Playwright (JavaScript/TypeScript). Si tu proyecto usa
Lippia, al final de la sección 5 hay una nota con los requisitos extra.
2.1 ¿Qué asistente de IA puedo usar?
NEO no depende de un asistente en particular: cualquiera de estos tres funciona, porque los tres saben leer skills en formato SKILL.md y conectarse al mismo servidor MCP de Playwright (.mcp.json). Lo único que cambia entre ellos es la extensión/CLI a instalar, la cuenta con la que iniciás sesión y la carpeta donde cada uno busca las skills.
| Asistente | Extensión/CLI | Cuenta necesaria | Carpeta de skills (en el repositorio de pruebas) |
|---|---|---|---|
| Claude Code | Extensión "Claude Code" para VSCode (o la CLI de terminal) | Cuenta de Claude/Anthropic habilitada | .claude/skills/ |
| Codex | Extensión/CLI de Codex | Cuenta habilitada para Codex | .codex/skills/ |
| GitHub Copilot | Extensión de GitHub Copilot para VSCode | Cuenta de GitHub con Copilot habilitado | .copilot/skills/ |
El resto de esta guía usa Claude Code como ejemplo de referencia en los pasos concretos (es el que está documentado con más detalle hoy), pero cada paso tiene el equivalente directo para Codex o Copilot reemplazando la extensión/cuenta/carpeta según esta tabla.
3. Paso a paso: instalar lo básico
3.1 Instalar VSCode
- Descargalo desde code.visualstudio.com y seguí el instalador (siguiente, siguiente, finalizar).
- Abrilo una vez instalado para confirmar que arranca bien.
3.2 Instalar tu asistente de IA
Los pasos de abajo son para Claude Code. Si usás Codex o Copilot, instalá la extensión/CLI equivalente (ver tabla en 2.1) y seguí el flujo de login propio de esa herramienta — el resto de esta guía (skills, Playwright, MCP) funciona igual una vez que el asistente está instalado y logueado.
- En VSCode, abrí el panel de extensiones (ícono de cuadraditos en el margen izquierdo, o
Ctrl+Shift+X). - Buscá "Claude Code for vs Code" e instalalo.
- Al abrirla por primera vez te va a pedir iniciar sesión con tu cuenta de Claude/Anthropic — seguí el flujo de login que te propone (se abre el navegador, confirmás y volvés a VSCode).
IMPORTANTE: Si tu usuario todavía no tiene acceso habilitado, pedilo al equipo técnico antes de seguir — sin login no hay forma de usar el asistente.
3.3 Instalar Git
Git es lo que te permite descargar ("clonar") los repositorios del proyecto.
- Windows: descargalo de git-scm.com e instalalo con las opciones por defecto (esto también instala Git Bash, una terminal que vas a necesitar más adelante).
- Mac: suele venir preinstalado; si no,
xcode-select --installdesde la Terminal, o git-scm.com.
Verificar que quedó instalado: abrí una terminal (en Windows, buscá "Git Bash") y escribí:
git --version
Si te devuelve un número de versión, está listo.
3.4 Para clonar los repositorios que vas a necesitar
Vas a trabajar con al menos dos carpetas en VSCode, segun el proyecto:
NEO-releases— donde viven las skills y los playbooks.- El repositorio de pruebas (por ejemplo, el de TechStore) — donde vas a generar y ejecutar los tests. Puede ser el mismo repositorio de la aplicación o, como pasa en muchos proyectos, uno separado.
Para obtener el link al repositorio, debes seguir estos pasos:
Entra en GitLab (https://gitlab.crowdaronline.com/lippia/products/neo) luego que te dan permisos al proyecto, haces click sobre el repo que queres clonar , por ejemplo "NEO-releases", vas y presionas el boton "Code" y al abrir te mostrara dos opciones, copias la de "Clone with HTTPS" o "Clone with SSH".
Para clonar el repositorio en VSCode, Ctrl+Shift+P → escribí "Git: Clone" , esto disponibilizará un campo input arriba de todo → pegá la URL del repositorio que copiaste → elegí una carpeta en tu computadora → Open cuando termine. (El mismo procedimiento que se explica con más detalle en last_version.md, sección 6.)
3.5 Instalar Node.js y npm
Node.js es el motor que necesita Playwright para ejecutarse. npm (Node Package Manager) viene incluido con Node.js — no se instala aparte.
- Descargá la versión LTS (la recomendada, no la "Current") desde nodejs.org.
- Instalala con las opciones por defecto.
Verificar:
node --version
npm --version
Ambos comandos tienen que devolver un número de versión.
4. Cómo disponibilizar las skills para tu asistente de IA
Con VSCode, tu asistente de IA, Git y Node ya instalados, el paso que falta es decirle al asistente dónde están las skills de NEO-releases. Tu asistente no las "adivina" — necesita encontrarlas en una carpeta específica del repositorio de pruebas.
4.1 Cómo funciona
Cada skill es una carpeta con un archivo SKILL.md adentro: instrucciones escritas para que el asistente sepa hacer una tarea puntual (leer una historia, armar un plan de pruebas, generar tests, etc.). En el repositorio de NEO-releases se encuentra un archivo "INSTALL.md" el cual contiene todo los pasos a efectuar (Se complementa con esta guía).
Al arrancar una sesión, tu asistente busca las skills en esta carpeta, dentro del repositorio de pruebas (el repositorio donde viven tus tests automatizados, que puede ser el mismo de la aplicación o uno separado):
<repositorio-de-pruebas>/.claude/skills/
Si usás Codex o Copilot en vez de Claude Code, es la misma lógica reemplazando
.claudepor.codexo.copilot(según la tabla en 2.1).
No hace falta copiar los archivos a mano: NEO-releases trae un script que crea un acceso directo (symlink) por cada skill, apuntando a la carpeta real dentro de NEO-releases. Así, cuando el equipo técnico actualiza una skill y vos hacés pull sobre NEO-releases (ver last_version.md), el cambio se refleja solo, sin repetir ningún paso. El script también enlaza los playbooks en .claude/playbooks/ y copia en .claude/rules/ las reglas que el asistente necesita para ejecutarlos.
4.2 Vincular las skills al repositorio de pruebas
Hay un script para cada sistema operativo. Los dos se ejecutan desde la carpeta del repositorio de pruebas (no en NEO-releases). En los dos casos, reemplazá <ruta-de-neo-releases> por la carpeta donde clonaste NEO-releases (por ejemplo, ../NEO-releases si los dos repositorios están en la misma carpeta padre).
En Linux o Mac
- Abrí una terminal.
-
Posicionate en la carpeta del repositorio de pruebas:
cd /ruta/al/repositorio-de-pruebas -
Ejecutá el script de
NEO-releases:bash <ruta-de-neo-releases>/symlink-skills-bash.sh -
Verificá que se crearon los accesos directos:
ls -l .claude/skills/Tenés que ver una lista con el nombre de cada skill, apuntando hacia la carpeta de
NEO-releases.
En Windows
- Abrí Git Bash con privilegios de administrador: buscá "Git Bash" en el menú de inicio, hacé clic derecho y elegí Ejecutar como administrador. Windows solo permite crear enlaces simbólicos con permisos de administrador. La terminal integrada de VSCode no sirve para este paso, salvo que hayas abierto VSCode como administrador.
-
Posicionate en la carpeta del repositorio de pruebas:
cd /ruta/al/repositorio-de-pruebas -
Ejecutá el script de
NEO-releases:bash <ruta-de-neo-releases>/symlink-skills-win-git-bash.sh -
Al terminar, el script muestra la lista de skills enlazadas. Cada una tiene que aparecer con el tipo
<SYMLINKD>(enlace simbólico a una carpeta). Si aparecen como<DIR>, son copias que no se van a actualizar congit pull: borrá la carpeta.claude/skillsy volvé a ejecutar el script desde Git Bash como administrador.
Los scripts crean los enlaces para Claude Code (carpeta
.claude/). Si usás Codex o Copilot en Windows, cambiáASSISTANT=claudeporASSISTANT=codexoASSISTANT=copilotensymlink-skills-win-git-bash.shantes de ejecutarlo. El script de Linux o Mac por ahora solo crea.claude/.IMPORTANTE: Si estás usando VSCode con la extensión de Claude Code, después de crear los enlaces es necesario recargar VSCode para que se puedan ver las skills disponibles.
4.3 Verificar que tu asistente ya las ve
Abrí una sesión con tu asistente de IA sobre el repositorio de pruebas y escribile, en lenguaje natural:
Listá las skills de Neo disponibles
Si la instalación salió bien, tu asistente va a responder con la lista de skills (lippia-neo-read-user-story, lippia-neo-create-test-plan, lippia-neo-meta-run-user-story-e2e, etc.).
4.4 Desinstalar (si hace falta)
Como son accesos directos, borrarlos no toca el repositorio NEO-releases. Desde la carpeta del repositorio de pruebas:
rm -rf .claude/skills .claude/playbooks
5. Cómo configurar Playwright
Playwright es la herramienta que efectivamente abre un navegador (Chrome, Firefox, etc.), navega por la app bajo test, hace clics, completa formularios y verifica resultados — es el "brazo ejecutor" detrás de las skills cuando el proyecto está configurado con este framework.
5.1 Instalar las dependencias del proyecto
Posicionate en la carpeta raíz del repositorio de pruebas (donde está su package.json, no en NEO-releases) y ejecutá, en una terminal:
npm install
Esto descarga las librerías que el proyecto ya tiene declaradas en su package.json (entre ellas, @playwright/test).
IMPORTANTE:
npm installno agrega@playwright/testsolo — si el proyecto no lo tiene declarado enpackage.json(endependenciesodevDependencies), hay que agregarlo antes (npm install @playwright/test, o pedirle alippia-neo-bootstrap-stack/lippia-neo-ci-bootstrapque lo verifique). Esto aplica tanto si ejecutás esto en tu computadora como en el pipeline de CI: si el paquete no está declarado,npx playwright installtermina resolviendo una versión ad-hoc distinta a la del proyecto, y si el pipeline ejecuta en una imagen sin usuario root (como la del engine de Crowdar), agregarle--with-depsa ese comando falla directamente (necesita permisos de root que esa imagen no tiene).
5.2 Instalar los navegadores de Playwright
Playwright necesita sus propias copias de los navegadores (no usa el Chrome que ya tenés instalado en la computadora):
npx playwright install
Este paso descarga los binarios de Chromium, Firefox y WebKit. Solo hace falta ejecutarlo una vez por computadora (o cuando cambia la versión de Playwright del proyecto).
5.3 Instalar el navegador para la etapa de exploración (MCP)
Además de ejecutar los tests, tu asistente usa Playwright para explorar la app manualmente antes de generar los tests (la skill lippia-neo-run-manual-testing). Para eso necesita su propio navegador vía MCP:
npx @playwright/mcp install-browser chrome-for-testing
⚠️ Ojo con la deriva de versión de
@playwright/mcp@latest: el.mcp.jsonde este repo arranca el servidor con@playwright/mcp@latest, así que cada ejecución puede traer una versión distinta del paquete — y cada versión espera una revisión distinta de Chrome-for-Testing. Si ya tenías un navegador instalado de una ejecución vieja, puede aparecer un error comoBrowser "chrome-for-testing" is not installed; expected executable at ...\ms-playwright\chromium-<rev>\chrome-win64\chrome.exe. El fix es volver a ejecutar el comando de arriba para instalar la revisión que pide el error — ver el detalle completo enplaywright-mcp-setup.md(Incidente 5).
5.4 Qué es el archivo .mcp.json (no hace falta tocarlo)
El repositorio NEO-releases ya trae un archivo .mcp.json con la configuración del servidor MCP de Playwright:
"playwright": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@playwright/mcp@latest", "--browser", "chromium"],
"env": {}
}
No necesitás editar esto — ya viene configurado. Es simplemente la forma en la que tu asistente sabe cómo arrancar el navegador de Playwright cuando una skill lo necesita. Este archivo es el mismo para los tres asistentes (Claude Code, Codex y Copilot) — no cambia nada según cuál uses.
Si al usar una skill que depende del MCP (por ejemplo
lippia-neo-run-manual-testing) te aparece un error de conexión, mirá el instructivoplaywright-mcp-setup— cubre los incidentes más comunes de configuración del MCP de Playwright y cómo resolverlos.
5.5 Datos del ambiente bajo test (URL y credenciales)
Las skills necesitan saber contra qué URL probar y con qué usuario. Esto vive en un archivo .env (que nunca se sube al repositorio — está en .gitignore), en la raíz del repositorio de pruebas:
# .env
APP_BASE_URL=https://tu-app-bajo-test.com
APP_USERNAME=usuario-de-prueba
APP_PASSWORD=contraseña-de-prueba
Si no tenés este archivo todavía, la skill lippia-neo-bootstrap-stack te lo puede armar, preguntándote estos datos la primera vez que configura el proyecto.
Los artefactos generados pueden seguir conteniendo credenciales
Las skills están diseñadas explícitamente para no tomar los valores del .env (o de la carpeta que hayas definido) y dejarlos "hardcodeados" en el código o los reportes que generan. Pero la IA no es perfecta: en la práctica pueden quedar credenciales, tokens o datos sensibles filtrados en el código de los tests, en los reportes, en capturas de pantalla o en otros artefactos generados.
Por eso, antes de subir a un repositorio compartido o distribuir estos artefactos, revisalos (o definí un checkpoint/paso de revisión en tu flujo) para confirmar que no quedó ningún dato sensible expuesto.
5.6 El archivo qa-stack.yaml
Es la "ficha técnica" del proyecto: le dice a las skills que el framework es playwright, en qué carpeta están los tests, dónde se guardan los reportes, etc. No hace falta escribirlo a mano.
Para entender qué hace este playbook paso a paso antes de ejecutarlo, leé el instructivo
new-project-bootstrap.
5.7 Checklist rápido de Playwright
node --version && npm --version # Node y npm instalados
npm install # dependencias del proyecto
npx playwright install # navegadores de Playwright
npx @playwright/mcp install-browser chrome-for-testing # navegador para exploración
Si los cuatro comandos se ejecutan sin error, Playwright está listo para que las skills generen y ejecuten tests.
¿Tu proyecto usa
Lippia(Java + Cucumber) en vez de Playwright? Entonces en lugar de esta sección necesitás: un JDK 8+, Apache Maven 3.6+, acceso a los repositorios Nexus de Crowdar, y un Google Chrome real instalado en el sistema (no alcanza con el que descarga Playwright). El detalle completo de este caso está enINSTALL.mddel repoNEO-releases.
6. Resumen visual del flujo completo
El diagrama usa Claude Code como ejemplo ilustrativo, pero el flujo (instalar el editor, instalar el asistente, disponibilizar las skills, pedir trabajo en lenguaje natural) es el mismo si usás Codex o Copilot.
7. Problemas comunes (y qué hacer)
| Lo que ves | Por qué puede pasar | Qué hacer |
|---|---|---|
| Tu asistente responde que no encuentra ninguna skill | El symlink no se creó, o se creó en una carpeta que no es la del repositorio de pruebas | Repetí el paso 4.2 desde la carpeta del repositorio de pruebas y verificá con ls -l .claude/skills/ (o la carpeta equivalente de tu asistente — ver 2.1) |
El script de symlinks (symlink-skills-win-git-bash.sh) tira error en Windows |
Lo ejecutaste desde la terminal de Windows (cmd.exe o PowerShell) en vez de Git Bash, o abriste Git Bash sin permisos de administrador |
Abrí Git Bash con Ejecutar como administrador y volvé a ejecutar el script desde la carpeta del repositorio de pruebas (paso 4.2) |
npx playwright install tarda mucho o falla |
Está descargando los navegadores por primera vez y depende de tu conexión | Esperá a que termine; si falla por red, verificá tu conexión/VPN y reintentá |
| Un test falla con error de navegador no encontrado | Falta ejecutar npx playwright install o npx @playwright/mcp install-browser |
Ejecutá ambos comandos (secciones 5.2 y 5.3) |
Error Browser "chrome-for-testing" is not installed; expected executable at ...chromium-<rev>... aunque ya habías instalado el navegador antes |
@playwright/mcp@latest trajo una versión nueva que espera otra revisión de Chrome-for-Testing distinta a la que tenés instalada (ver sección 5.3) |
Ejecutar npx @playwright/mcp@latest install-browser chrome-for-testing para instalar la revisión que pide el error |
En el pipeline de CI, npx playwright install falla con su: Authentication failure (o similar, pidiendo contraseña de root) |
Se le agregó --with-deps al comando en un runner que se ejecuta como usuario no-root (como la imagen del engine de Crowdar) — esa imagen ya trae las dependencias de sistema instaladas de fábrica |
Quitar --with-deps del comando en el CI; alcanza con npm install && npx playwright install <browser> |
Una skill con adapter (lippia-neo-generate-test-suite, lippia-neo-run-and-heal) dice que falta configuración |
No existe qa-stack.yaml en la raíz del repositorio de pruebas |
Pedile a tu asistente: "usá lippia-neo-bootstrap-stack para generar qa-stack.yaml" |
| Los tests no encuentran la URL o las credenciales de la app | Falta el archivo .env o le faltan variables |
Creá/completá .env en la raíz del proyecto con APP_BASE_URL, APP_USERNAME, APP_PASSWORD (sección 5.5) |
| Tu asistente no responde nada / pide iniciar sesión todo el tiempo | La cuenta (Claude/Anthropic, Codex o GitHub) no quedó logueada, o no tiene acceso habilitado | Repetí el login desde la extensión/CLI (paso 3.2); si el problema persiste, consultá al equipo técnico por el acceso |