DEV Community

Cover image for Cómo usar Apidog CLI en Windsurf
Roobia
Roobia

Posted on • Originally published at apidog.com

Cómo usar Apidog CLI en Windsurf

El agente Cascade de Windsurf puede editar archivos, ejecutar comandos, leer resultados y decidir el siguiente paso. Para integrar sus pruebas de API en ese mismo ciclo, ejecute los escenarios de Apidog mediante apidog-cli desde la terminal: Cascade podrá detectar fallos por el código de salida y corregir el código antes de terminar la tarea.

Prueba Apidog hoy

La CLI de Apidog es el paquete npm apidog-cli. Una vez instalada y autenticada, Cascade puede ejecutar un escenario igual que ejecuta pruebas unitarias:

apidog run -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

Antes de continuar, confirme que la CLI está lista:

apidog --version
Enter fullscreen mode Exit fullscreen mode

También debe haber iniciado sesión con apidog login. Si necesita configurar la CLI desde cero, siga cómo instalar la CLI de Apidog con un agente de codificación de IA.

Qué componente de Windsurf usará

Windsurf es el IDE agéntico de Codeium y Cascade es su agente integrado. Cascade trabaja localmente: lee el repositorio, modifica archivos y ejecuta comandos en la terminal integrada según la configuración de aprobación y autoejecución.

Si todavía no tiene Windsurf configurado, consulte cómo descargar e instalar Windsurf.

El objetivo es darle a Cascade una instrucción persistente para que ejecute sus escenarios de Apidog después de cambios que afecten a la API.

Paso 1: Crear una regla de Apidog para Cascade

Cascade carga reglas de proyecto desde archivos Markdown ubicados en:

.windsurf/rules/
Enter fullscreen mode Exit fullscreen mode

Cree este archivo en la raíz de su repositorio:

.windsurf/rules/apidog.md
Enter fullscreen mode Exit fullscreen mode

Añada una regla como esta:

# 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.
Enter fullscreen mode Exit fullscreen mode

Use una regla versionada en Git en lugar de escribir el comando en un chat puntual. Así, todos los miembros del equipo y cada sesión nueva de Cascade reciben la misma instrucción.

Windsurf también admite un archivo heredado .windsurfrules en la raíz y reglas globales en ~/.codeium/windsurf/memories/global_rules.md, pero para una regla específica del repositorio use .windsurf/rules/. Consulte la referencia de reglas y memorias de Windsurf.

Paso 2: Copiar el comando real desde Apidog

No adivine los valores de <scenario_id> y <env_id>.

  1. Abra el escenario de prueba en Apidog.
  2. Vaya a la pestaña CI/CD.
  3. Copie el comando apidog run generado por Apidog.
  4. Reemplace la línea de ejemplo en .windsurf/rules/apidog.md.

El comando generado ya incluye el ID de escenario, el ID de entorno y las opciones de reportero correspondientes. Por ejemplo:

apidog run -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

Para revisar la sintaxis y las banderas disponibles, consulte la referencia del comando apidog run.

Paso 3: Pedir a Cascade que ejecute el escenario

Abra Cascade dentro del repositorio. Al iniciarse, debería cargar .windsurf/rules/apidog.md.

Puede pedir una ejecución explícita:

Ejecuta el escenario de Apidog y dime el código de salida.
Enter fullscreen mode Exit fullscreen mode

O bien, haga un cambio que modifique el comportamiento de la API y pida a Cascade que valide el resultado antes de finalizar.

El comportamiento de ejecución depende de la configuración de autoejecución de Windsurf:

  • Deshabilitado: cada comando requiere aprobación.
  • Solo lista de permitidos: solo se ejecutan automáticamente los comandos permitidos.
  • Auto: el modelo decide cuándo ejecutar.
  • Turbo: ejecuta automáticamente salvo comandos denegados.

Para permitir apidog run sin habilitar todos los comandos, añada apidog a:

windsurf.cascadeCommandsAllowList
Enter fullscreen mode Exit fullscreen mode

La lista de denegación correspondiente es:

windsurf.cascadeCommandsDenyList
Enter fullscreen mode Exit fullscreen mode

Si un comando coincide con ambas listas, la lista de denegación tiene prioridad. Consulte la documentación del terminal de Windsurf.

Paso 4: Usar el resultado para corregir fallos

El reportero cli muestra el resultado directamente en la terminal de Cascade:

apidog run -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

Cuando una prueba falla, Cascade puede usar la salida para identificar:

  • La solicitud que falló.
  • La aserción concreta.
  • El código de estado esperado y recibido.
  • Campos ausentes o valores incorrectos.

El código de salida debe controlar la decisión:

  • 0: todas las aserciones pasaron.
  • Distinto de 0: al menos una aserción falló.

Para conservar la salida en terminal y generar un informe navegable, use ambos reporteros:

apidog run -t <scenario_id> -e <env_id> -r cli,html
Enter fullscreen mode Exit fullscreen mode

El reportero html escribe un informe autocontenido en:

./apidog-reports
Enter fullscreen mode Exit fullscreen mode

