QA MCP

Servidor MCP para automatizar generación de artefactos de QA:

• tests API con Rest Assured (generateRestTests): Java + JUnit 5 + Rest-Assured, cubriendo todos los resultados de cada endpoint, con ejecución/feedback (runRestTests)

• tests E2E con Cypress (generateE2ETests) y ejecución/feedback (runE2ETests)

• documentación ETP en Excel (exportETPAsExcel) y Word (exportETPAsWord)

• informe de evidencias Rest Assured en Excel (exportRestTestsAsExcel)

• autocompletado de rf-cu.md (autoCompleteRfCu)

Usa mcp.config.json en la raíz del proyecto para localizar OpenAPI, frontend, rutas de salida y plantillas.

Generación de tests REST (generateRestTests)

Genera tests de integración Java + JUnit 5 + Rest-Assured guiados por LLM. Todo su comportamiento (reglas, convenciones y alcance) está definido en prompts/rest.md, configurable con prompts.rest en mcp.config.json.

• Entrada: el contrato openApi (se parsean todos los paths, parámetros, request bodies y todos los códigos de respuesta declarados) y el código real del backend (backend.root), del que se derivan rutas efectivas, context-path, validaciones, cuerpos de error de @ControllerAdvice, reglas de negocio (404/409) y seguridad (401/403).

• Cobertura: un @Test como mínimo por cada resultado posible de cada endpoint. El servidor calcula ese mínimo y lo verifica.

• Salida: un fichero *ApiTest.java por grupo funcional (tag de OpenAPI o primer segmento de la ruta) dentro de restTests, en el paquete deducido del backend (<paquete-raíz>.api).

• Alcance cerrado: la tool solo crea o modifica tests bajo restTests; nunca toca el código de la aplicación ni añade dependencias.

• Convención obligatoria: cada @Test (y cada clase/@Nested) lleva un @DisplayName explícito en español, descriptivo y funcional. Está prohibida la generación automática de nombres (@DisplayNameGeneration, ReplaceUnderscores). Ese @DisplayName es exactamente lo que el ETP Excel exporta como «Objetivo Funcionalidad».

• Validación del contrato: antes de persistir cada fichero, el servidor comprueba @DisplayName explícito en todos los tests, ausencia de @Disabled/TODO, uso real de Rest-Assured/JUnit 5 y cobertura de cada código de estado; si falla, reintenta la generación con el diagnóstico (maxIterations, 3 por defecto).

• Ejecución iterativa hasta verde: cumplido el contrato estático, el servidor ejecuta la clase contra el backend (wrapper mvnw/gradlew detectado, o restRunCommand), lee el informe JUnit XML de Surefire/Failsafe/Gradle y persiste el estado de cada método @Test. Si algo falla, reinyecta al modelo la salida real (errores de compilación y detalle de los tests en rojo) y vuelve a generar, hasta verde o agotar maxIterations. Una clase sólo queda verde si cumple el contrato y todos sus @Test pasan; un build que no ejecuta ningún test nunca cuenta como verde.

• Reactores multi-módulo: Surefire/Gradle escriben el informe en <módulo>/target/surefire-reports, no en la raíz del proyecto. El servidor busca el XML en todo el árbol (raíz y submódulos, en anchura) y se queda con el más reciente posterior al arranque de la ejecución. Sin esto, un build multi-módulo con todos sus tests en verde se leería como «no ejecutado» y la clase nunca podría ponerse verde. También se contempla que la clase esté en el paquete por defecto, en cuyo caso el XML se llama TEST-<Clase>.xml sin prefijo de paquete.

• Estado persistido: restTests/.qa-mcp-rest-status.json guarda por clase green, contractVersion, attempts, validationErrors, totals y la lista de tests con passed/skipped y la causa del fallo. Las clases ya verdes se omiten en llamadas posteriores (skipGreen: false para forzar su regeneración).

• Log por clase: restTests/<Clase>.log, sobrescrito en cada iteración, con el comando lanzado, el resultado por test, la salida completa del build sin truncar, el resumen inyectado al modelo y el prompt de corrección. Permite distinguir si el problema está en la ejecución real o en el prompt.

• Build bloqueado por otra clase que no compila: Maven/Gradle compilan todo src/test/java antes de aplicar el filtro -Dtest=, así que un *ApiTest.java roto impide ejecutar a todas las demás clases. El servidor atribuye cada error de compilación a su fichero y, si el culpable es otro test bajo restTests, lo repara (con sampling, reescribiéndolo hasta maxCompileRepairRounds, 3 por defecto; sin sampling, devolviendo sus errores y un PROMPT DE REPARACIÓN por fichero) en vez de quemar intentos reescribiendo la clase en curso, que no es la que rompe el build. La reparación debe conservar todos los @Test y @DisplayName: está prohibido borrar el fichero, comentar tests o marcarlos @Disabled para esquivar el error. Los errores de compilación del código de la aplicación nunca se tocan.

