Saltar a contenido

Configurar el MCP de Katalon Studio

Esta guía explica cómo conectar Katalon Studio para que NEO cree, ejecute y repare los tests automatizados dentro de un proyecto de Katalon, en Groovy, en lugar de generarlos como archivos en el repositorio.

Nombre del servidor katalon-studio (usá siempre este nombre)
Servidor El MCP server integrado en Katalon Studio (11.6 o superior). No se instala ningún paquete
Tipo Remoto por HTTP (type: http): Katalon Studio lo expone en una URL, normalmente en tu misma computadora
Autenticación Token opcional (Authorization: Bearer <token>)
Cuándo se necesita Solo si el proyecto usa stack.test_framework: katalon en qa-stack.yaml
Skills que lo usan lippia-neo-generate-test-suite y lippia-neo-run-and-heal, con el adapter katalon. Lo agrega lippia-neo-bootstrap-stack

A diferencia de los otros servidores de NEO, este no es un programa que lanza el asistente (npx / uvx): es Katalon Studio el que lo publica, y el asistente solo se conecta a su URL. Por eso Katalon Studio tiene que estar abierto.


1. ¿Qué hace NEO con Katalon?

Con test_framework: katalon no hay carpeta tests_dir: la suite vive en el proyecto de Katalon que tengas abierto. NEO la maneja con las tools del MCP:

Etapa Qué hace Tools del MCP que usa
Generar (lippia-neo-generate-test-suite) Crea un test case por cada caso del plan, sus test objects (locators), la suite <US-ID> y el keyword de sesión writeTestCase, writeWebTestObject, writeRestWebServiceTestObject, writeTestSuite, writeCustomKeyword, listEntityFiles, readFile, searchProject
Ejecutar y reparar (lippia-neo-run-and-heal) Corre los tests desde Katalon Studio, lee los resultados, diagnostica las fallas y corrige los tests executeTest, getTestExecutionStatus, getTestExecutionResults, analyzeTestFailure, stopTestExecution y, para validar locators rotos, las tools webUI*

Qué sigue haciendo Playwright

La exploración (ejecución scripted, sesiones exploratorias, reproducción de bugs) sigue usando el MCP de Playwright, también con Katalon. La navegación de Katalon se usa solo al reparar, para comprobar un locator en el mismo motor que corre el test. Por eso en un proyecto Katalon necesitás los dos servidores: playwright y katalon-studio.

¿Por qué no usar la navegación de Katalon para explorar? No tiene hover, selección, teclas, subida de archivos, esperas, consola ni red; no carga la sesión guardada; y obligaría a tener Katalon Studio abierto para toda exploración. El detalle está en el ADR-028 de la arquitectura.


2. Antes de empezar

Necesitás Por qué Cómo verificarlo
Katalon Studio 11.6 o superior Es la versión que trae el MCP server integrado Help → About Katalon Studio
El proyecto de la suite abierto El MCP opera sobre el proyecto que está abierto en ese momento Ver el proyecto en el Tests Explorer
El MCP server habilitado Viene desactivado hasta que lo prendés Ver el Paso 1
Una licencia de Katalon activa La necesita Katalon Studio para ejecutar La app abre sin pedir activación
El MCP de Playwright Para explorar la app, igual que en los otros frameworks Ver la guía general

3. Paso 1 — Habilitar el MCP server en Katalon Studio

  1. Abrí Katalon Studio y el proyecto donde van a vivir los tests.
  2. Entrá a la configuración del MCP server de Katalon Studio y habilitalo.
  3. Anotá la URL que muestra. Tiene esta forma:
http://127.0.0.1:33699/mcp/stream

No asumas el host ni el puerto: cambian entre instalaciones y el servidor puede ser remoto. Copiá siempre la URL que te muestra tu Katalon Studio. 4. Si el server pide token, copialo. Si no lo pide, no hace falta ningún token.

Los nombres exactos de los menús pueden variar entre versiones de Katalon Studio. Si no encontrás la opción, buscá "MCP" en la configuración de la aplicación.


