Trae funciona en un bucle: su agente Builder lee tu repositorio, edita archivos, ejecuta comandos en el terminal y analiza la salida para decidir qué hacer después. Entonces, ¿por qué tus pruebas de API siguen aisladas en una GUI de Apidog y solo se ejecutan cuando alguien recuerda hacer clic? Si el agente no puede ejecutarlas, no forman parte de su ciclo de validación.
La solución es configurar la CLI de Apidog. El paquete npm apidog-cli ejecuta desde el terminal los escenarios de prueba que creaste en Apidog. Cuando la CLI está instalada y Trae conoce el comando correcto, Builder puede ejecutar un escenario de Apidog igual que ejecuta tus pruebas unitarias: lanza el comando, revisa el código de salida y corrige el código si la ejecución falla.
Si todavía no instalaste la CLI, empieza por ahí. Cómo instalar la CLI de Apidog con un agente de codificación de IA cubre la instalación con npm, la autenticación y la primera ejecución. Este artículo asume que apidog --version muestra una versión y que tu cuenta de Apidog ya está autenticada.
De qué Trae hablamos
Trae es el IDE de IA de ByteDance, basado en VS Code, con un modo de agente llamado Builder que puede editar archivos y ejecutar comandos de terminal. Puedes consultar los detalles del producto en el sitio oficial de Trae.
Este artículo trata sobre el IDE de escritorio, no sobre el proyecto de investigación independiente trae-agent en GitHub. Si en Trae ves un panel de chat junto al editor y puedes seleccionar el agente Builder, estás usando la herramienta correcta.
La distinción importa porque Trae puede cargar reglas del proyecto antes de que Builder empiece a trabajar. Ese mecanismo convierte una instrucción puntual como “ejecuta mis pruebas” en una regla persistente para cada sesión del agente.
Si quieres una guía independiente de Trae, consulta la guía completa de la CLI de Apidog.
Paso 1: Añadir el archivo de reglas del proyecto
Trae lee los archivos de reglas antes de que Builder empiece a trabajar. Según la documentación de reglas de Trae, el archivo de reglas a nivel de proyecto está en:
.trae/rules/project_rules.md
Builder carga estas reglas durante la inicialización y las usa mientras genera o modifica código. También existe un archivo global llamado user_rules.md, pero para este flujo basta con una regla dentro del repositorio.
Crea el archivo .trae/rules/project_rules.md y añade un bloque como este:
## Pruebas de API con la CLI de Apidog
Cuando cambies código que afecte a un endpoint de API, verifícalo ejecutando el
escenario de prueba de Apidog, no solo las pruebas unitarias.
Comando:
apidog run -t <scenario_id> -e <env_id> -r cli
Reglas:
- `apidog run` sale con 0 cuando todas las aserciones pasan y distinto de cero en cualquier fallo.
Considera un código de salida distinto de cero como una prueba fallida, incluso si el resumen parece correcto.
- Esta máquina ya está autenticada a través de `apidog login`. Nunca añadas un
flag --access-token y nunca coloques un token en este archivo.
- Si un flag es desconocido, ejecuta `apidog run --help` y usa el flag exacto de allí.
Guarda el comando en project_rules.md en lugar de escribirlo solo en el chat. Un ID de escenario enviado al panel desaparece al terminar la sesión; una regla en el repositorio queda disponible para el equipo y para futuras ejecuciones de Builder.
En un monorepo, Trae también puede leer carpetas .trae/rules/ dentro de subdirectorios. Esto permite definir reglas específicas para cada servicio.
Paso 2: Obtener el comando de Apidog
No inventes manualmente los IDs del escenario o del entorno.
- Abre el escenario de prueba en Apidog.
- Ve a la pestaña CI/CD.
- Copia el comando
apidog rungenerado. - Pégalo en
.trae/rules/project_rules.md.
El comando generado ya incluye:
- El ID del escenario después de
-t. - El ID del entorno después de
-e.
Reemplaza los marcadores <scenario_id> y <env_id> por esos valores reales:
Comando:
apidog run -t 123456 -e 789012 -r cli
Para revisar todos los flags disponibles, consulta la referencia del comando apidog run.
Paso 3: Hacer que Builder ejecute la prueba
Con las reglas configuradas:
- Abre tu repositorio en Trae.
- Cambia el agente a Builder.
- Haz un cambio que afecte a un endpoint de API.
- Pide al agente que ejecute la comprobación.
Por ejemplo:
Ejecuta el escenario de prueba de Apidog y dime el código de salida.
Builder cargará project_rules.md durante la inicialización y podrá usar el comando configurado.
El modelo de aprobación de Trae importa aquí: cuando Builder quiere ejecutar un comando de shell, propone el comando y muestra el botón Ejecutar. El comando se ejecuta en el terminal de Trae después de tu aprobación. Una vez ejecutado, Builder analiza la salida automáticamente.
Con -r cli, la CLI imprime el resultado paso a paso y un resumen en el terminal. Builder puede leer cada solicitud, cada aserción y el código de salida.
Paso 4: Leer el informe dentro de Trae
Cuando una ejecución falla, el informe contiene los datos necesarios para diagnosticarla. Con -r cli, Builder recibe en el terminal:
- Cada solicitud ejecutada.
- Cada aserción evaluada.
- La aserción que falló.
- El valor esperado y el valor recibido.
- El código de salida del comando.
Por ejemplo, el fallo puede indicar un código de estado inesperado, un campo ausente o un valor incorrecto. Esa información suele ser suficiente para que Builder localice el cambio necesario en el código.
Si también necesitas un informe que puedas abrir en el navegador o compartir con el equipo, añade el reportero HTML:
apidog run -t <scenario_id> -e <env_id> -r cli,html
El reportero html genera un archivo autocontenido en:
./apidog-reports
Mantén cli en la lista de reporteros. Builder necesita la salida en línea para decidir su siguiente acción.
Para los demás reporteros, incluidos JSON y JUnit para CI, consulta la guía de informes de prueba de la CLI de Apidog.
Pruebas de Trae dentro de su propio bucle
El valor real aparece cuando Builder deja de necesitar una instrucción manual para ejecutar el escenario. Si project_rules.md indica que debe validar los cambios de API, esa prueba pasa a formar parte de su flujo normal.
El ciclo queda así:
- Builder modifica un manejador, servicio o endpoint.
- Ejecuta el escenario de Apidog contra el entorno configurado.
- Lee el código de salida.
- Si el resultado es
0, continúa. - Si el resultado es distinto de
0, revisa la aserción fallida. - Ajusta el código y vuelve a ejecutar la prueba.
La prueba de API se integra en el mismo ciclo de editar, probar y corregir que Builder ya utiliza para pruebas unitarias.
Este enfoque sigue un modelo de delegar y verificar: Builder ejecuta el comando y analiza el resultado, mientras tú mantienes los escenarios visualmente en Apidog y verificas que el agente respete los códigos de salida.
Para ampliar este patrón, consulta cómo usar agentes de IA para pruebas de API y el arnés de pruebas de IA de Apidog.
Verifica que Trae realmente está ejecutando la CLI
Un agente puede informar un éxito sin haber ejecutado el comando esperado. Verifica estos tres puntos.
1. Confirma que el comando se ejecutó
Trae muestra los comandos ejecutados por Builder y su salida en el terminal. Busca una línea literal como esta:
apidog run ...
Debe haber una salida inmediatamente después. Si Builder afirma que ejecutó las pruebas pero no ves el comando, pide que lo ejecute de nuevo y que muestre la salida completa.
2. Confirma el código de salida
Pregunta explícitamente:
¿Cuál fue el código de salida de ese comando apidog run?
apidog run devuelve:
-
0cuando todas las aserciones pasan. - Un valor distinto de
0cuando ocurre algún fallo.
Si el texto de Builder dice que las pruebas pasaron, pero el código de salida no es 0, el código de salida es la fuente de verdad.
3. Confirma que usó el escenario correcto
Si aparece un error como “escenario no encontrado”, Builder puede haber usado un ID inventado o incorrecto.
Compara los valores de:
-t <scenario_id>
-e <env_id>
con:
- El contenido de
.trae/rules/project_rules.md. - El comando generado por Apidog en la pestaña CI/CD.
Los IDs guardados en tu archivo de reglas deben ser la referencia.
Opcional: Conectar el servidor MCP de Apidog
Ejecutar apidog run desde project_rules.md cubre la validación de pruebas. Un servidor MCP añade otra capacidad: permite que Builder consulte herramientas y datos expuestos por ese servidor.
Los agentes de Trae pueden actuar como clientes MCP. Para añadir un servidor:
- Abre la configuración de Trae.
- Ve a la pestaña MCP.
- Elige un servidor del marketplace o selecciona Añadir manualmente.
- Pega la configuración JSON del servidor con
command,argsyenv.
Consulta la guía de Trae para añadir servidores MCP para el formato de configuración.
El servidor MCP de Apidog expone las especificaciones de tu API mediante MCP. La separación de responsabilidades es directa:
- La CLI ejecuta los escenarios de prueba.
- MCP proporciona la especificación de API mientras Builder escribe código.
Cuando Trae se equivoca
Estos son los problemas más comunes durante la configuración.
Builder ignora el archivo de reglas
Si Builder ejecuta un comando genérico o no ejecuta ninguno, confirma que el archivo existe exactamente en:
.trae/rules/project_rules.md
Verifica también que la carpeta se llama rules, no rule. Reiniciar la sesión de Builder fuerza una nueva carga de las reglas.
Builder añade un token de acceso
Si Builder intenta usar --access-token, probablemente está reproduciendo ejemplos públicos. Refuerza esta regla:
Esta máquina ya está autenticada a través de `apidog login`.
Nunca añadas `--access-token` ni guardes tokens en este archivo.
No incluyas tokens reales en project_rules.md. Para entender el manejo de credenciales en uso interactivo y CI, consulta la guía de autenticación de la CLI de Apidog.
Builder inventa un flag
Un error de “opción desconocida” indica que el agente usó un flag no disponible en tu versión instalada.
Pídele que ejecute:
apidog run --help
Después, debe usar exactamente el flag mostrado por la ayuda de esa versión.
Builder informa éxito tras una ejecución fallida
Este es el error más costoso. Por eso la regla sobre el código de salida debe estar tanto en project_rules.md como en tu proceso de revisión.
Si el resumen textual y el código de salida no coinciden, el código de salida gana.
De un agente diario a un bucle probado
La configuración es breve:
- Instala
apidog-clisiguiendo la guía de instalación. - Añade el comando de tu escenario a
.trae/rules/project_rules.md. - Indica que Builder debe ejecutar la prueba cuando modifique endpoints.
- Haz que trate cualquier código de salida distinto de
0como un fallo.
Con esto, Builder puede ejecutar tus pruebas de API y leer el resultado dentro del mismo ciclo que ya usa para modificar código. Un endpoint roto se detecta mientras el agente sigue trabajando en el cambio, no después del despliegue.
Una prueba detrás de una GUI depende de que un humano haga clic. Un comando de una línea puede formar parte del flujo de trabajo del agente. Sigue creando escenarios visualmente en Apidog, añade su comando apidog run a .trae/rules/project_rules.md y deja que Builder lo ejecute en el siguiente cambio.
Descarga Apidog, crea un escenario e intégralo en las reglas de tu proyecto. Cuando quieras ejecutar ese mismo escenario sin un agente presente, consulta la guía de la CLI de Apidog en GitHub Actions, que cubre secretos, reporteros y validación de códigos de salida para CI.
Top comments (0)