• Verificadores de formato desactivados: los tests generados son evidencias, no código de producto. Un spotless:check (o Checkstyle) enganchado al ciclo del build aborta antes de Surefire, así que la clase no llega a ejecutarse y jamás puede ponerse en verde por un salto de línea. El servidor añade -Dspotless.check.skip=true -Dcheckstyle.skip=true (Maven) o -x spotlessCheck (Gradle) a la invocación —también a un restRunCommand propio— sin modificar la configuración del proyecto. Si necesitas los ficheros formateados, ejecuta mvn spotless:apply aparte.

• Fallos de entorno: si el build no existe, no hay dependencias, el proxy corporativo devuelve HTTP 407 o el backend está caído, se detecta como error de ENTORNO, se corta el bucle y se devuelve un diagnóstico accionable en vez de quemar intentos reescribiendo un test que no es el problema. Un error de compilación nunca se clasifica como fallo de entorno: lo provoca un .java generado por la tool y se arregla reescribiéndolo.

• Proxy corporativo (HTTP 407): ante un Proxy Authentication Required al resolver dependencias, el servidor reintenta automáticamente en modo offline (-o / --offline) contra el repositorio local. Si aun así falla, indica cómo resolverlo: credenciales del proxy en ~/.m2/settings.xml, variables HTTP_PROXY/HTTPS_PROXY/NO_PROXY (vía restEnv), o restOffline: true si ~/.m2 ya tiene las dependencias.

• Parámetros: tags (limita a uno o varios grupos de endpoints), promptOverride, maxIterations, assisted, validateOnly, runTests (false genera y valida sin ejecutar), runTimeoutMs, skipGreen y maxCompileRepairRounds.

• Sin sampling (Roo Code, Cline, opencode…): devuelve el prompt completo, las rutas exactas de los ficheros y el índice del código de backend para que el agente los abra y escriba los tests sólo de las clases que aún no están en verde; después debe llamar a runRestTests para ejecutarlas e iterar corrección→ejecución hasta que todas pasen.

Bucle de auto-corrección REST (runRestTests)

Equivalente a runE2ETests para la capa API: aunque el cliente no tenga sampling, el servidor sí puede ejecutar los tests y devolver el resultado como feedback. Trabaja una clase en curso cada vez (la primera que no está en verde) y no avanza hasta que pasa:

1. generateRestTests → escribe los *ApiTest.java pendientes en sus rutas exactas.

2. runRestTests → el servidor ejecuta esa clase, persiste green y el estado de cada @Test en .qa-mcp-rest-status.json, y escribe su .log. Si pasa, indica avanzar; si falla, devuelve la salida real del build + un PROMPT DE CORRECCIÓN.

3. El agente reescribe el fichero y vuelve a llamar a runRestTests (misma clase) hasta que pase.

Si el build ni siquiera compila por culpa de otras clases de test, runRestTests no pide corregir la clase en curso: lista los ficheros que no compilan con sus errores (- [línea,columna] mensaje) y entrega un PROMPT DE REPARACIÓN por fichero, con la orden de repararlos y volver a llamar. Así el bucle nunca se queda atascado corrigiendo una clase que no es la culpable.

Cada respuesta termina con una SIGUIENTE_ACCIÓN_OBLIGATORIA concreta para que el agente no dé por cerrado el bucle tras un solo intento. Como todo el estado vive en disco, el ciclo es reanudable desde una tarea nueva con contexto limpio: el servidor reengancha la primera clase no verde.

Parámetros de runRestTests: tags, promptOverride, runTimeoutMs, allFixes (ejecuta todas las clases pendientes en vez de parar en la primera que falla) y skipGreen.

Ajustes opcionales de ejecución en mcp.config.json: backend.mvn.path y backend.java.path (Maven y JDK concretos, ver abajo), restRunCommand (comando base si no vale el wrapper detectado), restEnv (variables de entorno, p. ej. HTTP_PROXY/NO_PROXY), restTimeoutMs (timeout por clase, 15 min por defecto) y restOffline (true fuerza -o/--offline desde el primer intento; útil detrás de un proxy que exige autenticación).

Maven y JDK a usar (backend.mvn.path / backend.java.path)

Cuando el Maven o el Java del PATH no son los correctos (varias versiones instaladas, Maven corporativo con su settings.xml y proxy ya configurados), se declaran explícitamente en mcp.config.json:

"backend": {
  "root": "./backend",
  "language": "java",
  "build": "maven",
  "mvn": { "path": "C:\\apache-maven-3.9.6" },
  "java": { "path": "C:\\Program Files\\Java\\jdk-17" }
}

