Cómo configurar el Runner autoalojado de Apidog para pruebas API automatizadas

Su suite de pruebas de API solo es útil si se ejecuta en un horario en el que pueda confiar. Una colección que activa manualmente detecta errores cuando se acuerda de hacer clic. Una ejecución nocturna en una máquina que usted controla los detecta a las 2 a.m., antes que sus usuarios. Ese es el trabajo del runner de Apidog: un servicio autodesplegado, instalado con Docker en su propio servidor, que ejecuta los escenarios de prueba programados que construye en Apidog y envía los informes de vuelta a su proyecto.

Hemos cubierto las tres formas de programar pruebas en Apidog en nuestra guía para programar pruebas automatizadas de API. Esa publicación compara la ejecución en la nube, el runner y la CLI a un alto nivel. Esta es una inmersión profunda en la ruta del runner: cuándo lo necesita, cómo implementarlo, cómo dirigir una tarea programada hacia él y cómo se compara con las alternativas.

Cuándo necesita un test runner autoalojado

La ejecución en la nube es conveniente, pero tres situaciones empujan a los equipos hacia un test runner autoalojado.

Sus API viven en una red privada. Un entorno de staging en https://orders.staging.internal:8443 no se resuelve desde la internet pública. Ningún servicio en la nube puede alcanzarlo. Un runner desplegado dentro de su VPC o red de oficina sí puede, porque realiza solicitudes desde donde se encuentra. Este es el mismo razonamiento detrás de ejecutar un servidor mock autoalojado en su intranet: la carga de trabajo debe vivir donde está el acceso a la red.

El cumplimiento mantiene el tráfico interno. Si su equipo de seguridad prohíbe que las cargas útiles de prueba con datos de clientes realistas salgan de su infraestructura, la ejecución en la nube queda descartada. Con el runner, las solicitudes se originan en su servidor y acceden directamente a sus API. Solo los informes de prueba viajan de vuelta a Apidog.

Quiere horarios estables independientes de cualquier portátil. Las pruebas programadas dentro de la aplicación de escritorio se detienen cuando la aplicación se cierra. Las pruebas conectadas a CI se ejecutan cuando alguien sube código. Ninguna le da "cada 6 horas, para siempre, pase lo que pase". Un runner en un servidor siempre encendido hace exactamente esto.

Si ninguna de estas situaciones aplica, probablemente no necesita un runner. Las ejecuciones manuales en la aplicación o la CLI en CI le serán suficientes.

Qué es el runner de Apidog

El runner autoalojado es un servicio de automatización que usted implementa en un servidor independiente. Una vez conectado a su equipo, puede:

• Ejecutar tareas de prueba automatizadas programadas construidas a partir de sus escenarios de prueba de Apidog
• Importar documentación de API en un horario recurrente
• Servir respuestas mock autoalojadas

Viene en dos ámbitos. Un runner general a nivel de equipo pertenece a un solo equipo. Un runner a nivel de organización puede compartirse entre todos los proyectos de los equipos de su organización. La implementación funciona de la misma manera para ambos.

El modelo mental clave: el runner es un trabajador, no una copia de su proyecto. Sus escenarios de prueba, entornos y aserciones permanecen en Apidog. El runner recibe tareas, las ejecuta contra cualquier red que pueda alcanzar y sube los resultados. Los miembros del equipo nunca acceden por SSH para ver qué sucedió; abren el historial de ejecución en la aplicación.

Requisitos previos

Revise esto antes de implementar. Provienen directamente de la documentación del entorno de despliegue del runner.

Hardware. Mínimo 2 núcleos de CPU y 4 GB de RAM; se recomiendan 4+ núcleos y 8 GB si va a ejecutar tareas concurrentes o tiene un equipo más grande. Asigne al menos 30 GB de disco para logs y artefactos de prueba, 50 GB para estar cómodo.

Docker. El host necesita Docker versión 20.10.0 o posterior, con la 20.10.13 recomendada. Si el servidor es nuevo, siga primero la guía oficial de instalación de Docker Engine para su distribución.

Red. El runner se comunica con el servidor de Apidog a través de HTTPS en el puerto 443 y mantiene una conexión WebSocket (WSS) abierta para el envío de tareas en tiempo real. También necesita acceso saliente a los dominios de AWS utilizados para la carga de informes, además, obviamente, alcance de red a cada API que sus pruebas objetivo. Tenga en cuenta la dirección aquí: el runner realiza llamadas salientes. No necesita abrir puertos de entrada para que Apidog lo alcance, lo que hace que las conversaciones sobre firewalls con su equipo de operaciones sean breves.

