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
- Abrí Katalon Studio y el proyecto donde van a vivir los tests.
- Entrá a la configuración del MCP server de Katalon Studio y habilitalo.
- 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-stackpregunta todo esto cuando elegís Katalon como framework: la URL del servidor, si pide token, las carpetas, el navegador y el profile. No te preguntatests_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
NEOo lo renombrás, acordate de actualizarkatalon.mcp_serverenqa-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:
- En Katalon Studio: Tests Explorer → Profiles →
<tu profile>(por defectodefault). - 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) |
- Guardá con
Ctrl+S. ParaAPP_PASSWORD, usá Tools → Encrypt Text y pegá el valor encriptado.
Si falta alguna variable,
lippia-neo-run-and-healno ejecuta y te avisa cuáles faltan (solo los nombres, nunca los valores). Sin ellas todos los tests fallarían conMissingPropertyException: 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, conbasic_auth, la guarda después del login.Common/open_authenticated_app: una precondición compartida que llaman todos los tests (WebUI.callTestCase). Segúnauth, 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.
NEOno 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
- Abrí Katalon Studio con el proyecto correcto y el MCP server habilitado.
- Reiniciá el asistente (o recargá la ventana).
- Abrí la lista de servidores (
/mcpen Claude Code o Codex, MCP: List Servers en VS Code…) y confirmá quekatalon-studiofigura conectado. Puede tardar unos 30 segundos. - 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 |