• backend.mvn.path: admite el ejecutable (...\bin\mvn.cmd), su carpeta bin o el directorio de instalación. Tiene prioridad sobre el wrapper mvnw del repositorio y sobre el mvn del PATH.

• backend.java.path: admite el home del JDK, su carpeta bin o el ejecutable java. Se exporta como JAVA_HOME y su bin se antepone al PATH de la ejecución.

• Ambas pueden ser relativas a mcp.config.json. Si la ruta no existe o no contiene el binario esperado, se reporta como fallo de ENTORNO con el motivo concreto, sin reescribir ningún test.

Para generateE2ETests, la generación es genérica y guiada por LLM (MCP sampling): para cada CU, el modelo del cliente genera un spec Cypress real (con cy.intercept, interacción con selectores derivados del código frontend y aserciones), no un esqueleto de cy.log. Cada CU se genera en su propio fichero .cy.js (un describe del RF con un único it del CU), de modo que cada ejecución de Cypress corre solo ese CU y el bucle itera más rápido y de forma aislada. Antes de empezar, la tool consulta .qa-mcp-e2e-status.json: conserva y omite los CU cuyo spec existe, tiene green: true y fue validado con la versión actual del contrato E2E; genera los specs que faltan y ejecuta/repara los existentes que aún no están en verde. Si cambia un contrato incompatible (por ejemplo, la forma segura de escribir inputs), los verdes antiguos se revocan y se regeneran una sola vez.

• Puedes definir las reglas de estilo/interacción con prompts.e2e en mcp.config.json (opcional). Si no se indica, usa prompts/e2e.md del servidor MCP.

• También puedes pasar promptOverride en la invocación de la tool para ajustar una ejecución puntual.

• Requiere un cliente MCP que soporte sampling (p. ej. VS Code Copilot 1.102+). Si el cliente no soporta sampling (Roo Code, Cline, opencode…), la tool pasa a modo asistido (ver más abajo).

Modo asistido (sin MCP sampling): si el cliente conectado no declara la capacidad sampling, generateE2ETests y autoCompleteRfCu no pueden pedir la generación al modelo por sí mismas. En su lugar:

• generateE2ETests prepara el entorno Cypress (helpers, config y baseline) y trabaja con UN CU no verde por llamada. Si su spec no existe, devuelve el prompt de generación y la ruta de salida exacta; si ya existe, indica que debe ejecutarse con runE2ETests para validarlo o repararlo. En vez de embeber el código frontend (que desborda el contexto del cliente), el prompt lista las rutas de los ficheros relevantes para que el agente los abra con sus propias herramientas de fichero.

• autoCompleteRfCu devuelve el prompt y la ruta de salida para que el agente genere y escriba rf-cu.md.

• El modo asistido se activa automáticamente al detectar la falta de sampling. También puedes forzarlo con el parámetro assisted: true en la invocación.

Decenas de CU sin llamadas ni prompts manuales: sin MCP sampling, el servidor no puede generar por sí solo el contenido de los specs, por lo que técnicamente el flujo necesita varias llamadas MCP (generateE2ETests → escribir spec → runE2ETests → corregir/volver a ejecutar → siguiente CU). El usuario, sin embargo, solo tiene que invocar generateE2ETests una vez. La descripción de la tool y todas sus respuestas asistidas ya incorporan un MANDATO DE AUTOCONTINUACIÓN para que el agente escriba/corrija los specs y encadene las llamadas necesarias sin pedir confirmación ni detenerse entre CU. .qa-mcp-e2e-status.json conserva el progreso. Si el cliente no puede encadenar tools, será necesario usar un orquestador; esa es una limitación del cliente, no hace falta suplirla con un prompt del usuario.

Invocación inicial en modo asistido (también se activa automáticamente cuando no hay sampling):

{
  "assisted": true
}

Bucle de auto-corrección en modo asistido (runE2ETests), CU a CU hasta verde: aunque el cliente no tenga sampling, el servidor sí puede ejecutar Cypress y devolver el resultado como feedback. El flujo trabaja un CU en curso cada vez (el primero que no está en verde) y no avanza al siguiente hasta que el actual pasa:

1. generateE2ETests (modo asistido) → devuelve el prompt de generación del CU en curso (si su .cy.js no existe). El agente lo escribe.

2. runE2ETests → el servidor ejecuta SOLO ese CU (limpiando el baseline entre intentos). Si pasa, lo marca en verde (estado persistido en disco) y te indica avanzar; si falla, devuelve la salida real de Cypress + un PROMPT DE CORRECCIÓN.

3. El agente aplica el prompt reescribiendo el fichero y vuelve a llamar a runE2ETests (mismo CU) hasta que pase.

4. Con el CU en verde, se llama de nuevo a generateE2ETests para el siguiente CU. Repetir hasta que todos estén en verde.