Permisos y plan. Desplegar un runner es una acción de recurso de equipo, por lo que necesitará el rol de equipo apropiado. La cantidad de ejecuciones de tareas programadas que obtiene depende de su nivel de suscripción; consulte la página de precios de Apidog para conocer los límites actuales por plan.

Paso 1: obtenga el comando de despliegue de Apidog

Apidog genera el comando de despliegue de Docker para usted, con un token de autenticación incorporado. No copie uno de una publicación de blog, incluyendo esta; el token es lo que vincula el contenedor a su equipo.

1. Abra Apidog y vaya a la página de inicio de Apidog. Si aún no tiene una cuenta, descargue Apidog gratis para seguir los pasos.
2. Seleccione el equipo al que debe pertenecer el runner.
3. Haga clic en Resources en el lado derecho.
4. Haga clic en Deploy General Runner.

Una ventana emergente muestra el comando de despliegue completo. Cópielo inmediatamente: contiene un token sensible y se muestra solo una vez. Trátelo como un secreto de CI, no como un fragmento para el wiki de su equipo.

Antes de copiar, el diálogo le permite personalizar el comando:

• Sistema operativo del servidor: Linux, macOS o Windows.
• Variante de imagen: General se envía con Node.js 18, Java 21, Python 3 y PHP 8, por lo que los scripts de pre/post-procesamiento en esos lenguajes funcionan sin configuración adicional. Slim incluye solo Node.js 18 y se descarga más rápido. Custom le permite proporcionar su propio Dockerfile cuando las pruebas dependen de certificados CA internos o bibliotecas inusuales.
• Puerto expuesto: mapee uno con -p (por ejemplo, -p 80:4524) si también utilizará el runner para mocks autoalojados.
• Directorio de datos montado: agregue un montaje de volumen -v si sus escenarios de prueba leen archivos de datos locales, como conjuntos de datos CSV para ejecuciones basadas en datos.

La documentación del runner general cubre cada opción en detalle.

Paso 2: ejecute el contenedor y confirme que está conectado

Acceda por SSH al servidor de destino, pegue el comando y deje que Docker descargue la imagen e inicie el contenedor. Dos notas operativas que vale la pena configurar el primer día:

• Pase TZ como una variable de entorno (por ejemplo, TZ=Asia/Singapore) para que "todos los días a las 02:00" signifique sus 02:00, no el valor predeterminado del contenedor.
• A partir de la versión 2.2.5 del runner, la imagen incluye un usuario runner no root (UID/GID 10001). Si su plataforma impone runAsNonRoot, configure el contexto de seguridad en consecuencia y preconfigure los permisos de volumen, ya que el punto de entrada no puede cambiar la propiedad de los directorios en modo no root.

De vuelta en Apidog, el runner aparece en los Recursos de su equipo una vez que se completa el handshake de WebSocket, y los miembros del equipo pueden seleccionarlo al crear tareas. Si no aparece en un minuto, revise los logs del contenedor con docker logs y confirme que el host puede alcanzar el servidor de Apidog en el puerto 443; una conexión WSS bloqueada es la causa habitual en redes corporativas restringidas.

Puede desplegar varios runners en un mismo equipo. Los equipos suelen mantener uno dentro de la VPC de staging y otro con acceso de lectura a producción, y luego eligen por tarea.

Paso 3: cree una tarea programada dirigida al runner

Con el runner en línea, la programación es un formulario, no un script.

1. En su proyecto, abra el módulo Tests y haga clic en Scheduled Tasks. Las tareas viven en una estructura de carpetas, así que agrúpelas por servicio o entorno a medida que la lista crece.
2. Cree una tarea y dele un nombre que un compañero de equipo entienda en seis meses: "Smoke del servicio de pedidos, staging, cada 6h" es mejor que "prueba1".
3. Seleccione uno o más escenarios de prueba. Por escenario, puede configurar el entorno, los datos de prueba, el número de iteraciones, el retraso entre solicitudes y si desea guardar los cuerpos de las solicitudes/respuestas.
4. Configure el entorno y el alcance de las variables. Aplicar variables a todos los escenarios dentro de la tarea es el término medio recomendado; el alcance a nivel de carpeta es potente pero fácil de malinterpretar.
5. Configure el Run Cycle: cada domingo a las 11 p.m., cada 6 horas, lo que sea que coincida con la rapidez con la que necesita saber si algo se rompió.
6. En Runs on, elija su runner autoalojado por nombre.
7. Configure las notificaciones. Puede alertar después de cada ejecución o solo en caso de fallo. Solo en caso de fallo es el valor predeterminado sensato; un canal lleno de marcas verdes entrena a todos a ignorarlo.

