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 correr 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 corre 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 del proyecto bajo test Sí
Node.js + npm El motor que corre 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 correr 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 6 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 (global)
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 repo del proyecto bajo test (por ejemplo, TechStore) — donde vas a generar y correr los tests.

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 correr. 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 de tu sistema.

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 revisa dos ubicaciones (los ejemplos usan Claude Code — para Codex o Copilot es la misma lógica reemplazando .claude por .codex o .copilot, según la tabla en 2.1):

Ubicación Qué significa Alcance
~/.claude/skills/ (carpeta del usuario) Skills disponibles en todos tus proyectos, sin importar en cuál estés parado Global
<repo>/.claude/skills/ (carpeta del proyecto) Skills que viajan con ese repositorio puntual — cualquiera que lo clone las tiene disponibles Solo ese proyecto

No hace falta copiar los archivos a mano: se usa un acceso directo (symlink) que apunta 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.

4.2 Opción A — Disponibilizarlas globalmente (recomendado)

Recomendada si vas a usar las mismas skills en varios proyectos. Se hace una sola vez por computadora.

  1. Abrí Git Bash (en Windows) o una terminal (Mac/Linux).

  2. Parate en la carpeta donde clonaste NEO-releases:

    cd /ruta/a/NEO-releases

  3. Ejecutá:

    mkdir -p ~/.claude/skills

for skill in skills/*/; do
  name=$(basename "$skill")
  ln -sfn "$(pwd)/$skill" ~/.claude/skills/"$name"
done

    Si usás Codex o Copilot, reemplazá .claude por .codex o .copilot en las dos líneas que mencionan la carpeta (según la tabla en 2.1) — el resto del bloque es igual.

    Alternativa en PowerShell (Windows):

    Get-ChildItem -Path "skills" -Directory | ForEach-Object {
    $name = $_.Name
    $target = Join-Path (Get-Location) "skills\$name"
    $linkPath = Join-Path $HOME ".claude\skills\$name"

    if (Test-Path $linkPath) {
        Remove-Item $linkPath -Force -Recurse
    }

    New-Item -ItemType Junction -Path $linkPath -Target $target | Out-Null
}

    Este bloque usa Junction en vez de symlink porque en Windows crear symlinks reales requiere permisos de administrador (o el modo desarrollador habilitado), mientras que las Junctions no. Si usás Codex o Copilot, reemplazá .claude por .codex o .copilot en la línea de $linkPath.

  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.

4.3 Opción B — Disponibilizarlas solo para un proyecto puntual

Recomendada cuando querés que las skills viajen versionadas junto con el repo del proyecto bajo test (por ejemplo, para fijar una versión específica).

  1. Parate en la carpeta del proyecto bajo test (no en NEO-releases):

    cd /ruta/al/proyecto-bajo-test
mkdir -p .claude/skills

  2. Si clonaste NEO-releases al lado de ese proyecto, corré:

    for skill in ../NEO-releases/skills/*/; do
  name=$(basename "$skill")
  ln -sfn "$(cd "$skill" && pwd)" .claude/skills/"$name"
done

    El repo trae este mismo bloque guardado en el archivo link-claude-skills.sh, así que también podés simplemente correr bash ../NEO-releases/link-claude-skills.sh. Si usás Codex o Copilot, reemplazá .claude por .codex/.copilot en el bloque anterior (no hay un script equivalente todavía para esas dos rutas).

Las skills a nivel proyecto tienen prioridad sobre las globales cuando coinciden los nombres.

4.4 Verificar que tu asistente ya las ve

Abrí una sesión con tu asistente de IA sobre el proyecto bajo test y escribile, en lenguaje natural:

Listá las skills de QA disponibles

Si la instalación salió bien, tu asistente va a responder con la lista de skills (qa-read-user-story, qa-create-test-plan, qa-workflow-e2e, etc.).

IMPORTANTE: Si estas utilizando vscode con la extensión del agente de claude code, luego de crear las skills, es necesario re cargar el vscode para que puedan visualizarse las skills disponibles.

4.5 Desinstalar (si hace falta)

Como son accesos directos, borrarlos no toca el repositorio original:

# Global
for skill in skills/*/; do rm -f ~/.claude/skills/"$(basename "$skill")"; done

# A nivel de un proyecto puntual
rm -rf .claude/skills

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

Parate en la carpeta raíz del proyecto bajo test (donde está su package.json, no en NEO-releases) y corré, 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 qa-bootstrap-stack/qa-ci-bootstrap que lo verifique). Esto aplica tanto si corré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 corre 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 correrlo 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 correr los tests, tu asistente usa Playwright para explorar la app manualmente antes de generar los tests (la skill qa-exploratory-test / qa-scripted-execution). 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 corrida 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 corrida 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 correr 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 qa-exploratory-test) 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 proyecto bajo test:

# .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 qa-bootstrap-stack te lo puede armar, preguntándote estos datos la primera vez que configura el proyecto.

!!! warning "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 correrlo, 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 corren 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 la carpeta equivocada Repetí el paso 4.2 o 4.3 y verificá con ls -l ~/.claude/skills/ (o la carpeta equivalente de tu asistente — ver 2.1 — o .claude/skills/ del proyecto)
Los comandos de symlink (ln -sfn, for ... in) tiran error en la terminal Estás en la terminal de Windows (cmd.exe o PowerShell) en vez de Git Bash Abrí específicamente Git Bash (se instaló junto con Git) y volvé a correr los comandos ahí
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 correr npx playwright install o npx @playwright/mcp install-browser Corré ambos comandos (secciones 6.2 y 6.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) Correr 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 corre 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 (qa-generate-test-suite, qa-run-and-heal) dice que falta configuración No existe qa-stack.yaml en la raíz del proyecto bajo test Pedile a tu asistente: "usá qa-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 6.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