Contexto limpio por CU: todo el estado vive en disco (los .cy.js + .qa-mcp-e2e-status.json con los CU en verde), no en la conversación del cliente. Por eso el bucle es reanudable: si el cliente admite subtasks, el mandato integrado le indica que delegue automáticamente el siguiente CU con contexto limpio; si no, continúa en la tarea actual. El usuario no tiene que iniciar otra tarea ni repetir la instrucción. El servidor detecta el siguiente CU pendiente automáticamente y cada llamada emite solo el CU en curso (frontend como lista de rutas, no código embebido) para minimizar el footprint.

Automatizar el contexto limpio con subtasks (Roo Code / Orchestrator): en clientes con orquestación de subtasks (Boomerang / Orchestrator, p. ej. Roo Code), no hace falta iniciar la tarea nueva a mano. Cada respuesta de generateE2ETests / runE2ETests incluye una SEÑAL DE SUBTASK con un campo QUEDA_TRABAJO (sí/no) y la instrucción de si seguir en el mismo subtask o delegar el siguiente paso en un new_task con contexto limpio. Como todo el estado está en disco, cada subtask arranca limpio y el servidor resuelve solo el CU pendiente.

Higiene de contexto en el bucle de corrección: el contexto se llena sobre todo al iterar correcciones dentro de un mismo CU (cada vuelta reinyecta spec + salida de Cypress + reglas, y el agente reescribe el fichero entero). Por eso se delega un subtask por CU (contexto limpio para cada CU), y dentro de ese subtask el agente itera corrección→runE2ETests hasta que ESE CU pase. Si aun así el contexto de un CU muy largo se llena, hay un offload OPCIONAL: cierra la tarea y deja que una tarea/subtask NUEVA reanude EL MISMO CU (el .cy.js y el estado quedan en disco; el servidor reengancha el primer CU no verde). El offload es un alivio puntual, no un fin del bucle: nunca cierres un CU en rojo dándolo por terminado.

IMPORTANTE — modos de Roo y acceso MCP: el modo Orchestrator NO tiene acceso directo a tools MCP (solo delega vía new_task); si le pides que llame a autoCompleteRfCu/generateE2ETests directamente, responderá que "no es una tool reconocida". La llamada a la tool debe ocurrir dentro del subtask, en un modo con el grupo mcp y edit. Usa modo Code (mode: "code") para los subtasks: como Roo no soporta sampling, las tools corren en modo asistido y el agente debe escribir los ficheros (rf-cu.md, .cy.js), así que hace falta editar. (Architect solo edita markdown; Ask no edita.)

Prompt listo para pegar en la tarea padre (Roo en modo Orchestrator):

Eres el orquestador del bucle E2E de qa-mcp. Objetivo: dejar TODOS los CU en verde.
Delega UN subtask por CU (contexto limpio por CU); el estado vive en disco y el
servidor reengancha el CU pendiente en cada subtask.

Repite este ciclo:
1. Crea un new_task EN MODO CODE (mode: "code") con contexto limpio y este objetivo
   (el modo Code es obligatorio: tiene acceso a las tools MCP y puede escribir ficheros;
   tú, como Orchestrator, NO puedes llamar a las tools qa-mcp directamente):
   "Deja EN VERDE el CU pendiente de qa-mcp (se resuelve solo desde disco):
    - Si no tiene spec: llama a generateE2ETests, escribe el .cy.js en la ruta EXACTA
      indicada y llama a runE2ETests.
    - Si ya tiene spec: llama a runE2ETests.
    Si FALLA, aplica el PROMPT DE CORRECCIÓN (reescribe el .cy.js completo) y VUELVE A
    LLAMAR a runE2ETests. Repite corrección→runE2ETests hasta que ESTE CU pase. NO cierres
    la tarea con el CU en rojo. (Solo si el contexto se te llena, puedes cerrar y dejar
    que otra tarea reanude ESTE MISMO CU desde disco.) Cuando pase, termina con
    attempt_completion indicando 'CU en verde' y copia la línea QUEDA_TRABAJO de la
    SEÑAL DE SUBTASK."
2. Cuando el subtask termine, lee su resultado (la línea QUEDA_TRABAJO).
3. Si QUEDA_TRABAJO: sí (siguiente CU), vuelve al paso 1.
4. Si QUEDA_TRABAJO: no (TODOS los CU en verde), termina.

No generes ni ejecutes tests tú mismo: delega SIEMPRE cada CU en un subtask en modo
Code con contexto limpio.

En clientes CON sampling no hace falta ni el bucle manual ni los subtasks: generateE2ETests reanuda el estado de .qa-mcp-e2e-status.json, genera lo que falta y ejecuta/repara los CU no verdes por sí misma.

