Saltar a contenido

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 Skills y Modelos.


1. La idea en una sola frase

NEO no 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

  1. Descargalo desde code.visualstudio.com y seguí el instalador (siguiente, siguiente, finalizar).
  2. 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.

  1. En VSCode, abrí el panel de extensiones (ícono de cuadraditos en el margen izquierdo, o Ctrl+Shift+X).
  2. Buscá "Claude Code for vs Code" e instalalo.
  3. 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 --install desde 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:

  1. NEO-releases — donde viven las skills y los playbooks.
  2. 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.

  1. Descargá la versión LTS (la recomendada, no la "Current") desde nodejs.org.
  2. 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 .claude por .codex o .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

  1. Abrí una terminal.
  2. Posicionate en la carpeta del repositorio de pruebas:

    cd /ruta/al/repositorio-de-pruebas
    
  3. Ejecutá el script de NEO-releases:

    bash <ruta-de-neo-releases>/symlink-skills-bash.sh
    
  4. 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

  1. 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.
  2. Posicionate en la carpeta del repositorio de pruebas:

    cd /ruta/al/repositorio-de-pruebas
    
  3. Ejecutá el script de NEO-releases:

    bash <ruta-de-neo-releases>/symlink-skills-win-git-bash.sh
    
  4. 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 con git pull: borrá la carpeta .claude/skills y 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=claude por ASSISTANT=codex o ASSISTANT=copilot en symlink-skills-win-git-bash.sh antes 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 install no agrega @playwright/test solo — si el proyecto no lo tiene declarado en package.json (en dependencies o devDependencies), hay que agregarlo antes (npm install @playwright/test, o pedirle a lippia-neo-bootstrap-stack/lippia-neo-ci-bootstrap que 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 install termina 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-deps a 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.json de 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 como Browser "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 en playwright-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 instructivo playwright-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á en INSTALL.md del repo NEO-releases.


6. Resumen visual del flujo completo

Puesta en marcha paso a paso: desde instalar VSCode y Claude Code hasta poder pedir cualquier trabajo de QA en lenguaje natural, con el porcentaje de avance en cada etapa

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