El agente Cascade de Windsurf ejecuta un bucle: edita archivos, ejecuta comandos de terminal, lee la salida y decide qué hacer a continuación. Entonces, ¿por qué sus pruebas de API no están en ese bucle? Se encuentran en Apidog detrás de una GUI y se ejecutan cuando alguien recuerda hacer clic. Cascade nunca los toca.
La solución es un bloque de configuración. La CLI de Apidog es un paquete npm, apidog-cli, que ejecuta los escenarios de prueba que construyó en Apidog directamente desde una terminal. Una vez que la CLI está instalada y Cascade sabe que existe, Windsurf ejecuta un escenario de Apidog de la misma manera que ejecuta sus pruebas unitarias: dispara el comando, lee el código de salida, corrige el código si vuelve en rojo.
Si aún no ha instalado la CLI, hágalo primero. Cómo instalar la CLI de Apidog con un agente de codificación de IA explica la instalación de npm, la autenticación y la primera ejecución, con un agente realizando la escritura. Este artículo asume que apidog --version imprime un número y que su cuenta de Apidog está autenticada.
De qué Windsurf se trata
Windsurf es el IDE agéntico de Codeium, y su agente integrado se llama Cascade. Cascade se ejecuta localmente, lee su repositorio, edita archivos y ejecuta comandos de shell en su terminal integrada, pidiendo aprobación según su configuración de auto-ejecución. Este es el editor y su agente, no una extensión de navegador o un plugin de autocompletado.
Si aún no lo ha configurado, empiece con cómo descargar e instalar Windsurf. Una vez que Cascade esté abierto en su proyecto, puede enseñarle sobre la CLI de Apidog a través de su propio mecanismo de reglas, que convierte un “ejecutar mis pruebas” puntual en algo que Cascade busca por sí mismo.
Paso 1: Añadir una regla de Apidog a .windsurf/rules
Cascade lee las reglas del proyecto desde archivos Markdown antes de empezar a trabajar. Póngalas en un directorio .windsurf/rules/ en la raíz de su repositorio, una regla por archivo. Windsurf todavía lee un archivo .windsurfrules único heredado en la raíz del espacio de trabajo, y un ~/.codeium/windsurf/memories/global_rules.md global que se aplica a cada proyecto, pero para una instrucción por proyecto, el directorio .windsurf/rules/ es el lugar correcto. Esto está documentado en la referencia de reglas y memorias de Windsurf.
Cree .windsurf/rules/apidog.md con un bloque como este:
# Pruebas de API de Apidog
Este proyecto tiene escenarios de prueba de Apidog. Ejecútelos con la CLI de Apidog:
apidog run -t <scenario_id> -e <env_id> -r cli
Reglas:
- Use el comando exacto anterior; no invente banderas. Ejecute `apidog run --help` si no está seguro.
- `apidog run` sale con 0 cuando todas las aserciones pasan, y con un valor distinto de cero cuando alguna falla.
Considere la salida 0 como éxito y un valor distinto de cero como fallo. Informe el código de salida real.
- La máquina ya está autenticada a través de `apidog login`. Nunca añada un
token de acceso al comando ni lo incluya en este archivo.
- Después de cambiar código que afecta la API, ejecute el escenario y actúe según el resultado.
¿Por qué un archivo de reglas en lugar de un mensaje de chat? Un ID de escenario tecleado en el chat desaparece cuando la sesión termina. Uno en .windsurf/rules/apidog.md está ahí para cada compañero de equipo y cada sesión de Cascade de ahora en adelante. Persiste, está versionado en Git, y Cascade lo carga en contexto automáticamente al inicio.
Paso 2: Obtener el comando de Apidog
Los <scenario_id> y <env_id> en ese bloque no son marcadores de posición que deba adivinar. Apidog genera el comando exacto para usted.
Abra el escenario de prueba en Apidog, vaya a su pestaña CI/CD y copie el comando apidog run ya preparado. Ya tiene el ID de escenario correcto, el ID de entorno y las banderas de reportero rellenadas. Pegue ese comando en su .windsurf/rules/apidog.md en lugar de la línea de ejemplo. Ahora la regla contiene un comando que realmente funciona contra su proyecto, no una plantilla.
Para la anatomía completa de ese comando y cada bandera que acepta, consulte la referencia del comando apidog run.
Paso 3: Hacer que Cascade ejecute la prueba
Con la regla establecida, abra Cascade en su repositorio. Carga .windsurf/rules/apidog.md al iniciar, por lo que ya sabe que la CLI está ahí. Realice un cambio que afecte su API, o simplemente pídale que ejecute la verificación:
Ejecuta el escenario de Apidog y dime el código de salida.
Cascade emite el comando apidog run de su regla. Si se ejecuta sin una solicitud depende de su configuración de auto-ejecución. Windsurf ofrece cuatro niveles: Deshabilitado (cada comando necesita aprobación), Solo Lista de Permitidos (solo los comandos que coinciden con su lista de permitidos se ejecutan automáticamente), Auto (una decisión de juicio del modelo premium) y Turbo (todo se ejecuta automáticamente excepto los comandos denegados). En modo Turbo, un apidog run simple se ejecuta por sí mismo; en los modos más estrictos, Cascade se pausa y pregunta primero.
Si desea que apidog run se ejecute automáticamente sin relajar todas las restricciones, añádalo a su lista de permitidos. La configuración es windsurf.cascadeCommandsAllowList, accesible desde la Paleta de Comandos en Abrir Configuración; añada apidog y Cascade ejecutará el comando sin preguntar. La configuración de lista de denegación correspondiente es windsurf.cascadeCommandsDenyList, y la lista de denegación prevalece cuando un comando coincide con ambas. Ambas están cubiertas en la documentación del terminal de Windsurf. Un escenario de solo lectura contra un entorno de prueba es exactamente el tipo de comando seguro y dentro del espacio de trabajo para el que se construye una entrada en la lista de permitidos.
Paso 4: Leer el informe dentro de Windsurf
Cuando una ejecución se pone en rojo, el informe tiene la respuesta. El reportero -r cli imprime un resultado paso a paso y un resumen directamente en la terminal de Cascade: cada solicitud, cada aserción y cuál falló con el valor esperado frente al real. La aserción fallida nombra el campo o código de estado exacto, lo que suele ser suficiente para que Cascade encuentre la solución en su siguiente pasada.
Para un informe que pueda abrir en un navegador o entregar a un compañero de equipo, añada el reportero HTML:
apidog run -t <scenario_id> -e <env_id> -r cli,html
El reportero html escribe un archivo autocontenido en ./apidog-reports. Mantenga cli en la lista para que Cascade siga obteniendo la salida en línea que lee para decidir su siguiente paso. Para cada reportero, incluido el formato JUnit que los paneles de CI analizan, consulte la guía completa de la CLI de Apidog y cómo leer los informes de prueba de la CLI de Apidog.
Pruebas de Windsurf dentro de su propio bucle
El punto es lo que sucede cuando deja de preguntar y Cascade ejecuta el escenario por sí mismo porque la regla se lo indicó.
Imagine a Cascade editando un manejador que construye una respuesta de pago. Su bucle cambia. Edita el código, luego, en lugar de declararse victorioso, ejecuta su escenario de Apidog contra el entorno de prueba, lee el código de salida y actúa en consecuencia. Si es verde, avanza. Si es rojo, abre el informe, lee qué aserción falló (el código de estado, el campo faltante, el valor incorrecto), intenta una corrección y vuelve a ejecutar. La prueba de API se convierte en parte del mismo bucle de editar-probar-corregir a través del cual Cascade ya ejecuta sus pruebas unitarias. Usted escribió una regla y Cascade incorporó el comando en su forma de trabajo actual.
Este es el modelo de delegar-luego-verificar que hace seguro cualquier flujo de trabajo de agente. Cascade ejecuta el comando y lee el resultado; usted sigue creando escenarios visualmente en Apidog y verifica que el agente lea los códigos de salida honestamente. Para el patrón más amplio, consulte cómo usar agentes de IA para pruebas de API y el arnés de pruebas de IA de Apidog.
Verificar que Cascade realmente esté ejecutando la CLI
Los agentes informan éxitos que no obtuvieron, y Cascade no es una excepción. Tres verificaciones, en orden de cuán a menudo detectan problemas.
Primero, confirme que el comando se ejecutó. Cascade muestra los comandos que ejecuta y su salida en línea en la terminal. Busque la línea literal apidog run ... y un resultado debajo. Si Cascade dice que ejecutó las pruebas pero usted no ve el comando, resumió algo que nunca hizo. Pídale que lo ejecute de nuevo y muestre la salida sin procesar.
Segundo, confirme el código de salida, el que importa. Pregúntele directamente:
¿Cuál fue el código de salida de ese comando apidog run?
apidog run sale con 0 cuando todas las aserciones pasan y con un valor distinto de cero cuando algo falla. Ese comportamiento único permite a Cascade, o a una pipeline, tratar la ejecución como una puerta limpia. Cuando el texto de Cascade dice “pruebas pasaron” pero el código de salida es distinto de cero, el código de salida tiene razón.
Tercero, confirme que usó el escenario real. Si una ejecución falla con “escenario no encontrado”, es posible que Cascade haya inventado o recordado mal un ID. Vuelva a verificar los valores de -t y -e contra su archivo de reglas y el comando que Apidog generó en la pestaña CI/CD. Los ID en .windsurf/rules/apidog.md son la verdad.
Opcional: conectar el servidor MCP de Apidog
Ejecutar apidog run desde una regla cubre la mayor parte de lo que necesita. Para ir un paso más allá, conecte un servidor MCP.
Cascade es compatible con el Protocolo de Contexto de Modelo (MCP). Windsurf lee su lista de servidores de ~/.codeium/windsurf/mcp_config.json, que puede editar directamente o gestionar a través del panel MCP de Cascade; el formato está documentado en la referencia MCP de Windsurf, y cómo configurar servidores MCP en Windsurf explica el panel. El servidor MCP de Apidog expone sus especificaciones de API a través de MCP, para que Cascade pueda leer su esquema mientras escribe código, no solo después del hecho. La división del trabajo es clara: la CLI ejecuta las pruebas y MCP alimenta al agente con la especificación.
Cuando Windsurf se equivoca
Algunos fallos aparecen a menudo durante la configuración.
Ignora la regla. Si Cascade ejecuta un comando genérico o ninguno, es posible que la regla no se esté cargando. Confirme que el archivo reside en .windsurf/rules/ en la raíz de su repositorio y tiene una extensión .md. Cada archivo de reglas está limitado a 12,000 caracteres, así que mantenga el bloque de Apidog corto. Reiniciar Cascade fuerza una nueva lectura.
Pasa un token de acceso de todos modos. Si Cascade intenta añadir un token de acceso al comando, está adivinando a partir de ejemplos públicos. Su regla ya le dice que no lo haga, ya que la máquina está autenticada a través de apidog login. Refuerce la línea y nunca coloque un token real en un archivo de reglas que se vaya a commitear. Para saber cómo funciona realmente la autenticación, consulte la guía de autenticación de la CLI de Apidog.
Inventa una bandera. Un error de “opción desconocida” significa que Cascade adivinó una bandera que su versión no tiene. Dígale que ejecute apidog run --help y copie la bandera exacta de ahí, que siempre es correcta para su versión instalada.
Reporta un éxito en una ejecución fallida. El más costoso, y la razón por la que la regla del código de salida está tanto en su archivo de reglas como en su paso de verificación. Cuando el resumen y el código de salida no concuerdan, el código de salida es el que manda.
De un agente diario a un bucle probado
Esa es la configuración. Instale apidog-cli una vez siguiendo la guía de instalación, añada una regla corta de Apidog al directorio .windsurf/rules/ de su repositorio, y Cascade sabrá cómo ejecutar sus pruebas de API y leer el resultado dentro del mismo bucle que ya usa para editar código. Un endpoint roto es detectado mientras Cascade todavía está trabajando en el cambio, no después de que se despliegue.
Una prueba detrás de una GUI se ejecuta cuando un humano hace clic; un comando de una sola línea se ejecuta cuando Cascade decide hacerlo. Usted sigue construyendo escenarios visualmente en Apidog, y su agente los ejecuta donde usted no está mirando. Para ejecutar el mismo comando en una pipeline una vez que funciona localmente, la CLI de Apidog en GitHub Actions cubre los secretos, reporteros y el control de código de salida. Descargue Apidog, construya un escenario, coloque su comando apidog run en una regla de Windsurf, y observe cómo Cascade lo toma en el siguiente cambio.