Ejecución iterativa (auto-fix): por defecto, generateE2ETests ejecuta Cypress sobre cada CU pendiente. Si el spec no existe, primero lo genera; si ya existe, no está verde y cumple el contrato actual, lo conserva y lo ejecuta directamente. Si usa una interacción de input insegura o le faltan evidencias, primero solicita su reparación al modelo. Cuando Cypress falla, pide al modelo que corrija el spec usando la salida de error real, repitiendo hasta que pase o se agoten los intentos. Cada resultado se persiste como green: true/false y contractVersion en .qa-mcp-e2e-status.json. Parámetros de la tool:

• runTests (bool, por defecto true): ejecuta Cypress e itera. Ponlo a false para solo generar.

• maxIterations (número, por defecto 3): intentos máximos por CU (1 generación + N-1 correcciones).

• rf (string, opcional): limita estrictamente todo el ciclo a un único RF, p. ej. "RF-3". Es la opción recomendada para ejecutar una tarea/contexto independiente por RF.

• rfFilter (array de ids, opcional): compatibilidad para limitar a varios RF, p. ej. ["RF-01","RF-03"]. No se combina con rf.

• promptOverride (string, opcional). Entre cada intento se limpian las claves de baseline del CU en curso para que la re-ejecución vuelva a autocapturar. El contrato v2 separa acciones humanas y operaciones técnicas: una acción humana puede agrupar varios controles relacionados, pero Cypress ejecuta y captura cada operación de forma independiente (rf1_cu1_01.png, rf1_cu1_02.png, etc.). Si Cypress reintenta un test, el MCP reconoce (attempt N), exige que el último intento tenga el juego completo y normaliza los nombres sin mezclar intentos. Todas las evidencias deben medir 1920×1080 con DPR 1 (100 %). Los set-control usan setDocumentedControl, que aplica el dato exacto, espera re-renderizados, resuelve controles nativos, centra el elemento, comprueba oclusiones, verifica el estado visible y captura el PNG. Las demás operaciones usan cy.screenshot() tras completarse. Un CU sólo queda verde con spec vigente, contrato coherente, baseline correcto y todas sus evidencias Full HD.

Un contexto por RF

Para generar únicamente los tests de un requisito funcional:

{
  "rf": "RF-3"
}

La tool sólo considera los CU de RF-3: no genera, ejecuta, repara ni cambia el estado de otros RF. En modo asistido, todas las respuestas incorporan el mismo argumento en las llamadas posteriores (runE2ETests({ "rf": "RF-3" }) y generateE2ETests({ "rf": "RF-3" })) y ordenan continuar en la misma tarea mientras quede algún CU de ese RF en rojo. Cada respuesta termina además con una SIGUIENTE_ACCIÓN_OBLIGATORIA concreta para evitar que el agente dé por finalizado el bucle después de una sola ejecución. Sólo cuando todos sus CU están verdes, la respuesta termina el ámbito y ordena no saltar a otro RF. Se puede entonces abrir una tarea o contexto nuevo e invocar la tool con el siguiente RF; el progreso anterior se recupera desde disco.

Related MCP server: API Tester MCP

Exportación del ETP a Excel

exportETPAsExcel genera un libro con la misma tabla y estilos de la plantilla configurada en evidence.excelTemplate. Si esa ruta no existe en el proyecto consumidor, usa automáticamente el templates/evidences.xlsx empaquetado con qa-mcp. Las filas de ejemplo que contenga la plantilla se eliminan y se sustituyen por los tests reales disponibles:

• una fila REST-NNN por cada método Java anotado con @Test encontrado bajo restTests;

• una fila E2E-NNN por cada it() o test() encontrado en los .cy.js bajo e2eTests;

• RF, CU, objetivo y acciones se obtienen de rf-cu.md cuando el test puede relacionarse con él; en las filas REST, el «Objetivo Funcionalidad» es el @DisplayName literal del método @Test;

• las filas muestran primero todos los casos REST y después todos los E2E; dentro de cada bloque se ordenan por R. Funcional y luego por Nombre (CU), usando orden natural para los identificadores numéricos;

• los E2E usan .qa-mcp-e2e-status.json y su .log para mostrar OK, KO, PASS o FAIL;

• los Rest Assured usan .qa-mcp-rest-status.json y su .log para mostrar OK, KO u OMITIDO; si la clase aún no se ha ejecutado, aparecen como NO EJECUTADO;

• it.skip y @Disabled se muestran como OMITIDO.

La tool acepta opcionalmente outputFileName; si no se indica, escribe ETP.xlsx dentro de evidence.output. Funciona si solo existen tests REST, solo E2E o ambos. No ejecuta los tests durante la exportación: refleja los resultados persistidos que estén disponibles. Si no encuentra ningún @Test, it() o test(), devuelve un error claro en vez de crear un ETP vacío.

Informe de evidencias Rest Assured (exportRestTestsAsExcel)