Mantenga cli para que Cascade pueda leer el resultado durante la ejecución. Para más formatos, incluido JUnit, consulte la guía completa de la CLI de Apidog y cómo leer los informes de prueba de la CLI de Apidog.

Integrar pruebas de API en el ciclo de Cascade

Con la regla configurada, el flujo de trabajo pasa a ser:

  1. Cascade modifica un controlador, servicio o endpoint.
  2. Ejecuta el escenario de Apidog contra el entorno de prueba.
  3. Lee el código de salida y la salida del reportero.
  4. Si el resultado es verde, continúa.
  5. Si el resultado es rojo, revisa la aserción fallida, aplica una corrección y vuelve a ejecutar.

Por ejemplo, si Cascade cambia un manejador de pagos y el escenario devuelve un campo incorrecto o un código HTTP inesperado, el fallo queda visible mientras el agente sigue trabajando en el cambio.

Usted mantiene el control sobre los escenarios visuales en Apidog; Cascade ejecuta el comando y actúa según resultados verificables. Para profundizar en este patrón, consulte cómo usar agentes de IA para pruebas de API y el arnés de pruebas de IA de Apidog.

Verificar que Cascade ejecutó la CLI

No se limite al resumen del agente. Verifique la ejecución en este orden.

1. Confirme el comando ejecutado

En la terminal de Cascade, busque la línea real:

apidog run ...
Enter fullscreen mode Exit fullscreen mode

También debe aparecer la salida del comando debajo. Si Cascade afirma que ejecutó pruebas pero no hay comando ni salida, pídale que lo ejecute de nuevo y muestre la salida sin procesar.

2. Confirme el código de salida

Pregunte directamente:

¿Cuál fue el código de salida de ese comando apidog run?
Enter fullscreen mode Exit fullscreen mode

Un resultado textual que diga “las pruebas pasaron” no invalida un código de salida distinto de cero. El código de salida es la señal fiable para Cascade y para una pipeline de CI.

3. Confirme los IDs de escenario y entorno

Si aparece un error como “escenario no encontrado”, compare los argumentos -t y -e con:

  • El comando generado en la pestaña CI/CD de Apidog.
  • El comando almacenado en .windsurf/rules/apidog.md.

Ese archivo debe contener el comando real del proyecto, no una plantilla.

Opcional: conectar el servidor MCP de Apidog

La regla con apidog run cubre la ejecución de pruebas. Si también quiere que Cascade consulte la especificación mientras genera código, conecte un servidor MCP.

Windsurf admite el Protocolo de Contexto de Modelo (MCP) y lee la configuración desde:

~/.codeium/windsurf/mcp_config.json
Enter fullscreen mode Exit fullscreen mode

Puede editar el archivo directamente o usar el panel MCP de Cascade. Consulte la referencia MCP de Windsurf y cómo configurar servidores MCP en Windsurf.

El servidor MCP de Apidog expone especificaciones de API mediante MCP. La división de responsabilidades es simple:

  • CLI de Apidog: ejecuta escenarios y devuelve resultados.
  • MCP de Apidog: proporciona contexto de la especificación a Cascade.

Solución de problemas

Cascade ignora la regla

Compruebe que el archivo:

  • Está en .windsurf/rules/.
  • Tiene extensión .md.
  • Se encuentra en la raíz del repositorio abierto en Windsurf.

Cada archivo de reglas tiene un límite de 12 000 caracteres. Mantenga la regla corta y reinicie Cascade para forzar una nueva carga.

Cascade añade un token de acceso

La autenticación debe estar resuelta previamente con:

apidog login
Enter fullscreen mode Exit fullscreen mode

No incluya tokens en la regla ni permita que Cascade los añada al comando. Refuerce esta instrucción en .windsurf/rules/apidog.md.

Para revisar el flujo de autenticación, consulte la guía de autenticación de la CLI de Apidog.

Cascade inventa una bandera

Si recibe un error de opción desconocida, ejecute:

apidog run --help
Enter fullscreen mode Exit fullscreen mode

Use únicamente las opciones disponibles en la versión instalada de la CLI.

Cascade reporta éxito aunque la ejecución falló

Priorice siempre el código de salida. Si el resumen de Cascade contradice un código distinto de cero, considere la ejecución como fallida y revise el informe.

Convertir una prueba manual en una verificación automática

La configuración final es corta:

  1. Instale apidog-cli.
  2. Autentique la máquina con apidog login.
  3. Copie el comando de CI/CD generado por Apidog.
  4. Guárdelo en .windsurf/rules/apidog.md.
  5. Indique a Cascade que ejecute el escenario después de cambios en la API.
  6. Use el código de salida como criterio de éxito o fallo.

De este modo, una prueba que antes dependía de que alguien hiciera clic en una GUI pasa a formar parte del ciclo editar-probar-corregir de Cascade.

Siga creando y manteniendo escenarios visualmente en Apidog, y ejecute el mismo comando en CI cuando funcione localmente. Para integrar la CLI en una pipeline, consulte la CLI de Apidog en GitHub Actions. También puede descargar Apidog, crear un escenario y añadir su comando apidog run a una regla de Windsurf.

Top comments (0)