Guárdelo. A partir de este punto, la programación se ejecuta en su servidor, independientemente de si alguien tiene la aplicación Apidog abierta.

Paso 4: lea los informes de ejecución en Apidog

Después de cada ejecución, el runner carga los resultados al servidor de Apidog automáticamente. Abra Scheduled Tasks → Run History en la aplicación para ver cada ejecución: estado de aprobado/fallido, resultados por escenario, fallos de aserción y tiempos.

Esta es la ventaja silenciosa del runner sobre una configuración casera de cron más scripts. La ejecución ocurre en su infraestructura, pero los informes aterrizan en el mismo espacio de trabajo compartido donde se definen las pruebas. Cuando la ejecución del martes a las 02:00 falla, el ingeniero de QA que investiga ve qué aserción falló en qué paso, en contexto, sin tener que buscar en los archivos de log de un servidor.

Combine las notificaciones de fallo con el historial de ejecución y tendrá un bucle de monitoreo: se dispara la alerta, se abre el informe, se reproduce el paso fallido manualmente en la aplicación contra el mismo entorno, se corrige y se espera la siguiente ejecución exitosa.

Runner vs CLI vs nube: eligiendo una ruta de ejecución

Apidog le ofrece tres formas de ejecutar pruebas más allá de un clic manual en la aplicación, y resuelven problemas diferentes. Hemos escrito un recorrido completo de la ruta CI en nuestra guía de Apidog CLI para GitHub Actions, y la comparación a continuación muestra dónde encaja cada uno.

Las rutas se complementan en lugar de competir. Una configuración común: la CLI protege cada despliegue en el pipeline, mientras que el runner ejecuta una suite de humo cada hora contra el entorno de staging y una regresión completa nocturna, detectando los fallos causados por la deriva de la infraestructura y las credenciales caducadas en lugar de los cambios de código.

Una advertencia sobre los tiempos: según la documentación de tareas programadas, las tareas programadas están diseñadas para ejecutarse en un runner autoalojado, con Apidog Cloud seleccionable a medida que la disponibilidad se implementa. Si necesita ejecución programada hoy y no puede esperar la disponibilidad en la nube para su plan, el runner es la ruta fiable.

Preguntas frecuentes

¿Necesito el runner si ya uso Apidog CLI en CI?

Responden a preguntas diferentes. CI le dice "¿este cambio rompió la API?" en el momento del push. El runner le dice "¿la API está saludable ahora mismo?" en un ciclo fijo, detectando fallos causados por tokens caducados, dependencias muertas o deriva de la infraestructura sin un commit asociado. Muchos equipos ejecutan ambos; consulte nuestra guía de configuración de pruebas de API nocturnas para la mitad programada por CI del patrón.

¿Puede el runner alcanzar APIs de intranet?

Sí, y esta es su principal razón de ser. El runner realiza solicitudes desde la máquina en la que está desplegado. Colóquelo dentro de su VPC o red de oficina y podrá probar hosts *.internal que ningún servicio en la nube puede resolver. Solo necesita acceso HTTPS y WebSocket saliente al servidor de Apidog para recibir tareas y subir informes.

¿Cuáles son las especificaciones mínimas del servidor?

Dos núcleos de CPU, 4 GB de RAM, 30 GB de disco y Docker 20.10.0 o posterior. Para equipos que ejecutan tareas programadas concurrentes, pase a 4+ núcleos y 8 GB. Una VM pequeña o una caja de sobra en el rack de la oficina funcionan; la restricción es el tiempo de actividad, no la potencia.

¿Qué plan necesito para tareas programadas en un runner autoalojado?

Las cuotas de ejecución de tareas programadas varían según el nivel de suscripción, así que consulte los límites actuales en la página de precios de Apidog antes de planificar un horario de alta frecuencia. Si está evaluando opciones de ejecución entre herramientas, nuestra comparación de Apidog CLI vs Postman CLI analiza lo que incluye la parte del test-runner de cada plataforma.