exportRestTestsAsExcel genera un informe Excel exclusivo de los tests REST generados previamente con generateRestTests, reutilizando la misma tabla y estilos de evidence.excelTemplate (o del templates/evidences.xlsx empaquetado). Escribe una fila REST-NNN por cada método @Test encontrado bajo restTests:

• R. Funcional, Nombre y Objetivo Funcionalidad: el @DisplayName literal del método (si falta, se humaniza el nombre Java);

• Aplicacion: el proyecto derivado de backend.root, con el sufijo BACKEND;

• Requisitos Previos / Restricciones: Entorno: <DES|PRE|PRO|INT|LOCAL> | Inicio: <fecha de ejecución>; el entorno se deriva del host realmente invocado (o del servers de OpenAPI) y la hora de inicio, del informe de ejecución;

• Acciones: la petición real, con el formato GET <url> => <código>. Si hay log de Rest Assured en el informe se usa la URI y el status reales; si no, se reconstruyen desde el propio test (get/post/..., queryParam, pathParam, constantes String de la clase y statusCode(...));

• Resultado: OK, KO, OMITIDO (@Disabled/skipped) o NO EJECUTADO;

• Resultado reproducido: PASS | ..., FAIL | ... | <mensaje del fallo>, SKIPPED | ... o PENDIENTE | <fichero>#<método>.