4. Paso 2 — Indicar el framework en qa-stack.yaml

stack:
  test_framework: katalon
  language: groovy

# No hay paths.tests_dir: la suite vive en el proyecto de Katalon

katalon:
  mcp_server: katalon-studio          # nombre del server en .mcp.json
  test_cases_folder: Test Cases       # se crea <carpeta>/<US-ID>/ por historia
  object_repository_folder: Object Repository
  test_suites_folder: Test Suites     # una suite <US-ID> por historia
  browser: CHROME
  execution_profile: default          # profile con las GlobalVariable
Campo Para qué Valor por defecto
mcp_server Nombre del servidor en .mcp.json. La URL y el token viven allá, no en este archivo katalon-studio
test_cases_folder Carpeta de los test cases. Cada historia tiene la suya: <US-ID>/ Test Cases
object_repository_folder Carpeta de los test objects, en <US-ID>/<Página>/ Object Repository
test_suites_folder Carpeta de las suites (una por historia) Test Suites
browser Navegador de ejecución: CHROME, CHROME_HEADLESS, FIREFOX, FIREFOX_HEADLESS, EDGE_CHROMIUM, SAFARI CHROME
execution_profile Profile de Katalon con las GlobalVariable (BASE_URL, APP_USER, APP_PASSWORD, API_TOKEN_*) default

lippia-neo-bootstrap-stack pregunta todo esto cuando elegís Katalon como framework: la URL del servidor, si pide token, las carpetas, el navegador y el profile. No te pregunta tests_dir.


5. Paso 3 — Configurar el servidor en tu asistente

Base para todos: .mcp.json en la raíz del proyecto

{
  "mcpServers": {
    "katalon-studio": {
      "type": "http",
      "url": "http://127.0.0.1:33699/mcp/stream",
      "headers": {
        "Authorization": "Bearer <token del MCP server de Katalon>"
      }
    }
  }
}
Clave ¿Obligatoria? Para qué
type Sí, con el valor "http" Es un servidor remoto, no un comando local
url Sí La URL que muestra Katalon Studio (Paso 1)
headers.Authorization Solo si el server pide token Bearer <token>. Si no pide token, borrá todo el bloque headers

.mcp.json tiene que estar en .gitignore si lleva el token. Lo que se versiona es .mcp.json.template.

Según tu asistente

Asistente Qué hacer Detalle del formato
Claude Code (VS Code, CLI o pestaña Code de Claude Desktop) Nada más: lee el .mcp.json de arriba. Recargá la ventana y aprobá el servidor IDE · Terminal
GitHub Copilot en VS Code / JetBrains / Visual Studio Mismo contenido con la clave servers IDE
Codex Sección [mcp_servers.katalon-studio] con url en ~/.codex/config.toml IDE · Terminal
Cursor Copiá el bloque a .cursor/mcp.json IDE
Claude Desktop (chat) y ChatGPT (chat) ❌ No es el camino para NEO. Usá la pestaña Code de Claude Desktop o Codex Escritorio

Por comando, en Claude Code CLI:

claude mcp add --transport http --scope project katalon-studio \
  http://127.0.0.1:33699/mcp/stream \
  --header "Authorization: Bearer <token>"

Ejemplo para Copilot en VS Code (.vscode/mcp.json), pidiendo el token al conectar:

{
  "inputs": [
    { "id": "katalon-token", "type": "promptString", "description": "Token del MCP de Katalon", "password": true }
  ],
  "servers": {
    "katalon-studio": {
      "type": "http",
      "url": "http://127.0.0.1:33699/mcp/stream",
      "headers": { "Authorization": "Bearer ${input:katalon-token}" }
    }
  }
}

Ejemplo para Codex (~/.codex/config.toml):

[mcp_servers.katalon-studio]
url = "http://127.0.0.1:33699/mcp/stream"
bearer_token_env_var = "KATALON_MCP_TOKEN"   # variable de entorno con el token; quitar si no pide token