Los resultados provienen de una ejecución local previa: la tool no ejecuta los tests, sólo lee los informes JUnit ya existentes (surefire-reports, failsafe-reports o build/test-results/**) bajo backend.root, quedándose con la ejecución más reciente de cada método. Si no encuentra ningún informe, exporta igualmente el inventario completo con todos los casos como NO EJECUTADO y lo advierte en la respuesta.

Detalles que evitan informes incompletos o engañosos:

• Sólo las clases generadas: restTests suele ser el src/test/java del módulo, compartido con los tests unitarios escritos a mano. El informe se limita a las clases registradas en .qa-mcp-rest-status.json, de modo que no se cuelan tests ajenos (que además aparecerían con nombres en inglés, sin @DisplayName en castellano).

• Anotaciones multilínea: el formateador (google-java-format/Spotless) parte los @DisplayName largos en varias líneas. El parseo recorre las anotaciones con paréntesis equilibrados en vez de con un patrón de una línea, así que no se pierde ningún @Test.

• Clases @Nested: Surefire escribe en classname el @DisplayName del grupo (p. ej. GET /destinations), no el nombre Java. El emparejamiento usa el nombre de la suite, que sí es la clase de nivel superior; si no, todos los tests anidados saldrían como NO EJECUTADO pese a haberse ejecutado.

• URL base parametrizada: los tests generados usan System.getProperty("api.base.uri", "https://…"). Se resuelve el valor por defecto y se respeta que la ruta ya sea absoluta; sin ello, la columna Acciones mostraría «petición no deducible del test» en casi todas las filas.

Parámetros (todos opcionales):

{
  "outputPath": "C:/Users/usuario/Downloads/restassured-evidences.xlsx"
}

Si no existe ningún método @Test bajo restTests, devuelve un error claro en vez de generar un informe vacío.

Exportación del ETP a Word

exportETPAsWord construye el documento a partir de rf-cu.md: crea un encabezado de nivel 1 por cada RF y, dentro de él, un encabezado de nivel 2 por cada CU. Sólo muestra las acciones para ejecución manual; nunca exporta componentes, selectores ni instrucciones Cypress. Bajo cada acción agrupa uno o varios PNG (rfx_cuy_NN.png), uno por operación técnica. Los RF, CU y acciones siguen orden natural.

El Word sólo se exporta si todos los CU están en verde y existe una captura PNG válida por cada operación. Si falta alguna evidencia, la tool devuelve un error con los CU y ficheros pendientes en vez de generar un documento incompleto. Ejecuta antes generateE2ETests hasta completar el conjunto.

Para autoCompleteRfCu, la generación es genérica y guiada por LLM (no usa plantillas ni heurísticas de dominio) y es UI-first: los RF/CU describen lo que el usuario puede reproducir DESDE LA UI, no la API completa.

• Con frontend.root configurado (modo UI-first): los RF se derivan de lo que la UI expone (rutas de appRouting, componentes/pantallas y acciones que el usuario puede disparar) y los CU son los flujos concretos ejercitables desde la interfaz. OpenAPI se usa solo como referencia para entender el comportamiento, no como checklist de cobertura: no se crea un RF por endpoint ni se prueban casos que la UI no permite. La cobertura exhaustiva de la API es tarea de generateRestTests.

• Sin frontend.root (modo fallback OpenAPI-first): frontend.root es opcional; si no se define, no hay UI que analizar y los RF se infieren directamente de los endpoints de OpenAPI (un RF por operación/funcionalidad relevante), con CU a nivel de comportamiento esperado del endpoint.

• Los CU los estima el modelo del cliente analizando el código frontend real (componentes, plantillas, servicios), vía MCP sampling (sampling/createMessage).

• Requiere un cliente MCP que soporte sampling (p. ej. VS Code Copilot 1.102+). Sin sampling, la tool devuelve el prompt para que el agente del cliente genere y escriba rf-cu.md; después debe llamar a autoCompleteRfCu con validateOnly: true y corregir el documento hasta que el servidor lo acepte.

• El prompt de instrucciones está externalizado en prompts/rfcu.md (configurable con prompts.rfcu en mcp.config.json, opcional). Si no se indica, usa el prompts/rfcu.md del servidor MCP.

• Si ya existe un rf-cu.md parcial, se completa respetando lo ya definido.

• Cada CU contiene dos proyecciones enlazadas: Acciones para ejecución manual, que alimenta Excel/Word y no expone selectores ni Cypress, y un Contrato de automatización estructurado que alimenta los tests. Una acción humana puede agrupar varias operaciones, pero cada operación conserva su selector, valor y evidencia independiente:

• Toda acción manual indica el valor literal de cada campo: fecha, hora, número, texto y texto visible exacto de cada dropdown. Expresiones como «una opción disponible», «un valor válido» o «indicar la fecha y la hora» se rechazan. Datepicker, timepicker y textarea se registran técnicamente como input; set-control sólo admite input, select y checkbox.

• El servidor extrae un inventario compacto de controles de todas las plantillas Angular y valida la cadena frontend → contrato técnico → acción humana. Un CU que pulse una acción de cálculo/consulta no puede omitir silenciosamente fecha, hora u otro control de su componente. En modo sampling se realizan hasta tres intentos de autocorrección antes de rechazar el documento.

- **CU-1: Cálculo nominal.**
  - **Acciones para ejecución manual:**
  1. Acceder al Simulador de facturas.
  2. Seleccionar «Org. Ventas de AASA» en Sociedad e introducir 180000 en Peso de la aeronave.
  3. Comprobar que Importe total muestra el importe calculado.
  - **Contrato de automatización:**
    - `A01.1` | acción `01` | operación `visit` | etiqueta `Simulador de facturas` | destino `/simulador-de-facturas`
    - `A02.1` | acción `02` | operación `set-control` | clave `sociedad` | tipo `select` | etiqueta `Sociedad` | selector `#sociedad` | valor `Org. Ventas de AASA`
    - `A02.2` | acción `02` | operación `set-control` | clave `pesoAeronave` | tipo `input` | etiqueta `Peso de la aeronave` | selector `#pesoAeronave input` | valor `180000`
    - `A03.1` | acción `03` | operación `verify` | etiqueta `Importe total` | selector `#importeTotal` | resultado `muestra el importe calculado`

Los documentos v1 siguen siendo legibles durante la migración, pero autoCompleteRfCu genera exclusivamente el contrato v2. Los CU verdes anteriores se revalidan porque cambia la relación entre acciones y evidencias.

La generación E2E incluye baseline autocapturable de snapshots genéricos (API/UI):

• asegura Cypress en el frontend (devDependencies.cypress) y scripts e2e / e2e:open

• asegura cypress.config.js y registra registerBaselineTasks(on) en setupNodeEvents (omite la inyección si tu config ya define las tareas readBaseline/writeBaseline, para no duplicarlas)

• usa e2eBaseUrl de mcp.config.json para cy.visit(...) en los specs generados

• crea cypress/support/e2e-baseline.js

• crea cypress/fixtures/e2e-baseline.json; si detecta snapshots contaminados con [object Event], elimina sólo esas entradas, revoca el verde de sus CU y las vuelve a capturar en la siguiente ejecución

• crea cypress/support/baseline-tasks.js con tareas readBaseline y writeBaseline

• crea cypress/support/e2e-helpers.js: librería compartida que incluye setDocumentedControl(clave, tipo, selector, valor, captura). Para input usa el setter nativo y eventos de la ventana AUT, evitando [object Event]; para select elige y verifica el texto visible exacto aunque Angular use [ngValue]; para checkbox establece y verifica true/false. En los tres casos vuelve a resolver el DOM tras el cambio, lleva el control al viewport, lo resalta, genera el PNG y registra el dato bajo inputs para compararlo con rf-cu.md.

Antes de lanzar Cypress, es necesario ejecutar:

set NO_PROXY=localhost,127.0.0.1,.aena.es

Además, en la configuración de proxy del sistema, la IP/host del proxy debe ser:

proxym.aena.es

sin incluir http://.

En cypress.config.js, registra esas tareas desde setupNodeEvents(on): const { registerBaselineTasks } = require('./cypress/support/baseline-tasks'); registerBaselineTasks(on);

Configuración en VS Code Copilot (MCP)

Configuración recomendada: por proyecto, en .vscode/mcp.json (no en configuración global de usuario).

En la raíz del proyecto que quieres documentar, crea .vscode/mcp.json con:

{
    "servers": {
        "qa-mcp": {
            "type": "stdio",
            "command": "C:\\Program Files\\nodejs\\node.exe",
            "args": ["C:\\EnvAena\\workspace\\qa-mcp\\dist\\index.js"],
            "cwd": "${workspaceFolder}"
        }
    }
}

Y elimina qa-mcp de la configuración global (MCP: Open User Configuration) para evitar conflictos entre proyectos.

Uso en un proyecto (guía rápida)

1. En el proyecto a documentar, crea/ajusta mcp.config.json en su raíz con rutas de backend, frontend, OpenAPI y salidas de tests/evidencias.

   • Para fijar el Maven y el JDK con los que se ejecutan los tests REST, añade backend.mvn.path y backend.java.path (ejecutable o directorio de instalación).

   • Si quieres controlar explícitamente de dónde derivar CU, añade appRouting con la ruta del app-routing.module.ts.

   • Para fijar la URL de ejecución E2E, añade e2eBaseUrl (ej. https://mi-entorno.aena.es).

   • Para ejecutar Cypress con un Node concreto (p. ej. instalación nvm), añade e2eNodePath con el directorio que contiene node.exe/npx (por defecto C:\Users\aena\AppData\Roaming\nvm\v24.16.0); se antepone al PATH de la ejecución de Cypress.

   • Para pasar variables de entorno a la ejecución de Cypress (proxy, etc.), añade e2eEnv como objeto clave/valor. Por defecto se establece NO_PROXY=localhost,127.0.0.1,.aena.es; puedes sobreescribirlo o añadir más variables. Ej.: "e2eEnv": { "NO_PROXY": "localhost,127.0.0.1,.aena.es", "HTTP_PROXY": "" }.

   • Para ver el navegador mientras Cypress ejecuta (modo headed), añade "e2eHeaded": true: el runner del MCP añade --headed, así que ves cada spec en un navegador visible (se cierra al terminar; NO se usa --no-exit para no colgar la llamada MCP). Opcionalmente "e2eBrowser": "chrome" (o edge/firefox/electron) para elegir navegador — debe estar instalado; por defecto Electron.

   ⚠️ Timeout MCP en Roo/Cline (MCP error -32001: Request timed out): una corrida real de Cypress (arranque + navegador + tests) supera con facilidad el timeout por defecto de 60 s de las llamadas MCP. Sube el timeout del servidor qa-mcp en la config MCP del cliente (Roo permite hasta 3600 s; recomendado 600). Es imprescindible además si la tool tiene que reparar la caché de Cypress (descarga del binario, ver abajo).

   ⚠️ Invalid or incompatible cached data (cachedDataRejected) al lanzar Cypress: es un error de ENTORNO (caché V8 del binario de Cypress corrupta/incompatible con la versión de Node), no del spec. runE2ETests/generateE2ETests lo detectan y reparan automáticamente una vez (cypress cache clear + install + verify) y reintentan; si persiste, devuelven un aviso claro (NO reescriben el test). Repara manualmente en el frontend, con el Node configurado en el PATH: npx cypress cache clear && npx cypress install && npx cypress verify. La reparación descarga el binario: asegura conectividad a download.cypress.io (revisa NO_PROXY) y sube el timeout MCP (arriba).

2. En VS Code Copilot, configura y arranca el servidor MCP qa-mcp con cwd apuntando a ese proyecto.

3. En Copilot Chat (modo Agent), ejecuta las tools según necesidad:

   • autoCompleteRfCu: completa rf-cu.md. Infiere RF desde OpenAPI + appRouting y estima los CU con el LLM del cliente (MCP sampling) analizando el frontend.

   • generateRestTests: genera tests de integración de API (Java + JUnit 5 + Rest-Assured) desde OpenAPI + código de backend, los ejecuta y persiste su estado por test.

   • runRestTests: ejecuta los tests REST ya escritos y devuelve el prompt de corrección para iterar hasta verde.

   • generateE2ETests: genera tests E2E (Cypress) y deja Cypress/baseline configurado en frontend.

   • exportETPAsExcel / exportETPAsWord: exportan el plan de pruebas con evidencias.

   • exportRestTestsAsExcel: exporta el informe de evidencias de los tests Rest Assured con el resultado de la última ejecución local.

4. Revisa los artefactos generados en:

   • tests API: ruta configurada en restTests

   • tests E2E: ruta configurada en e2eTests

   • evidencias: carpeta configurada en evidence.output

Nota: las tools usan siempre mcp.config.json desde la raíz del proyecto en el que se ejecuta el MCP (cwd).