Si sacás el servidor de NEO o lo renombrás, acordate de actualizar katalon.mcp_server en qa-stack.yaml: tiene que coincidir con el nombre que usa .mcp.json.

El handshake inicial tarda

El primer arranque del MCP de Katalon demora unos 30 segundos. Si el asistente lo muestra como failed to connect o timeout, aumentá el tiempo de espera antes de abrirlo:

Sistema Cómo
Windows (PowerShell) setx MCP_TIMEOUT 60000 y abrí una terminal nueva
macOS / Linux export MCP_TIMEOUT=60000 en tu perfil de shell

MCP_TIMEOUT está en milisegundos. Luego reiniciá el asistente.


6. Paso 4 — Preparar el profile con las credenciales

Las credenciales de la app no van en ningún archivo del repositorio: los tests las leen como GlobalVariable del execution profile de Katalon. El MCP no puede escribir profiles, así que las cargás vos, a mano:

  1. En Katalon Studio: Tests Explorer → Profiles → <tu profile> (por defecto default).
  2. Add y creá solo las que correspondan a tu configuración:
Variable Cuándo se necesita
BASE_URL Siempre (es environment.base_url)
APP_USER y APP_PASSWORD Con auth: basic_auth
API_TOKEN_* Con auth: api_token
QA_AUTH_STATE_PATH Opcional. Ruta absoluta a la sesión guardada del repo (ver sección 7)
  1. Guardá con Ctrl+S. Para APP_PASSWORD, usá Tools → Encrypt Text y pegá el valor encriptado.

Si falta alguna variable, lippia-neo-run-and-heal no ejecuta y te avisa cuáles faltan (solo los nombres, nunca los valores). Sin ellas todos los tests fallarían con MissingPropertyException: No such property: <VAR> for class: internal.GlobalVariable.


7. La sesión guardada con Katalon

Cuando la app exige login (auth distinto de none), NEO guarda una sola sesión y la comparten todas las herramientas: el MCP de Playwright, Playwright, Cypress, Lippia y Katalon. La sesión queda en paths.auth_state_file (por defecto .auth/auth-state.json, ignorada por git).

Cómo se arma Qué pasa
google_sso (SSO, 2FA, captcha) Una persona hace el login a mano, una vez, con la skill lippia-neo-setup-authenticated-session. NEO nunca automatiza ni observa ese login
basic_auth Con session.on_expired: refresh, el primer test case se loguea con APP_USER / APP_PASSWORD y guarda la sesión; el resto la restaura. Con fail, corta y no se loguea

En el proyecto de Katalon, esto se materializa en dos piezas que crea lippia-neo-generate-test-suite:

  • lippia_neo.SavedSession: un keyword en Groovy que carga la sesión en el navegador de Katalon y, con basic_auth, la guarda después del login.
  • Common/open_authenticated_app: una precondición compartida que llaman todos los tests (WebUI.callTestCase). Según auth, navega, hace el login o restaura la sesión.

Qué pasa cuando la sesión vence (session.on_expired)

Valor Qué hace
fail (por defecto) Corta con un mensaje: recapturar la sesión (google_sso) o revisar las credenciales (basic_auth). Nunca intenta loguearse
refresh con google_sso La precondición espera a que te loguees a mano en el navegador de Katalon (hasta session.refresh_timeout_s, 300 s por defecto) y guarda la sesión nueva. Cuando se abra Chrome, iniciá sesión vos
refresh con basic_auth La precondición se loguea sola con APP_USER / APP_PASSWORD y guarda la sesión nueva. No hace falta intervenir

Con refresh y google_sso, el navegador tiene que ser visible: si katalon.browser es *_HEADLESS, NEO usa la variante visible para esa corrida y te lo avisa.

Compartir la sesión con Playwright

Si el proyecto de Katalon no está dentro del repositorio de pruebas, definí QA_AUTH_STATE_PATH (ruta absoluta) en el profile para que Katalon y Playwright usen el mismo archivo. Si no, la sesión queda en .auth/ dentro del proyecto de Katalon: agregala al .gitignore de ese proyecto.

Es información sensible. El archivo de sesión tiene tokens válidos. NEO no lo abre ni lo muestra, y vos tampoco deberías subirlo a git.

La misma sesión también la usa el MCP de Playwright al explorar: ver Sesión guardada en Playwright MCP.


8. Reglas de ejecución que conviene conocer

Regla Qué significa para vos
Una ejecución a la vez Katalon no corre en paralelo: los test cases de una corrida van en serie
Tiempos executeTest espera hasta 110 s. Para una suite, NEO consulta el estado cada tanto, con un tope de 15 minutos
No se modifica lo que ya existe Antes de crear un test case, NEO busca duplicados (por tags <US-ID> y tc<NNN>, por nombre y por contenido). Si ya existe, no lo crea y te informa; nunca modifica un test existente
Se reusa el Object Repository Antes de crear un test object, busca en todo el repositorio uno que apunte al mismo elemento con un locator estable (incluidos los que grabaste con el Web Recorder o el Spy)
Credenciales siempre como GlobalVariable Nunca como literales en el script
Locators solo en el Object Repository El script usa findTestObject(...), nunca un XPath o CSS suelto
CI Ejecutar fuera de Katalon Studio requiere Katalon Runtime Engine (katalonc) con licencia. lippia-neo-bootstrap-ci todavía no genera jobs de Katalon

9. Verificar que funciona

  1. Abrí Katalon Studio con el proyecto correcto y el MCP server habilitado.
  2. Reiniciá el asistente (o recargá la ventana).
  3. Abrí la lista de servidores (/mcp en Claude Code o Codex, MCP: List Servers en VS Code…) y confirmá que katalon-studio figura conectado. Puede tardar unos 30 segundos.
  4. Probalo:
Con el MCP de Katalon, listá los test suites del proyecto abierto.

Es la misma verificación que hace lippia-neo-run-and-heal (listEntityFiles sobre TEST_SUITE). Si responde, la conexión está bien.


10. Problemas comunes (y qué hacer)

Lo que ves Por qué puede pasar Qué hacer
katalon-studio figura como Failed o timeout El handshake inicial tarda ~30 s, o Katalon Studio no está abierto Abrir Katalon Studio y definir MCP_TIMEOUT=60000; reiniciar el asistente
Katalon Studio no está abierto o su server MCP no está conectado lippia-neo-run-and-heal no pudo listar los test suites Abrir Katalon Studio con el proyecto de la suite y revisar la conexión
Connection refused / no responde La URL o el puerto no son los de tu instalación Copiar de nuevo la URL desde la configuración del MCP en Katalon Studio
401 / no autorizado El server pide token y falta, o es incorrecto Agregar headers.Authorization: Bearer <token>. Si no pide token, quitar headers
El MCP funciona, pero crea los tests en otro proyecto El MCP opera sobre el proyecto abierto Abrir el proyecto correcto en Katalon Studio y volver a ejecutar
MissingPropertyException: No such property: <VAR> for class: internal.GlobalVariable Falta una variable en el execution profile Cargarla en Tests Explorer → Profiles (sección 6)
Se pide login en cada test case save y restore usan archivos de sesión distintos Revisar QA_AUTH_STATE_PATH en el profile (o como variable de entorno)
No se completó el login manual Con session.on_expired: refresh no se terminó el login a tiempo Volver a correr y loguearse dentro de session.refresh_timeout_s
El navegador no es visible y no hay dónde loguearse katalon.browser es *_HEADLESS Usar el navegador visible para esa corrida
katalon.mcp_server no coincide con el servidor Se renombró el servidor en .mcp.json Poner el mismo nombre en qa-stack.yaml
El asistente pierde Katalon tras cambiar el .mcp.json Los servidores se cargan al arrancar Reiniciar el asistente